NAV Navbar
shell python javascript
  • Introduction
  • Credits
  • Root URL
  • Authentication
  • Responses
  • Location Queries
  • Officials
  • Legislative Districts
  • Non-Legislative Districts
  • Maps
  • Election Events
  • Account Status
  • District Types
  • API Version
  • Response Objects
  • Help & Support
  • Introduction

    This documentation shows example API calls using the command line tool curl, the Python library requests, and the Node.js package request. To get started:

    $ curl --help
    
    import requests
    
    var request = require('request');
    

    Examples in this documentation use {api_key} in place of your actual Cicero API Key. Refer to Authentication for more information about adding credentials to your API calls.

    The Cicero API is a web service that matches addresses or locations to legislative districts and returns contact information for elected officials. Check the Cicero Database Availability document for current national, regional, and local coverage.

    Things you might want to use the Cicero API for:

    Sign up for a free trial and read below to start using the API.

    This documentation describes the Cicero API v3.1.

    Credits

    Using the Cicero API costs one credit per call to each of these resources:

    The Cicero Dashboard is where you'll monitor your Cicero account. Use calls to the free usage and credits_remaining resources to programmatically access this information.

    You can add more credits on the Purchase Credits page.

    Root URL

    Root URL:

     https://cicero.azavea.com/v3.1
    

    The base URL for all requests to the Cicero API is https://cicero.azavea.com/v3.1.

    All calls to resources described below should start with this base URL and are only accessible over HTTPS.

    Authentication

    There are two possible ways you can authenticate with the Cicero API:

    1. API Key authentication
    2. User ID and temporary Token authentication

    These credentials allow access to the Cicero API and calls made with these credentials will use your credits.

    API Key

    The My Profile page is where you'll update your account information and generate an API Key. The API key will give you access to Cicero's API resources.

    With an API Key, format your authenticated calls as:

    /{resource}?key={api_key}

    User ID and Token

    Endpoint:

    POST https://cicero.azavea.com/v3.1/token/new.json
    

    Example API Call:

    $ curl -X POST \
        -H "Content-Type: application/x-www-form-urlencoded" \
        -d "username={username}&password={password}" \
        "https://cicero.azavea.com/v3.1/token/new.json"
    
    username = 'username' # Replace with your username
    password = 'password' # Replace with your password
    
    response = requests.post(
        'https://cicero.azavea.com/v3.1/token/new.json', 
        headers = { 'Content-Type': 'application/x-www-form-urlencoded' },
        data = 'username=' + username + '&password=' + password)
    
    data = response.json()
    
    if data['success']:
        user = data['user']
        token = data['token']
        print(user, token)
    else:
        errors = data['errors']
        print(errors)
    
    var username = 'username', // Replace with your username
        password = 'password'; // Replace with your password
    
    request.post({
        url: 'https://cicero.azavea.com/v3.1/token/new.json',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: 'username=' + username + '&password=' + password
      }, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.success) {
          var user = data.user,
              token = data.token;
          console.log(user, token);
        } else {
          console.log(data.errors);
        }
      });
    

    Response Structure:

    {
      "token": string,
      "user": number,
      "success": boolean
    }
    

    Call for a temporary token and user ID from the /token/new.json endpoint.

    With the response from this resource, you can format your authenticated calls as:

    /{resource}?user={user_id}&token={token}

    Tokens are valid until the end of the following day, Universal Coordinated Time (UTC). For example, if it is Tuesday at 7 p.m. EDT (23:00 UTC), the token will be valid through Wednesday at 8 p.m. EDT (Thursday 00:00 UTC).

    Setup your application to handle expiring tokens by calling for a new token whenever Cicero returns a 403 Forbidden HTTP response code. Then, try the call again.

    Responses

    An HTTP request to one of the Cicero API resources returns a response with a specific format and structure.

    The response is also delivered with Cicero specific headers.

    Format

    API responses can be returned in either XML or JSON format.

    The default format is XML.

    Specify your preference with either a query parameter or a Content-Type request header.

    For example, use the format parameter to receive JSON output:

    /{resource}?format=json

    Structure

    Response Structure:

    {
      "response": {
        "errors": [],
        "messages": [],
        "results": {}
      }
    }
    

    The API response is wrapped in a response object containing errors, messages, and results.

    A successful API call includes a set of objects within results.

    Headers

    Example Response Header:

    x-cicero-credit-balance: 831
    

    Each response that uses a credit has a header called X-Cicero-Credit-Balance, which is the total number of credits that are left on your account.

    If you have overdrafted your account, your balance will be a negative value. You can add credits to your account on the Purchase Credits page.

    Location Queries

    The primary way to get information from Cicero's database of officials and districts is through a location query.

    When you include API call parameters that provide a location in the form of a latitude & longitude coordinate, street address, or postal code, Cicero will find that location on the Earth's surface and match it against a range of district boundaries. In this way, you can determine which elected official represents any home, business, or place in regions with Cicero coverage.

    Responses for these location queries can also be filtered by the type of district.

    Latitude & Longitude

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/official/?lat=39.961&lon=-75.154&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/official/?lat=39.961&lon=-75.154&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        officials = data['response']['results']['officials']
        print(officials)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/official/?lat=39.961&lon=-75.154&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var officials = data.response.results.officials;
          console.log(officials);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Response Structure

    {
      "response": {
        "errors": [],
        "messages": [],
        "results": {
          "count": {
            "to": number,
            "total": number,
            "from": number
          },
          "officials": [
            ... official objects ...
          ]
        }
      }
    }
    

    A location query with a latitude and longitude coordinate pair requires two parameters:

    Parameter Description
    lat The latitude of the location.
    lon The longitude of the location.

    The response will list objects with boundaries, or constituent boundaries, that contain the coordinate location.

    Using an exact latitude and longitude coordinate is more accurate than geocoding with a street address or postal code.

    Address

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/legislative_district?search_loc=990+spring+garden+st+philadelphia+pa&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/legislative_district?search_loc=990+spring+garden+st+philadelphia+pa&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        districts = data['response']['results']['candidates'][0]['districts']
        print(districts)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/legislative_district?search_loc=990+spring+garden+st+philadelphia+pa&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var districts = data.response.results.candidates[0].districts;
          console.log(districts);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Response Structure

    {
      "response": {
        "errors": [],
        "messages": [],
        "results": {
          "candidates": [
            {
              "count": {
                "to": number,
                "total": number,
                "from": number
              },
              "districts": [
                ... district objects ...
              ],
              "match_postal": string,
              "wkid": number,
              "match_country": string,
              "locator": string,
              "score": number,
              "match_region": string,
              "match_city": string,
              "match_addr": string,
              "y": number,
              "x": number,
              "match_subregion": string,
              "partial_match": boolean,
              "geoservice": string
            },
            ...
          ]
        }
      }
    }
    

    A location query with a street address uses a geocoding service to translate that information to a latitude and longitude coordinate, then matches the location to Cicero's district boundaries.

    Use the search_loc parameter to search for an address as a single string or use a parameter for each of the address components.

    Searching with a single address string:

    Parameter Description
    search_loc One line address or a single search string.

    Searching with multiple address components:

    Parameter Description
    search_address The street address of the location.
    search_neighborhood The official neighborhood of the location (in countries with postal designations e.g., Mexico).
    search_city The city of the location.
    search_state The state of the location.
    search_postal The postal code of the location.
    search_country The country of the location (Use ISO 3166-1 alpha-2 code).

    The response will include a list of candidate locations for the provided address. An address that is vague or an address that could refer to more than one place will have multiple candidate locations. The location that is most likely to be correct is listed first.

    Each candidate location object includes metadata about the geocoding match and a list of objects with boundaries, or constituent boundaries, that contain the geocoded address location.

    Using a street address is less accurate than using a latitude and longitude coordinate, but more accurate than using only a postal code.

    If a location query does not return any candidate location objects, there will be an empty response.

    Postal Code

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/legislative_district?search_postal=19123&search_country=US&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/legislative_district?search_postal=19123&search_country=US&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        districts = data['response']['results']['candidates'][0]['districts']
        print(districts)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/legislative_district?search_postal=19123&search_country=US&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var districts = data.response.results.candidates[0].districts;
          console.log(districts);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Response Structure:

    {
      "response": {
        "errors": [],
        "messages": [],
        "results": {
          "candidates": [
            {
              "count": {
                "to": number,
                "total": number,
                "from": number
              },
              "districts": [
                ... district objects ...
              ],
              "match_postal": string,
              "wkid": number,
              "match_country": string,
              "locator": string,
              "score": number,
              "match_region": string,
              "match_city": string,
              "match_addr": string,
              "y": number,
              "x": number,
              "match_subregion": string,
              "partial_match": boolean,
              "geoservice": string
            },
            ...
          ]
        }
      }
    }
    

    A location query with only a postal code uses a geocoding service to approximate a center point for the postal code, then matches the location to Cicero's district boundaries.

    In the United States, postal codes are known as ZIP Codes. In addition to standard five-digit ZIP Codes, Cicero will also match to ZIP+4 or nine digit ZIP Codes. Using a ZIP+4 will be more accurate than a five-digit ZIP Code. ZIP+4 Codes can be formatted with or without the hyphen.

    Use the search_postal and search_country parameter to search for a postal code.

    Searching with a single address string:

    Parameter Description
    search_postal One line address or a single search string.
    search_country The country of the location (Use ISO 3166-1 alpha-2 code).

    Using only a postal code is less accurate than using a full street address and less accurate than using a latitude and longitude coordinate.

    Filter by District Type

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/official?lat=38.89737&lon=-77.03741&district_type=NATIONAL_EXEC&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/official?lat=38.89737&lon=-77.03741&district_type=NATIONAL_EXEC&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        officials = data['response']['results']['officials']
        print(officials)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/official?lat=38.89737&lon=-77.03741&district_type=NATIONAL_EXEC&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var officials = data.response.results.officials;
          console.log(officials);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Use district parameters to filter location query responses based on the type of district.

    Parameter Description
    district_type (optional) The type of district.
    district_id (optional) The ID, number, or name of the official's district.
    city (optional) The city of the official's district.
    state (optional) The state of the official's district.
    country (optional) The country of the official's district.

    Filter by District Valid Range

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/official?lat=39.961292&lon=-75.154126&district_type=NATIONAL_LOWER&valid_range=ALL&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/official?lat=39.961292&lon=-75.154126&district_type=NATIONAL_LOWER&valid_range=ALL&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        officials = data['response']['results']['officials']
        print(officials)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/official?lat=39.961292&lon=-75.154126&district_type=NATIONAL_LOWER&valid_range=ALL&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var officials = data.response.results.officials;
          console.log(officials);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Use district valid range parameters to filter location query responses based on dates the district is valid. This parameter can be used to request redistricted districts that go into effect in the future. We do not keep official or candidate data for future districts.

    Parameter Description
    valid_on The date the district is valid on. Date should be specified in a YYYY-MM-DD format.
    valid_on_or_after The date the district is valid on or after. Date should be specified in a YYYY-MM-DD format.
    valid_on_or_before The date the district is valid on or before. Date should be specified in a YYYY-MM-DD format.
    valid_range The dates during which district is valid between. Dates should be specified in a YYYY-MM-DD format and separated by a comma. Use ALL to return every district in all valid date ranges.
    district_type (optional) The type of district.
    district_id (optional) The ID, number, or name of the official's district.
    city (optional) The city of the official's district.
    state (optional) The state of the official's district.
    country (optional) The country of the official's district.

    Filter by Max Parameter

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/official/?lat=-34.6697761&lon=150.8531786&max=100&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/official/?lat=-34.6697761&lon=150.8531786&max=100&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        officials = data['response']['results']['officials']
        print(officials)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/official/?lat=-34.6697761&lon=150.8531786&max=100&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var officials = data.response.results.officials;
          console.log(officials);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Response Structure

    {
      "response": {
        "errors": [],
        "messages": [],
        "results": {
          "count": {
            "to": number,
            "total": number,
            "from": number
          },
          "officials": [
            ... official objects ...
          ]
        }
      }
    }
    

    By default, a location query will return up to 40 objects. However, some legislative chambers have more than 40 officials representating a single location. This parameter can be used to return more than 40 objects but less than 200.

    Parameter Description
    max The maximum number of objects to return.

    Officials

    Endpoint:

    GET https://cicero.azavea.com/v3.1/official
    

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/official?lat=39.662&lon=-75.566&district_type=NATIONAL_LOWER&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/official?lat=39.662&lon=-75.566&district_type=NATIONAL_LOWER&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        officials = data['response']['results']['officials']
        print(officials)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/official?lat=39.662&lon=-75.566&district_type=NATIONAL_LOWER&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var officials = data.response.results.officials;
          console.log(officials);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Response Structure:

    {
      "response": {
        "errors": [],
        "messages": [],
        "results": {
          "count": {
            "to": number,
            "total": number,
            "from": number
          },
          "officials": [
            ... official objects ...
          ]
        }
      }
    }
    

    Cicero tracks elected officials and makes their information available through the official resource.

    Cost: 1 credit

    Use location queries on this resource. You can also query for officials using the official's name.

    Response results include a list of official objects. By default, up to 40 officials are returned, but you can increase that up to 200 with the max parameter.

    Query by Name

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/official?last_name=Washington&valid_range=ALL&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/official?last_name=Washington&valid_range=ALL&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        officials = data['response']['results']['officials']
        print(officials)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/official?last_name=Washington&valid_range=ALL&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var officials = data.response.results.officials;
          console.log(officials);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Use name parameters to query for information about a specific official. The response will include all officials currently in office who match that name.

    Parameter Description
    last_name The official's last name
    valid_range The dates during which official is valid between. Dates should be specified in a YYYY-MM-DD format and separated by a comma. Use ALL to return every official in all valid date ranges.
    valid_on_or_after The date official is valid on or after. Date should be specified in a YYYY-MM-DD format.
    valid_on_or_before The date official is valid on or before. Date should be specified in a YYYY-MM-DD format.
    first_name (optional) The official's first name

    Combine any of these parameters with a location query to filter responses.

    Legislative Districts

    Endpoint:

    GET https://cicero.azavea.com/v3.1/legislative_district
    

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/legislative_district?lat=38.89737&lon=-77.03741&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/legislative_district?lat=38.89737&lon=-77.03741&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        districts = data['response']['results']['districts']
        print(districts)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/legislative_district?lat=38.89737&lon=-77.03741&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var districts = data.response.results.districts;
          console.log(districts);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Response Structure

    {
      "response": {
        "errors": [ ],
        "messages": [ ],
        "results": {
          "districts": [
            ... district objects ...
          ],
          "count": {
            "to": number,
            "total": number,
            "from": number
          }
        }
      }
    }
    

    Cicero tracks legislative district boundaries and makes information about the districts available through the legislative_district resource.

    Cost: 1 credit

    Use location queries on this resource.

    Response results include a list of district objects.

    Non-Legislative Districts

    Endpoint:

    GET https://cicero.azavea.com/v3.1/nonlegislative_district
    

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/nonlegislative_district?lat=38.7081&lon=-77.0864&district_type=SCHOOL&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/nonlegislative_district?lat=38.7081&lon=-77.0864&district_type=SCHOOL&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        districts = data['response']['results']['districts']
        print(districts)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/nonlegislative_district?lat=38.7081&lon=-77.0864&district_type=SCHOOL&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var districts = data.response.results.districts;
          console.log(districts);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Response Structure:

    {
      "response": {
        "errors": [ ],
        "messages": [ ],
        "results": {
          "districts": [
            ... district objects ...
          ],
          "count": {
            "to": number,
            "total": number,
            "from": number
          }
        }
      }
    }
    

    Cicero tracks non-legislative district boundaries and makes information about the districts available through the nonlegislative_district resource. The types of non-legislative districts tracked by Cicero vary regionally.

    Cost: 1 credit

    Use location queries on this resource.

    Response results include a list of district objects.


    Attribution Requirements for Non-Legislative District Data:

    Australian Census boundaries are licensed under the Creative Commons Attribution Australia License. Material that has not been modified or transformed must be cited using "Source: Australian Bureau of Statistics" or "Source: ABS". Derivative material, such as modifications to text, deriving new statistics, calculating percentage changes, or creating graphs or charts must be attributed using "Based on Australian Bureau of Statistics data" or "Based on ABS data".

    Australian watershed boundaries are developed by Australian National University (ANU) and obtained through Geoscience Australia. Licensing is under Creative Commons Attribution Australia License. ANU has tried to make the information in this product as accurate as possible. However, it does not guarantee that the information is totally accurate or complete. Therefore you should not solely rely on this information when making a commercial decision. Users should also consider the scale and limitations of the source data on which it is based. The database is suitable for application at regional to continental scale. Finer scale data should be obtained for local scale analyses and assessment.

    Canadian census and watershed boundaries are adapted from Statistics Canada. This does not constitute an endorsement by Statistics Canada of Cicero Web Services. Boundaries are reproduced and distributed on an “as is” basis with the permission of Statistics Canada. Use is subject to the Statistics Canada Open Licence Agreement.

    Maps

    Endpoint:

    GET https://cicero.azavea.com/v3.1/map
    

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/map/734?include_image_data&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/map/734?include_image_data&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        map_data_URI = data['response']['results']['maps'][0]['img_src']
        print(map_data_URI)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/map/734?include_image_data&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var mapDataURI = data.response.results.maps[0].img_src;
          console.log(mapDataURI);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Response Structure:

    {
      "response": {
        "errors": [],
        "messages": [],
        "results": {
          "maps": [
            {
              "url": string,
              "img_src": string,
              "extent": {
                "x_min": number,
                "srid": number,
                "y_max": number,
                "y_min": number,
                "x_max": number
              }
            }
          ]
        }
      }
    }
    

    Cicero makes simple maps of district boundaries available through the map resource.

    Use the id property from a District object with this resource to request an image showing the shape of the district. The appearance of the map can be configured beyond the default style with graphical parameters.

    Cost: 1 credit

    Parameter Description
    width (optional) The width in pixels of the returned map image.
    height (optional) The height in pixels of the returned map image.
    include_image_data (optional) Whether to include a data URI in the response.
    fill_color (optional) The color of the district's shape.
    fill_opacity (optional) The opacity of the district's shape.
    boundary_width (optional) The width of the district's outline.
    boundary_color (optional) The color of the district's outline.
    boundary_dash (optional) The length of dashes on the district's outline.
    boundary_gap (optional) The length of gaps between dashes on the district's outline.
    boundary_line_join (optional) The type of line joins for the district's outline.
    srs (optional) The EPSG code spatial reference system code for the map.
    format (optional) The format of the map image (one of png, png8, png32, png256 or jpeg).

    Election Events

    Endpoint:

    GET https://cicero.azavea.com/v3.1/election_event
    

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/election_event?election_expire_date_on_or_after=today&election_expire_date_before=tomorrow&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/election_event?election_expire_date_on_or_after=today&election_expire_date_before=tomorrow&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        elections = data['response']['results']['election_events']
        print(elections)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/election_event?election_expire_date_on_or_after=today&election_expire_date_before=tomorrow&format=json&key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var elections = data.response.results.election_events;
          console.log(elections);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Response Structure:

    {
      "response": {
        "errors": [],
        "messages": [],
        "results": {
          "count": {
            "to": number,
            "total": number,
            "from": number
          },
          "election_events": [
            ... election event objects ...
          ]
        }
      }
    }
    

    Cicero tracks elections occurring in every country around the world and makes information about the elections available through the election_event resource.

    Cost: 0 credits

    Parameter Description
    election_expire_date_after The earliest date an election is completed. Use today for elections completing today or later. Date should be specified in a YYYY-MM-DD format.
    election_expire_date_before The latest date an election is completed. Use tomorrow for elections completing before tomorrow. Date should be specified in a YYYY-MM-DD format.

    Response results include a list of election event objects.

    Account Status

    You can programmatically check on your account with the credits_remaining and usage resources.

    Credits Remaining

    Endpoint:

    GET https://cicero.azavea.com/v3.1/account/credits_remaining
    

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/account/credits_remaining?key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/account/credits_remaining?key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        credits_remaining = data['response']['results']['credit_balance']
        print(credits_remaining)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/account/credits_remaining?key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var creditsRemaining = data.response.results.credit_balance;
          console.log(creditsRemaining);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Response Structure:

    {
      "credit_balance": number,
      "usable_batches": [ 
        {
          "discount": string,
          "cost": string,
          "created": string,
          "credits_remaining": number,
          "expiration_time": string,
          "credits_purchased": number 
        },
        ...
      ],
      "overdraft_limit": 0
    }
    

    Use the account/credits_remaining resource to track how many credits are left in your account.

    Cost: 0 credits

    Usage

    Endpoint:

    GET https://cicero.azavea.com/v3.1/account/usage/{YYYY-MM}/to/{YYYY-MM}
    

    Response Structure:

    {
      "response": {
        "errors": [],
        "messages": [],
        "results": [
          {
            "count": number,
            "activity_types": [
              {
                "count": string,
                "type": string,
                "credits_used": string
              },
              ...
            ],
            "year": number,
            "credits_used": number,
            "month": number
          },
          ...
        ]
      }
    }
    

    Use the account/usage resource to get information about your API requests and credit usage by month for a range of months within the last year.

    Specify your time range in a /YYYY-MM/to/YYYY-MM format.

    Cost: 0 credits

    District Types

    Endpoint:

    GET https://cicero.azavea.com/v3.1/district_type
    

    Example API Call:

    $ curl "https://cicero.azavea.com/v3.1/district_type?key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://cicero.azavea.com/v3.1/district_type?key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        district_types = data['response']['results']['district_types']
        print(district_types)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://cicero.azavea.com/v3.1/district_type?key=' + key;
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var districtTypes = data.response.results.district_types;
          console.log(districtTypes);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Response Structure:

    {
      "response": {
        "errors": [ ],
        "messages": [ ],
        "results": {
          "district_types": [
            {
              "name_short": string,
              "notes": string,
              "acknowledgements": string,
              "is_legislative": boolean,
              "name_long": string
            },
            ...
          ]
        }
      }
    }
    

    Use the district_type resource to get information about the categories of both legislative and non-legislative districts in Cicero.

    Cost: 0 credits

    The district_type resource returns a list of District Type objects in its results. You can use any of the name_short property values of these objects to filter resource responses by district.

    Some common name_short values for legislative district types include:

    Some common name_short values for non-legislative district types include:

    The types of non-legislative districts tracked by Cicero vary regionally.

    API Version

    Endpoint:

    GET https://cicero.azavea.com/version
    

    Example API Call:

    curl "https://cicero.azavea.com/version"
    
    url = 'https://cicero.azavea.com/version'
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        version = data['response']['results']['version']
        print(version)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var url = 'https://cicero.azavea.com/version';
    
    request.get(url, function(error, response, body) {
        var data = JSON.parse(body);
        if (data.response.errors.length === 0) {
          var version = data.response.results.version;
          console.log(version);
        } else {
          var errors = data.response.errors;
          console.log(errors);
        }
      });
    

    Example Response:

    {
      "response": {
        "errors": [], 
        "messages": [], 
        "results": {
          "version": "3.1"
        }
      }
    }
    

    Use the version resource to get the current version of the API.

    Cost: 0 credits

    Response Objects

    Official object

    Official objects are a component of responses from the official resource.

    Property Value Description
    id number The Cicero database ID for this official. Changes after each edit; for a persistent ID, see sk.
    sk number The surrogate key for an official. Remains the same for an individual through different districts, chambers, and discontinuous terms.
    first_name string First name of the official. Sometimes, an official will have a preferred_name that they are more commonly known by.
    last_name string Last name of the official.
    middle_initial string Middle name or initial of the official.
    preferred_name string A name commonly used instead of the official's given first name. This property has a value only if it differs from the first_name.
    salutation string Official's formal salutation. Some assemblies use formal titles such as "Honorable".
    name_suffix string Name suffix of the official (e.g., "Jr.", "III", "Ph.D.").
    party string Political party designation of the official. Might be "Nonpartisan" in cases where the government specifically uses that term.
    titles array A list of any titles that the official holds. Typically, these are determined at an early meeting of the chamber. Titles are different than and in addition to the role (e.g., President, Senator) that the official was elected to.
    office object An office object with information about the official's country, chamber, government, and role.
    addresses array A list of address objects with the official's contact information, such as mailing address, phone, and fax.
    email_addresses array A list of the official's email addresses.
    urls array A list of the official's government web page URLs.
    web_form_url string A web form URL for contacting the official.
    photo_origin_url string A URL for a headshot photo of the official.
    identifiers array A list of identifier objects with information like social media accounts.
    notes array A list of descriptive information about the official, including a biography and a birthdate.
    valid_from string Date the official was inaugurated in this office. Changes with redistricting or election to a new office, but not when an incumbent starts a consecutive term.
    valid_to string Date the official's term in office expires. This date would be extended if the official wins re-election.
    last_update_date string Date the Cicero research team last made changes to this official's information.
    committees array Deprecated.
    term_end_date string Deprecated. Use valid_to instead.
    initial_term_start_date string Deprecated. Use valid_from instead.
    current_term_start_date string Deprecated. Use valid_from instead.
    nickname string Deprecated. Use preferred_name instead.

    Office object

    Office objects are a component of responses from the official resource.

    Property Value Description
    title string The role of this office. This is the position that an candidate for office is listed for on an election ballot.
    chamber object A chamber object for the chamber that this office serves within.
    district object A district object for the constituency of this office.
    representing_country object A country object for the country of this office's government.
    representing_state string The state, province, or other region that this office serves.
    representing_city string The city that this office serves.
    id number Deprecated. Use id on the Official object
    sk number Deprecated. Use sk on the Official object
    valid_from string Deprecated. Use valid_from on the Offical object
    valid_to string Deprecated. Use valid_to on the Offical object
    last_update_date object Deprecated. Use last_update_date on the Official object
    election_rules string Deprecated. Use election_rules on the Chamber object
    notes string Deprecated.

    Address object

    Address objects are a component of responses from the official resource. Primary address objects are listed first and usually contain Capitol or official government offices for the legislature. Secondary address objects are listed second and usually contain district or home offices.

    Property Value Description
    address_1 string The first line of the street address.
    address_2 string The second line of the street address.
    address_3 string The third line of the street address.
    state string The state, province, or other region of the address.
    postal_code string The postal code for the address.
    phone_1 string The primary phone number for contacting the address.
    phone_2 string The secondary phone number for contacting the address.
    fax_1 string The primary fax number for the address.
    fax_2 string The secondary fax number for the address.
    county string Deprecated.

    Identifier object

    Identifier objects are a component of responses from the official resource.

    Property Value Description
    identifier_type string The platform referred to by the identifier.
    id number The Cicero database ID for this identifier.
    identifier_value string The identifying value for the official on this type of platform. Could be either a profile ID or a full URL.
    official number Deprecated. Use id on the Official object
    valid_from string Deprecated.
    valid_to string Deprecated.
    last_update_date string Deprecated.
    sk number Deprecated.
    version number Deprecated.

    Common Identifier Types in Cicero:

    identifier_type Description Platform URL
    FACEBOOK The full Facebook page URL of an official's personal profile. https://www.facebook.com
    FACEBOOK-CAMPAIGN The full Facebook page URL for an official's campaign profile. https://www.facebook.com
    FACEBOOK-OFFICIAL The full Facebook page URL for an official's government profile. https://www.facebook.com
    VOTESMART The Vote Smart profile ID of an official. https://www.votesmart.org
    TWITTER The Twitter handle of an official. https://www.twitter.com
    LINKEDIN The full LinkedIn profile URL of an official. https://www.linkedin.com
    YOUTUBE The YouTube user ID or channel ID for an official. https://www.youtube.com
    INSTAGRAM The Instagram handle for an official. https://www.instagram.com
    RSS The RSS feed URL for an official. Unique URL
    FLICKR The Flickr profile ID of an official. https://www.flickr.com
    BIOGUIDE The Congressional Biographical Directory profile ID for an official. http://bioguide.congress.gov
    GOVTRACK The GovTrack profile ID for an official. https://www.govtrack.us
    FEC The Federal Election Committee profile ID for an official or campaign committee. https://www.fec.gov/
    CRP The OpenSecrets.org Center for Responsive Politics profile ID for an official. https://www.opensecrets.org

    District object

    District objects are a component of responses from the official, legislative_district, and nonlegislative_district resources.

    Property Value Description
    id number The Cicero database ID for this district. Changes after each edit; for a persistent ID, see sk.
    sk number The surrogate key for the district.
    ocd_id string The Open Civic Data Identifier for the district. Provides a standardized way of specifying and describing a geographic political division.
    label string Descriptive text associated with a district_id, such as the label for the district (e.g. “5th Ward”), or a full label for the district (e.g. “Sealaska Alaska Native Regional Corporation”).
    district_type string The level of government the district represents. See the district_type metadata endpoint for a list of possibilities.
    subtype string An additional categorization within district_type.
    district_id string The identifying code for the district within its delegation or district type. For example, a legislative delegation's 5th district would probably have a district_id of "5". Non-legislative districts might have an ID assigned by the managing agency (e.g., US Census Block Groups have a GEOID).
    city string The city the district represents, if the district_type is LOCAL or LOCAL_EXEC.
    state string The state, province, or region the district is within.
    country string The country the district is within. Uses the ISO 2 country code.
    num_officials number The number of elected officials that hold offices representing this district.
    valid_from string The date the district was established. Usually, this is the date of the last redistricting.
    valid_to string The date when the district's boundaries are expected to be changed. Usually, this is the date of the next redistricting.
    last_update_date string Date the Cicero research team last made changes to this district's boundary information.
    data object Deprecated.

    Chamber object

    Chamber objects are a component of responses from the official and election_event resources.

    Property Value Description
    id number The Cicero database ID for the chamber. Changes after each edit; not persistent.
    name string Informal name of the chamber in English.
    name_formal string English formal name of the chamber.
    name_native_language string Name of the chamber in the government's official language.
    government object A government object for the government this chamber is part of.
    type string Governmental level of the chamber.
    official_count number The number of officials serving in the chamber.
    term_length string The length of time for each term that officials serve in the chamber.
    term_limit string The maximum number of terms officials within the chamber can serve.
    election_frequency string The length of time between elections with candidates for the chamber on the ballot. Shorter than term_length in chambers with staggered elections.
    election_rules string A description of when elections take place.
    vacancy_rules string The process of how vacancies within the chamber are filled.
    redistricting_rules string The process of redistricting for the chamber.
    inauguration_rules string The process for inaugurating officials within the chamber.
    url string URL to the official webpage of the chamber.
    contact_phone string A general phone number for contacting the chamber.
    contact_email string A general email address for contacting the chamber.
    remarks string Notable quirks or facts related to the chamber.
    last_update_date string Date the Cicero research team last made changes to this district's information.
    legislature_update_date string Deprecated.
    is_chamber_complete boolean Deprecated.
    has_geographic_representation string Deprecated.
    notes string Deprecated.

    Government object

    Government objects are a component of responses from the official and election_event resources.

    Property Value Description
    name string The formal name of the government.
    type string A category describing the level of government.
    city string The city that the government governs.
    state string The state, province, or region that the government governs.
    country object A country object for the government's country.
    notes string Deprecated.

    Country object

    Country objects are a component of responses from the official and election_event resources.

    Property Value Description
    id number The Cicero database ID for the country. Changes after each edit; for a persistent ID, see sk.
    sk number The surrogate key for the country.
    status string The parent organization (e.g., “UN Member State”) or state on which the given Country is dependent (e.g., “Oversea Department of France”).
    name_short string Short, common name for the country in English.
    name_short_iso string Short name (in English) for the country specified in the ISO-3166 standard.
    name_short_local string Short, common name for the country in the local language.
    name_short_un string United Nations short name for the country.
    name_long string Long name for the country in English.
    name_long_local string Long name for the country in the local language.
    gmi_3 string Three-letter Global Mapping International (GMI) country/territory code for the country.
    iso_2 string Two-letter ISO 3166-1 alpha-2 standard code for the country.
    iso_3 string Three-letter ISO 3166-1 alpha-3 standard code for the country.
    iso_3_numeric number Three-digit ISO 3166-1 numeric standard code for the country.
    fips string Two-letter U.S. Federal Information Processing Standard No.
    last_update_date string Date the Cicero research team last made changes to the country's information.
    valid_from string Deprecated.
    valid_to string Deprecated.
    version number Deprecated.

    Election Event object

    Election Event objects are a component of responses from the election_event resource.

    Property Value Description
    id number The Cicero database ID for the election event. Changes after each edit; for a persistent ID, see sk.
    sk number The surrogate key for the election event.
    label string The name of the election.
    chambers array A list of chamber objects for chambers with members up for election.
    election_expire_date string The date when voting in the election completes. Some elections span several days; this will be the last day.
    election_date_text string A description of the date or dates that an election is being held.
    is_approximate boolean Whether the election event's election_expire_date is not accurate or precise to the day.
    is_local boolean Whether the election is for an office of local government (e.g., a municipal, county, or town election).
    is_state boolean Whether the election is for an office of regional government (e.g., sub-national state, provincial, or prefecture election).
    is_national boolean Whether the election is for an office of the nation state.
    is_by_election boolean Whether the election is a special election that falls outside the regular calendar.
    is_referendum boolean Whether the election event is specifically about a referendum on the ballot.
    is_primary_election boolean Whether the election is a primary election that precedes the general election.
    is_runoff_election boolean Whether the election is a second, third, or later election used for deciding between the top candidates in earlier elections.
    is_transnational boolean Whether the election is for an office of a trans-national institution.
    urls array A list of URL strings for pages with more information about the election.
    remarks string Specific details about the election that describe the event.
    last_update_date string Date the Cicero research team last made changes to the election's information.
    valid_from string Deprecated
    valid_to boolean Deprecated

    District Type object

    Government objects are a component of responses from the district_type resource.

    Property Value Description
    name_short string The code used for filtering responses by district type. Formatted in ALL_CAPS with an underscore.
    name_long string A description of the district type.
    is_legislative boolean Whether the districts of this type are legislative.
    notes string Deprecated
    acknowledgements string Deprecated

    Help & Support

    Please contact us with any questions.

    We are constantly working to improve Cicero and its services. Please use the Data Error Report form if you find incorrect information in any of Cicero's data.

    Was this documentation helpful? Let us know how it could be improved. https://www.cicerodata.com/contact/