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 http://ocd.datamade.us/events/?timezone=America/Los_Angeles
Queries can contain multiple parameters. An ampersand (&) separates each parameter:
# Basic pattern http://ocd.datamade.us/events/?{param1}&{param2}&{param3} # Example query - all canceled events in the Los Angeles timezone http://ocd.datamade.us/events/?timezone=America/Los_Angeles&status=cancelled
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 http://ocd.datamade.us/bills/?classification=claim
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 http://ocd.datamade.us/bills/?from_organization__name=Chicago%20City%20Council
And again, the API also accepts multiple parameters, separated by an ampersand (&):
# Filtering on more than one data point http://ocd.datamade.us/bills/?from_organization__name=Chicago%20City%20Council&classification=claim
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”).
Page¶
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 http://ocd.datamade.us/bills/?page=2
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.
Sort¶
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 http://ocd.datamade.us/bills/?sort=title# Returns bills in reverse alphanumeric order by title http://ocd.datamade.us/bills/?sort=-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 http://ocd.datamade.us/bills/?actions__date=2013-01-17 # Returns bills in ascending order (oldest to newest) of their latest action date http://ocd.datamade.us/bills/?sort=actions__date # Returns the second page of bills from New York City Council # In descending order (newest to oldest) of the latest action date http://ocd.datamade.us/bills/?sort=-actions__date&from_organization__name=New%20York%20City%20Council&page=2
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” http://ocd.datamade.us/bills/?title__contains=Zoning%20Reclassification
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 http://ocd.datamade.us/bills/?from_organization__name=Chicago%20City%20Council&title__contains=Zoning%20Reclassification&sort=-actions__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 http://ocd.datamade.us/bills/?actions__date__gt=2013 # Returns all bills with no actions taken after January 1, 2013 http://ocd.datamade.us/bills/?actions__date__lt=2013 # Returns bills with at least one action taken on or after January 1, 2013 http://ocd.datamade.us/bills/?actions__date__gte=2013 # Returns bills with at least one action taken on or before January 1, 2013 http://ocd.datamade.us/bills/?actions__date__lte=2013
exact¶
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 http://ocd.datamade.us/bills/?from_organization__jurisdiction__name__iexact=chicago%20City%20government
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” http://ocd.datamade.us/bills/?title__startswith=Rahm%20Emanuel # Returns bills with titles that end with the phrase “Rahm Emanuel” (insensitive of case) http://ocd.datamade.us/bills/?title__iendswith=rahm%20Emanuel