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:

• Provide an elected official lookup tool on your website.
• Create constituent records in your database.
• Display district boundaries on a map.
• Show elected official profiles in your app.

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:

• official
• legislative_district
• nonlegislative_district
• map

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:

• NATIONAL_* district types will filter Officials to all districts matching country and state, but will ignore city.
• STATE_* district types will filter in the same way as NATIONAL. This means that retrieving a state-level chamber will return all officials in that chamber, even if the request includes a city filter.
• LOCAL_* district types will be filtered by country, state, and city.

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:

• NATIONAL_EXEC
• NATIONAL_UPPER
• NATIONAL_LOWER
• STATE_EXEC
• STATE_UPPER
• STATE_LOWER
• LOCAL_EXEC
• LOCAL

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

• SCHOOL
• JUDICIAL
• CENSUS
• COUNTY
• WATERSHED

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/