Querying Endpoints

The OCD endpoints, individually filterable and searchable, can return precise results about government data. The API responds to standard URL queries: users can search the API using basic query strings and also advanced query patterns, including certain Django URL Filters.

Query basics

A question mark (?) always demarcates the beginning of a URL query string:

# Basic pattern
http://ocd.datamade.us/events/?{query string}

# Example query - all events in the Los Angeles timezone

Queries can contain multiple parameters. An ampersand (&) separates each parameter:

# Basic pattern

# Example query - all canceled events in the Los Angeles timezone

A few useful calls

Filtering on data points

Each entry displays a collection of fields and corresponding data, e.g., an event has a classification, description, start_time, etc. Any of these data points may form the basis of a URL query:

# Basic pattern
http://ocd.datamade.us/bills/{data point}={value}

# Example query - all bills labeled as claims

Some fields contain arrays of data. Use a double underscore to separate the field names:

# Basic pattern
http://ocd.datamade.us/bills/{name of array}__{desired subset}

# Example query - all the bills processed by the Chicago City Council

And again, the API also accepts multiple parameters, separated by an ampersand (&):

# Filtering on more than one data point

Note: type the spaces if a value has multiple words, e.g, Grants of Privilege. The API will automatically replace spaces with the correct encoding (“%20”).


Most endpoints do not contain all entities on a single listing page. To navigate through all entries, run the “page” query:

# Returns the second listing page within the bills endpoint

Note: The boundaries endpoint is not paginated in this way. For now, this endpoint employs an offset + limit format. “Offset” refers to the index of the entity that is first displayed, and “limit” sets the number of entities viewable on each page.


The “sort” call orders entities in an endpoint by a specific parameter, in either ascending or descending order:

# Returns bills sorted in alphanumeric order by title
# Returns bills in reverse alphanumeric order by title

Finding all data points

The listing page does not show all accessible data points: that is, some data points only appear on the detail page of an entry. Fortunately, API queries can simultaneously sift through data on both the listing and detail pages.

# Returns bills with a latest action date of 2013-01-17

# Returns bills in ascending order (oldest to newest) of their latest action date

# Returns the second page of bills from New York City Council
# In descending order (newest to oldest) of the latest action date

Djano queries

The OCD API also responds to Django URL filters.

contains and icontains

The “contains” parameter is particularly helpful. As the name suggests, the query returns all entries containing a specified string in a given field. The “icontains” parameter performs the same function, but for case insensitive searches.

# Returns all bills with titles that include “Zoning Reclassification”

Get even more specific results: tack the two strings together.

# Return all Chicago City Council bills with titles that include “Zoning Reclassification”
# In descending order (newest to oldest) of the latest action date

Comparison operators

The API supports a number of comparison operators: greater than (gt), less than (lt), greater than or equal to (gte), and less than or equal to (lte).

# Returns all bills with at least one action taken after January 1, 2013

# Returns all bills with no actions taken after January 1, 2013

# Returns bills with at least one action taken on or after January 1, 2013

# Returns bills with at least one action taken on or before January 1, 2013


The “exact” filter returns entities containing an exact value for a specified field. The “iexact” filter performs the same function, but for case insensitive searches.

# Return all bills proposed under the jurisdiction of Chicago City Government

startswith and endswith

The “startswith” filter returns entities containing a value for a field that begins with a specified string. The “endswith” call does the same function for entity values that end with a specified string. The “istartswith” and “iendswith” calls perform the same function as their parent parameters, for for case insensitive searches.

# Returns bills with titles that begin with the exact phrase “Rahm Emanuel”

# Returns bills with titles that end with the phrase “Rahm Emanuel” (insensitive of case)