Using the Cicero API to Promote and Filter Civic Engagement
Author: Tee O.
Within the tech space, there has been a growing interest in how we can use technology to enhance the relationship between government and people and drive change for social good.
Formally known as Civic Tech, tons of technologies have been created for the purpose of helping citizens stay informed and get involved within government.
If you’re looking to create a project that promotes civic engagement by connecting users to their legislative officials, look no further than the Cicero API. In this post I'm going to introduce you to the Cicero API and its official resource. We will explore how we can use Cicero to implement civic engagement at the local level by walking through an open-source web app called Amplify, a civic tech project that uses Cicero to help its users streamline the process of lobbying public officials.
CICERO API: AN OVERVIEW
Cicero(link to doc) is a Civic Data API that allows you to identify the government districts and officials associated with a given location or address. It provides local, state, and national data for governing bodies across the United States and other western countries(link to database availability doc). With the Cicero API you are able to easily receive information about a location's legislative and non-legislative districts and track the elected officials that govern within those regions.
As stated within the documentation, some common use cases for the API include:
- Showing elected official profiles in your application
- Displaying district boundaries on a map
- Creating constituent records within your database
- Providing a lookup tool for elected officials
There are four resources(link to doc) within the API that serve these various purposes. We will be focusing on the official resource as it is the part of the API that can be used to connect users to legislators, an essential part spurring civic action.
USING CICERO TO DRIVE CIVIC ENGAGEMENT
The Amplify project allows users to send letters to public officials on the campaigns that matter most to them. Amplify is currently using cicero to implement the last use case by providing users a means to lookup and filter through the elected officials within their region. This is done using the official resource endpoint.
[gif of the application in action]
Deep Dive into the ‘Official’ Resource
Finding information about the officials who govern a certain region is really easy with Cicero’s official resource. The resource allows you to query officials by location via the endpoint shown below.
The returned value is a list of officials who match that particular location. The API captures each official's information within what they call an official object(link to doc). The object contains information that users can use to identify each legislator such as their social media handle, office address, headshot photo, and more.
You are also able to filter results according to the level of government that the officials are involved in. The API allows you to add filters to your query by passing in a district type value which returns a subset of officials according to their government level, whether that’s national government, state government etc.
Here are some legislative district values you can pass in:
- NATIONAL_EXEC - Members of the executive branch of national gov
- NATIONAL_UPPER - Members of the upper legislative branch of national gov ( i.e. The Senate)
- STATE_EXEC - Members of the executive branch of state gov
- STATE_LOWER - Members of the lower legislative branch of state gov (i.e. The House of Delegates)
- LOCAL - Members of city/county level legislature
Filtering Officials in Amplify
Within the Amplify project, Cicero provides the tools to implement the government level filtering that we need to make it easier for users to find the officials that they would like to lobby.
On the front-end of the application we’ve defined a form that takes in a zipcode as well as filter buttons that allow users to specify the type of officials they would like to see
Selecting a filter button has the effect of passing a filtering parameter along with the request to the backend of our application.
When the backend receives this request, the desired filter is processed via what we’ve defined as a jurisdiction map which spits out the correct district_type values to send into the API
{
federal: ['NATIONAL_UPPER', 'NATIONAL_LOWER'],
state: ['STATE_EXEC', 'STATE_UPPER', 'STATE_LOWER'],
local: ['LOCAL_EXEC','LOCAL'],
county: ['COUNTY'],
school: ['SCHOOL']
}]
The results from the API are then sent back to the front-end where the legislator’s name, title, image, and social media handles are displayed to the user. The office address of each official is stored as a reference for where to send the letter.
Using the official endpoint in combination with the district_type filter you are able to easily create a feature where users are not only able to look up public officials in their area, but also contact them either by mail or via social media.
Edge Cases and Potential Solutions
When using legislative district values such as the ones I mention above (e.g. NATIONAL_EXEC, LOCAL) , results are consistently returned. However there were some issues using the district_type filter for non-legislative district types. The non-legislative(link to doc) district type values such as COUNTY and SCHOOL, rarely track officials and are consistently not returning any results. I have tested these two filter values across different US zip codes and haven't seen any officials appear. It is possible that they may track officials for some zip codes, but it seems like it's more likely to be no than yes.
This being said, if you’re looking to specify more local jurisdictions to display school and county level officials, you might need to implement your own special filter on the results that isolates officials with those keywords within their title. Or if you know in advance the areas or officials that you are targeting, you can code in placeholders to be displayed when no matching representatives have been returned.
Conclusion
Hopefully now you have a better understanding of the Cicero API and how you can use it to connect users to their legislators! If you would like to test out the ‘official’ endpoint within the API for yourself, you can do so by forking this postman collection:
Just add in your Cicero API key and start sending requests! You can register for a key here.
Otherwise, here are some resources you can use to further explore Cicero, Civic Tech, and The Amplify Project!
- Civic Tech Field Guide - https://civictech.guide/graveyard/
- Amplify Repository - https://github.com/ProgramEquity/amplify
- Cierco API Documentation - https://cicero.azavea.com/docs/
- Cicero Blog - https://medium.com/cicero-data
Top comments (0)