Getting Started with the Cicero API

About Cicero

Cicero is a web service that provides legislative, school, and other district information and their geographic boundaries. Web services are agnostic about the systems which consume their services; they can be running Linux, Windows, Mac OSX, anything. Also, web services are agnostic about the programming language that consumes them: C#, Java, PHP, ColdFusion, or even JavaScript.

Setting up your Account

If this is your first time using Cicero, you can sign up for a free trial, which is available for a limited time and includes a limited amount of API calls. Once your trial expires, or you run out of credits, you can choose from one of our paid subscription plans. For more information about setting up an account, you can contact us via the web, e-mail cicero@azavea.com, or call us at 215-925-2600.

Authentication using API Key

For API calls requiring authentication, you may use your API key indefinitely. Your API key can be found on your account profile page.

Requests using an API key must be made using HTTPS. In this example, Cicero returns all officials currently in office whose last name is “Malik”:

https://cicero.azavea.com/v3.1/official?last_name=Malik&key=343d9083eb7bb8a06202c2c146f0ff2e97204a85

Warning

Keep in mind that even when using HTTPS, if your API key is used in viewable, client-side code (such as JavaScript on a webpage), end users may be able to see your API key.

Authentication using User ID and Token

Obtaining a token

Obtain a token by posting your username and password to /token/new.json. Upon success, the Cicero server will return JSON including your token and user ID, which will be needed to make most API calls. Tokens will be 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).

The easiest way to handle expiring tokens is to build in logic to obtain a new one when a 403 (Forbidden) HTTP response code is received, and try the request again.

Sample Request:

Request Url: http://cicero.azavea.com/v3.1/token/new.json
Request Method: POST
Parameters:
    username: john_doe
    password: p@ssw0rd

Sample Successful JSON Response

{"token": "21q-df53da3e9fcd1ce221f1", "user": 99, "success": true}

Using your token and User ID

For API calls that require authentication, use your token and user ID as request variables. For example, if you want to find officials with the last name Obama, your request might look something like:

https://cicero.azavea.com/v3.1/official?last_name=Obama&user=99&token=21q-df53da3e9fcd1ce221f1

Specifying an Output Format

API responses can be provided in JSON or XML format. The desired output can be declared with either a query parameter or Content-type request header. In cases where the format query string parameter and header are present, the response will be given in the format specified in the query string. The default format is XML.

To get the same results in the example above in JSON format, set the f or format argument to json:

https://cicero.azavea.com/v3.1/official?last_name=Obama&user=99&token=21q-df53da3e9fcd1ce221f1&f=json

Understanding API Responses

Structure

In both JSON and XML, the API response is wrapped with the response objects, which contains errors, messages, and results. As long as your query does not result in any errors, there will be a set of objects within results:

response
 |-- errors
 |-- messages
 |-- results
      |-- objects

Headers

There is also a response header called X-Cicero-Credit-Balance, which is the total of credits that are left on your account. If you have overdrafted your account, your overdraft limit will be represented by a negative value.

Sample Responses

Let’s say we want some information about legislative districts representing 32 Molesworth Street in Wellington. Here is how you would do it for XML and JSON:

XML Request:

http://cicero.azavea.com/v3.1/legislative_district?search_loc=32+Molesworth+St,+Wellington&user=99&token=21q-df53da3e9fcd1ce221f1&f=xml

XML Response

<response>
    <errors />
    <messages />
    <results>
        <candidates>
            <candidate>
                <count>
                    <to>3</to>
                    <total>4</total>
                    <from>0</from>
                </count>
                <confidence>High</confidence>
                <wkid>4326</wkid>
                <entity>Address</entity>
                <districts>
                    <district>
                        <district_type>NATIONAL_EXEC</district_type>
                        <city />
                        <valid_from>0001-01-01 04:56:02</valid_from>
                        <country>NZ</country>
                        <district_id>NEW ZEALAND</district_id>
                        <valid_to>None</valid_to>
                        <label>New Zealand</label>
                        <sk>58</sk>
                        <subtype>NATION</subtype>
                        <state />
                        <last_update_date>2012-01-12 20:00:34</last_update_date>
                        <data />
                        <id>58</id>
                    </district>
                    <district>
                        <district_type>NATIONAL_LOWER</district_type>
                        <city />
                        <valid_from>0001-01-01 04:56:02</valid_from>
                        <country>NZ</country>
                        <district_id>Wellington Central</district_id>
                        <valid_to>None</valid_to>
                        <label />
                        <sk>2648</sk>
                        <subtype>LOWER</subtype>
                        <state />
                        <last_update_date>2012-01-12 20:01:35</last_update_date>
                        <data />
                        <id>2648</id>
                    </district>
                    <district>
                        <district_type>NATIONAL_LOWER</district_type>
                        <city />
                        <valid_from>0001-01-01 04:56:02</valid_from>
                        <country>NZ</country>
                        <district_id>AT LARGE</district_id>
                        <valid_to>None</valid_to>
                        <label />
                        <sk>2676</sk>
                        <subtype>LOWER</subtype>
                        <state />
                        <last_update_date>2012-01-12 20:01:35</last_update_date>
                        <data />
                        <id>2676</id>
                    </district>
                    <district>
                        <district_type>NATIONAL_LOWER</district_type>
                        <city />
                        <valid_from>0001-01-01 04:56:02</valid_from>
                        <country>NZ</country>
                        <district_id>Te Tai Tonga</district_id>
                        <valid_to>None</valid_to>
                        <label />
                        <sk>2248</sk>
                        <subtype>LOWER</subtype>
                        <state />
                        <last_update_date>2012-01-12 20:01:35</last_update_date>
                        <data />
                        <id>2248</id>
                    </district>
                </districts>
                <locator>interpolation</locator>
                <score>100</score>
                <match_addr>32 Molesworth St, Wellington 6011</match_addr><y>-41.2778725886</y><x>174.777710671</x>
                <geoservice>Bing</geoservice>
            </candidate>
        </candidates>
    </results>
