Querying the Cicero API

To query Cicero data, you will need to use the correct API endpoint along with the user ID and token obtained using your username and password. Look at the documentation for each object type to see what fields may be used.

Querying with wildcards

Use an asterisk (*) at the beginning, end, or middle of a phrase, or at both the beginning and the end to find results where the value starts with, ends with, or contains the text provided.

Search Matches
*lark Clark, Klark, Lark
Johns* Johnson, Johnston, Johns
Je*ings Jenings, Jennings, Jellings
*enning* Jennings, Pennington

Querying with an OR condition

To query a field with an OR condition, simply use that parameter as many times as needed for each condition to test.

Example: To find elected officials with the last name Jones, Lee, or Rodriguez, use:

http://cicero.azavea.com/v3.1/official?last_name=Jones&last_name=Lee&last_name=Rodriguez

Querying boolean values

Use ‘true’, ‘false’, and ‘null’ in the query string when querying boolean values.

Example: To find by-elections (also known as special elections), we can query the is_by_election field:

http://cicero.azavea.com/v3.1/election_event?is_by_election=true

Example: To find elections that are not by-elections, or if it is unknown whether or not they are by-elections, we can combine the use of ‘false’ and ‘null’:

http://cicero.azavea.com/v3.1/election_event?is_by_election=false&is_by_election=null

Note

The default ascending sort order for booleans is null, false, true.

Querying dates

In addition to querying a specific date, you may also search
  • before a date by adding _before to the field name
  • after a date by adding _after to the field name
  • on or before a date by adding _on_or_before to the field name
  • on or after a date by adding _on_or_after to the field name
  • between a range of dates by using a combination of fields

Example: To find elections ending in November 2012, use:

http://cicero.azavea.com/v3.1/election_event?election_expire_date_on_or_after=2012-11-01&election_expire_date_on_or_before=2012-11-30
Some relative dates are also acceptable in place of specific dates:
  • today uses the current UTC date
  • tomorrow uses the current UTC date, plus 24 hours
  • yesterday uses the current UTC date, minus 24 hours

Example:

http://cicero.azavea.com/v3.1/redistricting_event?redistricting_date_after=today

Note

Because relative dates are based on Universal Coordinated Time (the time on our servers), results may be a day offset from your users’ location. For example, if it is 8pm in New York, using on_or_after will not return results matching the current date in New York (it would be midnight or 1am the next day in UTC, depending on whether or not daylight savings time is in effect).

In order to avoid this issue, use an absolute date based on the user’s timezone. It is possible to determine the user’s timezone by using JavaScript and sending it back to your server with a request made by the client (such as a hidden form variable, or AJAX call).

Table Of Contents

Previous topic

Getting Started with the Cicero API

Next topic

Querying by Location