NAV Navbar
shell python javascript
  • Introduction
  • Credits
  • Root URL
  • Authentication
  • Responses
  • Location Queries
  • Pagination
  • Officials
  • Officials by region
  • Legislative Districts
  • Non-Legislative Districts
  • Maps
  • Election Events
  • Redistricting Events
  • Data coverage
  • 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. Javascript examples use fetch, which is supported in most browsers but requires the node-fetch package to be used in a Node.js application. To get started:

    $ curl --help
    
    import requests
    
    // Javscript examples use the fetch API, which is supported in most browsers.
    
    // If you are using Node.js, you can use the node-fetch library
    const fetch = require('node-fetch');
    

    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 or the Data Coverage resource 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://app.cicerodata.com/v3.1
    

    The base URL for all requests to the Cicero API is https://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/token/new.json"
    
    username = 'username' # Replace with your username
    password = 'password' # Replace with your password
    
    response = requests.post(
        'https://app.cicerodata.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
    
    
    fetch('https://app.cicerodata.com/v3.1/token/new.json', {
        method: 'POST',
        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
        body: 'username=' + username + '&password=' + password
      })
      .then(response => response.json())
      .then(data => {
        var user = data.user,
        token = data.token;
        console.log(user, token)
      })
      .catch((error) => {
        console.error('Error:', error);
      });
    

    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. The following is a description of each field:

    Property Value Description
    errors string[] If the request encountered an error or errors, details about the error(s) will be contained in this field, as an array of strings.
    results object Contains the resources matching the request query, if any. The structure of this object depends on the type of resource being queried. Refer to the documentation for the endpoint you are querying and the section on Response Objects for details.
    messages string[] Contains additional information about the outcome of a request that is not an error and not part of a query result, as an array of strings. Currently, this field is unused by the data endpoints and will always be an empty array.

    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://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/official/?lat=39.961&lon=-75.154&format=json&key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
        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://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/legislative_district?search_loc=990+spring+garden+st+philadelphia+pa&format=json&key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
        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://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/legislative_district?search_postal=19123&search_country=US&format=json&key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
        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.

    Ordering

    Example API Call:

    $ curl "https://app.cicerodata.com/v3.1/official/?lat=-34.6697761&lon=150.8531786&order=middle_initial&sort=desc&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://app.cicerodata.com/v3.1/official/?lat=-34.6697761&lon=150.8531786&order=middle_initial&sort=desc&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://app.cicerodata.com/v3.1/official/?lat=-34.6697761&lon=150.8531786&order=middle_initial&sort=desc&format=json&key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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": [
            {
              "middle_initial": "W.",
              ... other fields ...
            },
            {
              "middle_initial": "L.",
              ... other fields ...
            },
            {
              "middle_initial": "A.",
              ... other fields ...
            }
          ]
        }
      }
    }
    

    The ordering of resources returned by an API call can be controlled through the use of the order and sort query parameters. In general, a resource can be ordered by any of the simple fields (strings, numbers, dates, etc.) at the top level of the resource. The example shows ordering officials by middle initial. This is probably not a useful thing to order by in practice, but it demonstrates the functionality: middle_initial is a string field at the top level of the Official resource.

    Each resource has a default ordering which is applied if no ordering is specified. The default orderings for specific resources are documented in the sections below for each resource.

    Parameter Description
    order The name of the resource field by which to order the results
    sort Whether to sort the results in ascending or descending order. Accepted values are asc and desc. If unspecified, asc is the default.

    Filter by District Type

    Example API Call:

    $ curl "https://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/official?lat=38.89737&lon=-77.03741&district_type=NATIONAL_EXEC&format=json&key=' + key;
    
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/official?lat=39.961292&lon=-75.154126&district_type=NATIONAL_LOWER&valid_range=ALL&format=json&key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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.

    Pagination

    Some endpoints may return a large number of results, in which case the response will be paginated. The max and offset parameters can be used to access additional results for a query that spans across multiple pages.

    Max Parameter

    Example API Call:

    $ curl "https://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/official/?lat=-34.6697761&lon=150.8531786&max=100&format=json&key=' + key;
    
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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.

    Results offset

    Example count section:

    "count": {
        "from": 0,
        "to": 39,
        "total": 64
    }
    

    Use the offset parameter to access additional results beyond the first page. For example, if the count section of an API response looks like the JSON to the right (where total > to), indicating that only the first 40 officials have been returned in the current response, the offset parameter can be used to access the additional officials beyond those returned in the initial set.

    Example API call:

    $ curl "https://app.cicerodata.com/v3.1/official?lat=-34.6697761&lon=150.8531786&offset=40&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://app.cicerodata.com/v3.1/official?lat=-34.6697761&lon=150.8531786&offset=40&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://app.cicerodata.com/v3.1/official?lat=-34.6697761&lon=150.8531786&offset=40&format=json&key=' + key;
    
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      if (data.response.errors.length === 0) {
        var officials = data.response.results.officials;
        console.log(officials);
      } else {
        var errors = data.response.errors;
        console.log(errors);
      }
    })
    
    Parameter Description
    offset Number of items to skip in the response, starting from the beginning of the list.

    Officials

    Endpoint:

    GET https://app.cicerodata.com/v3.1/official
    

    Example API Call:

    $ curl "https://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/official?lat=39.662&lon=-75.566&district_type=NATIONAL_LOWER&format=json&key=' + key;
    
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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. The default response ordering is by last_name, first_name.

    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.

    Order by District Type

    Example API call:

    $ curl "https://app.cicerodata.com/v3.1/official?lat=39.662&lon=-75.566&order=district_type&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://app.cicerodata.com/v3.1/official?lat=39.662&lon=-75.566&order=district_type&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://app.cicerodata.com/v3.1/official?lat=39.662&lon=-75.566&order=district_type&format=json&key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      if (data.response.errors.length === 0) {
        var officials = data.response.results.officials;
        console.log(officials);
      } else {
        var errors = data.response.errors;
        console.log(errors);
      }
    })
    

    Passing order=district_type as a query parameter will cause the returned officials to be sorted by the type of district with which each official is associated. This sorting applies to legislative (including executive) districts only.

    The default sort order is:

    1. Transnational
    2. National
    3. State
    4. Local

    Within each level, the ordering is:

    1. Executive
    2. Upper
    3. Lower

    After district ordering has been applied, officials are sorted by last_name, first_name.

    The district-level ordering can be reversed by passing the sort=desc parameter.

    Query by Name

    Example API Call:

    $ curl "https://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/official?last_name=Washington&valid_range=ALL&format=json&key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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.

    Officials by region

    Endpoint:

    GET https://app.cicerodata.com/v3.1/officials_by_region
    

    Example API Call:

    $ curl "https://app.cicerodata.com/v3.1/officials_by_region?district_type=NATIONAL_LOWER&district_type=STATE_LOWER&country=US&state=PA&state=OH&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    url = 'https://app.cicerodata.com/v3.1/officials_by_region'
    params = {
      'district_type': ['NATIONAL_LOWER', 'STATE_LOWER'],
      'country': 'US',
      'state': ['PA', 'OH'],
      'key': key,
    }
    
    response = requests.get(url, params)
    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://app.cicerodata.com/v3.1/officials_by_region?key=' + key +
              '&district_type=NATIONAL_LOWER&district_type=STATE_LOWER&country=US&state=PA&state=OH';
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      if (data.response.errors.length === 0) {
        var districts = data.response.results.officials;
        console.log(districts);
      } else {
        var errors = data.response.errors;
        console.log(errors);
      }
    })
    

    Response Structure:

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

    The "Officials by Region" resource provides the ability to list elected officials by level and region rather than for a single geographic location.

    Cost: 50 credits

    Permission: Please contact the Cicero Team to request access to this resource.

    Response results include a list of abbreviated official objects, which contain a limited subset of the information in the full Officials response. By default, the first 100 officials will be returned, but see the Pagination section for how to use the max and offset parameters to access the complete set of results.

    The endpoint is filtered by district type and region, and sorted by last_name, first_name.

    Parameter Description
    district_type The name_short value of a district type. See District Types. Required.
    country Two-letter country code. Required.
    state State or province abbreviation. Conditionally required depending on district_type.
    city City or other local municipality. Conditionally required depending on district_type.

    All parameters can be provided more than once to include multiple values. Results will be filtered to districts matching any of the values for a given parameter.

    Which parameters are required depends on what district types are selected:

    Query param NATIONAL_* STATE_* LOCAL_*
    country X X X
    state X X
    city X

    Since the endpoint supports looking up officials from multiple levels in a single request, the region filters are applied differently depending on the district type. Query parameters will filter different district types as follows:

    Query param NATIONAL_* STATE_* LOCAL_*
    country X X X
    state X X X
    city X

    In other words:

    Legislative Districts

    Endpoint:

    GET https://app.cicerodata.com/v3.1/legislative_district
    

    Example API Call:

    $ curl "https://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/legislative_district?lat=38.89737&lon=-77.03741&format=json&key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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. The default response ordering is by id.

    Cost: 1 credit

    Use location queries on this resource.

    Response results include a list of district objects.

    Non-Legislative Districts

    Endpoint: ````````` endpoint GET https://app.cicerodata.com/v3.1/nonlegislative_district ```

    Example API Call:

    $ curl "https://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/nonlegislative_district?lat=38.7081&lon=-77.0864&district_type=SCHOOL&format=json&key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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. The default response ordering is by id.

    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://app.cicerodata.com/v3.1/map
    

    Example API Call:

    $ curl "https://app.cicerodata.com/v3.1/map/734?format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://app.cicerodata.com/v3.1/map/734?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://app.cicerodata.com/v3.1/map/734?format=json&key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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": [
            {
              "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.

    JSON and XML responses will contain the image as a data URI. Requests with format=image will return only the image.

    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.
    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_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 response: json, xml or image
    map_format (optional) The format of the map image. One of png (the default), png8, png32, png256 or jpeg.

    Election Events

    Endpoint:

    GET https://app.cicerodata.com/v3.1/election_event
    

    Example API Call:

    $ curl "https://app.cicerodata.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://app.cicerodata.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://app.cicerodata.com/v3.1/election_event?election_expire_date_on_or_after=today&election_expire_date_before=tomorrow&format=json&key=' + key;
    
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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. The default response ordering is by election_expire_date.

    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.

    Redistricting Events

    Endpoint:

    GET https://app.cicerodata.com/v3.1/redistricting_event
    

    Example API Call:

    $ curl "https://app.cicerodata.com/v3.1/redistricting_event?begin_date_before=today&complete_date_after=tomorrow&format=json&key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://app.cicerodata.com/v3.1/redistricting_event?begin_date_before=today&complete_date_after=tomorrow&format=json&key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        redistricting_events = data['response']['results']['redistricting_events']
        print(redistricting_events)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://app.cicerodata.com/v3.1/redistricting_event?begin_date_before=today&complete_date_after=tomorrow&format=json&key=' + key;
    
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      if (data.response.errors.length === 0) {
        var redistricting_events = data.response.results.redistricting_events;
        console.log(redistricting_events);
      } else {
        var errors = data.response.errors;
        console.log(errors);
      }
    })
    
    
    

    Response Structure:

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

    Cicero tracks redistricting events and makes information about them available through the redistricting_event resource.. The default response ordering is by begin_date.

    Cost: 0 credits

    Parameter Description
    begin_date_before The date a redistricting event was begun. Use today for redistricting events that have already started. Date should be specified in a YYYY-MM-DD format.
    complete_date_after The latest date a redistricting event is completed. Use tomorrow for redistricting events that are not yet completed. Date should be specified in a YYYY-MM-DD format.

    Response results include a list of redistricting event objects.

    Data coverage

    Endpoint:

    GET https://app.cicerodata.com/v3.1/coverage
    

    Example API Call:

    $ curl "https://app.cicerodata.com/v3.1/coverage?key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://app.cicerodata.com/v3.1/coverage?key=' + key
    
    response = requests.get(url)
    
    data = response.json()
    
    if len(data['response']['errors']) == 0:
        coverage = data['response']['results']['coverage']
        print(coverage)
    else:
        errors = data['response']['errors']
        print(errors)
    
    var key = '{api_key}'; // Replace with your API key
    
    var url = 'https://app.cicerodata.com/v3.1/coverage?key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      if (data.response.errors.length === 0) {
        var coverage = data.response.results.coverage;
        console.log(coverage);
      } else {
        var errors = data.response.errors;
        console.log(errors);
      }
    })
    
    

    Response Structure:

    {
      "response": {
        "errors": [ ],
        "messages": [ ],
        "results": {
          "coverage": [
            {
              "name": string,
              "chambers": [string, ...],
              "admin1": [
                {
                  "name": string,
                  "chambers": [string, ...],
                  "localities": [
                    {
                      "name": string,
                      "chambers": [string, ...]
                    }
                  ]
                }
              ],
              "nonLegislative": {
                "description": "Geographic divisions for which Cicero maintains boundaries but not elected officials.",
                "types": [string, ...]
                ]
              }
            },
            ...
          ]
        }
      }
    }
    

    The coverage resource provides a current list of national, state, and local governments for which Cicero maintains elected official data. It includes chamber names for all legislative chambers and a list of the non-legislative districts for which Cicero maintains geographic boundaries.

    The response is organized by country, with states/provinces and non-legislative boundaries listed within each country and localities listed within each state/province. Each place contains a list of its legislative chambers, and each country also contains a list of its non-legislative district types.

    Cost: 0 credits

    Account Status

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

    Credits Remaining

    Endpoint:

    GET https://app.cicerodata.com/v3.1/account/credits_remaining
    

    Example API Call:

    $ curl "https://app.cicerodata.com/v3.1/account/credits_remaining?key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://app.cicerodata.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://app.cicerodata.com/v3.1/account/credits_remaining?key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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://app.cicerodata.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://app.cicerodata.com/v3.1/district_type
    

    Example API Call:

    $ curl "https://app.cicerodata.com/v3.1/district_type?key={api_key}"
    
    key = '{api_key}' # Replace with your API key
    
    url = 'https://app.cicerodata.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://app.cicerodata.com/v3.1/district_type?key=' + key;
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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. The default response ordering is by name_short.

    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://app.cicerodata.com/version
    

    Example API Call:

    curl "https://app.cicerodata.com/version"
    
    url = 'https://app.cicerodata.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://app.cicerodata.com/version';
    
    
    fetch(url, {method: 'GET'})
    .then(response => response.json())
    .then(data => {
      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 string[] 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 Address[] A list of address objects with the official's contact information, such as mailing address, phone, and fax.
    email_addresses string[] A list of the official's email addresses.
    urls string[] 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. See note 1, below.
    photo_cropping object or null For photos that are zoomed out or off center, an object of the form {x, y, width, height, origWidth, origHeight} specifying the location (from top left) and dimensions of a bounding box that defines a headshot within the official photo. If no bounding box is defined (e.g. if the original photo is a well-framed headshot), this field will be null. See note 2, below.
    identifiers Identifier[] A list of identifier objects with information like social media accounts.
    notes string[] 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 or null 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 CommitteeMembership[] A list of the committees of which the official is a member. See Committee Membership object documentation.
    term_end_date string or null Deprecated. Use valid_to instead.
    initial_term_start_date string or null Deprecated. Use valid_from instead.
    current_term_start_date string Deprecated. Use valid_from instead.
    nickname string Deprecated. Use preferred_name instead.

    Note 1

    In all cases where it is filled out, the photo_origin_url provides a direct link to an image file of an official's headshot photo. Whenever possible, we use links to photos hosted on official sites operated by the government body of which the official is a member. However, there are rare cases where this is not possible. Sometimes, there is no official government site containing a headshot photo of the official. In this case, we try to locate a photo from another source, such as the Congressional Biographical Directory. In other cases, an official site with photos may exist, but it may not be possible for us to provide direct links to the photos. In these cases, we copy and host the photos ourselves. Whenever we host a photo ourselves, we obtain permission from the relevant government body before copying and hosting their photos. If a photo is hosted by Cicero, the URL will start with: https://s3.amazonaws.com/cicero-media-files/ or https://cicero-media-files.s3.amazonaws.com/.

    Note 2

    Example CSS

    .headshot {
        height: {displayHeight}px;
        width: {displayWidth}px;
        background-image: url('{official_photo_url}');
        background-size: auto {displayHeight * origHeight / width}px;
        background-position: {-x * displayHeight / width}px {-y * displayHeight / width}px;
        background-repeat: no-repeat;
    }
    

    The photo_cropping field contains a JSON object with properties x, y, width, height, origWidth, and origHeight. These parameters can be used to calculate CSS that will display the image at photo_origin_url cropped and scaled to fit in a fixed-size element. x and y are the coordinates of the top left corner of the cropping box, width and height are the dimensions of the cropping box, and origWidth and origHeight are the dimensions of the full-sized original image.

    The example CSS is a template for calculating a style definition. The quantities in brackets must be calculated for each image based on the photo_cropping parameters and the size of the intended container (displayHeight and displayWidth). The example scales to the container height, which means the width could be more or less than the container size, depending on the dimensions of the cropping box. The calculations could be adapted to scale to the display width instead, but not both, since that could result in the image being stretched or squashed.

    In cases where the original image is a standard headshot and no cropping is needed, the photo_cropping field will be null and the style should use background-size: cover; and background-position: center;.

    Abbreviated Official object

    Property Value Description
    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.").
    sk number The surrogate key for the official.
    party string Political party designation of the official. Might be "Nonpartisan" in cases where the government specifically uses that term.
    district object An abbreviated district object containing only district_id, district_type__name_short, subtype, and label.
    state string The state, province, or region of the official's district.
    chamber__name_formal string The formal name of the official's chamber.
    title string The primary title the official holds.
    addresses string[] A list of address objects with the official's contact information, such as mailing address, phone, and fax.
    email_addresses string[] A list of the official's email addresses.
    phone_1 string The primary phone number for the official's primary address.
    phone_2 string The secondary phone number for the official's primary address.
    photo_origin_url string A URL for a headshot photo of the official. See note under Official Object.
    web_form_url string A web form URL for contacting the official.
    identifiers Identifier[] A list of abbreviated identifier objects containing only identifier_type and identifier_value for official Facebook and Twitter accounts.
    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 or null Date the official's term in office expires. This date would be extended if the official wins re-election.

    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 or null 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 or null 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 (see a list of identifier types, below).
    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 or null 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
    INSTAGRAM-CAMPAIGN The Instagram handle for an official's campaign. 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

    Committee Membership object

    Committee Membership objects are a component of responses from the official resource, identifying the committees on which an official serves and their position within each committee.

    Property Value Description
    name string Name of the committee.
    urls string[] A list of the committee's web page URLs.
    committee_identifiers Identifier[] A list of identifier objects with information like social media accounts. Note that fields marked deprecated in the identifier object documentation are excluded here.
    position string The official's position within the committee, e.g. "Chair". For members with no special position this field will be blank.

    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. This field is persistent for a given District, but this does not imply that the remainder of the response payload will never change. For example, a correction to the district boundary will change the response payload but will not change the ID. On the other hand, a boundary change due to a legal event such as an annexation or redistricting will result in a new District with a new ID (and appropriate adjustments to the valid_to field, if necessary).
    sk number The surrogate key for the district. Provided for API uniformity. For this resource, the SK is equivalent to the ID.
    ocd_id string or null 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 or null 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 or null 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.
    is_appointed boolean Whether officials in this chamber are appointed rather than elected.
    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 or null 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 or null 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 or null 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 or null 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 Chamber[] A list of chamber objects for chambers with members up for election.
    election_expire_date string or null 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 string[] 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 string or null Deprecated

    Redistricting Event object

    Redistricting Event objects are a component of responses from the redistricting_events resource.

    Property Value Description
    id number The Cicero database ID for the redistricting event. Changes after each edit; for a persistent ID, see sk.
    sk number The surrogate key for the redistricting event.
    label string The name of the redistricting event.
    state string The state or country subdivision where the redistricting event occurred.
    chambers Chamber[] A list of chamber objects for chambers with modified districts in the redistricting event.
    begin_date string or null The date when the redistricting event started.
    begin_date_is_approximate boolean Whether the redistricting event's begin_date is not accurate or precise to the day.
    complete_date string or null The date when the redistricting event completed.
    complete_date_is_approximate boolean Whether the redistricting event's complete_date is not accurate or precise to the day.
    urls string[] 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.

    District Type object

    District Type 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/