</response>

JSON Request:

http://cicero.azavea.com/v3.1/legislative_district?search_loc=32+Molesworth+St,+Wellington&user=99&token=21q-df53da3e9fcd1ce221f1&f=json

JSON Response

{
  "response": {
    "errors": [],
    "messages": [],
    "results": {
      "candidates": [
        {
          "count": {
            "to": 3,
            "total": 4,
            "from": 0
          },
          "confidence": "High",
          "wkid": 4326,
          "entity": "Address",
          "districts": [
            {
              "district_type": "NATIONAL_EXEC",
              "city": "",
              "valid_from": "0001-01-01 04:56:02",
              "country": "NZ",
              "district_id": "NEW ZEALAND",
              "valid_to": null,
              "label": "New Zealand",
              "sk": 58,
              "subtype": "NATION",
              "state": "",
              "last_update_date": "2012-01-12 20:00:34",
              "data": {},
              "id": 58
            },
            {
              "district_type": "NATIONAL_LOWER",
              "city": "",
              "valid_from": "0001-01-01 04:56:02",
              "country": "NZ",
              "district_id": "Wellington Central",
              "valid_to": null,
              "label": "",
              "sk": 2648,
              "subtype": "LOWER",
              "state": "",
              "last_update_date": "2012-01-12 20:01:35",
              "data": {},
              "id": 2648
            },
            {
              "district_type": "NATIONAL_LOWER",
              "city": "",
              "valid_from": "0001-01-01 04:56:02",
              "country": "NZ",
              "district_id": "AT LARGE",
              "valid_to": null,
              "label": "",
              "sk": 2676,
              "subtype": "LOWER",
              "state": "",
              "last_update_date": "2012-01-12 20:01:35",
              "data": {},
              "id": 2676
            },
            {
              "district_type": "NATIONAL_LOWER",
              "city": "",
              "valid_from": "0001-01-01 04:56:02",
              "country": "NZ",
              "district_id": "Te Tai Tonga",
              "valid_to": null,
              "label": "",
              "sk": 2248,
              "subtype": "LOWER",
              "state": "",
              "last_update_date": "2012-01-12 20:01:35",
              "data": {},
              "id": 2248
            }
          ],
          "locator": "interpolation",
          "score": 100,
          "match_addr": "32 Molesworth St, Wellington 6011",
          "y": -41.27787258856771,
          "x": 174.77771067145628,
          "geoservice": "Bing"
        }
      ]
    }
  }
}

Next Steps

Using PHP? Try our “Hello World” example

To see an example of how to make a webpage in PHP using Cicero data, check out our Hello World Example.

Play around using a REST console in your browser

If you use Google Chrome, check out the REST Console App (available for free at the Chrome Web Store). You can use it set up content headers, build a request payload, and see response headers and the body with highlighted JSON or XML in a variety of color themes.

If you prefer Firefox, you can install the RESTClient add-on here. It includes many of the same features as the Chrome plugin, including header and payload creation and syntax highlighting.

Learn more about the different types of API calls

You can get detailed information about legislative bodies (chambers), governments, election and redistricting events, and more. Additionally, you can get map images, and even information about your account usage in a variety of formats. Go back to the index and take a look at everything that is available.

Learn about more advanced searching techniques

The new REST API supports searching with wildcards and dates, and allows searching on dozens of different fields. Be sure to learn how to query for these different field types and page through results.