Merge pull request #3 from datamade/query

Edits for query section
datamade · Jun 1, 2017 · 892b55f · 892b55f
2 parents 556ddb3 + 1c84530
commit 892b55f
Show file tree

Hide file tree

Showing 3 changed files with 188 additions and 27 deletions.
diff --git a/docs/endpoints.rst b/docs/endpoints.rst
@@ -19,26 +19,26 @@ The API contains eight different types of civic data. A unique endpoint represen
 
   * votes
 
-Independently filterable and searchable, the endpoints organize individual entries, each receiving a unique id. Displaying an entry reveals detailed information about a specified instance of civic data. 
+Independently filterable and searchable, the endpoints organize individual entries, each receiving a unique id, which points to detailed information about a specified instance of civic data. 
 
 Elements of an Endpoint
 ~~~~~~~~~~~~~~~~~~~~~~~
 
-Each endpoint has two parts: (1) the **listing pages**, which contain general information on each entity, and (2) the **detail pages**, which contain all available data on a given entity. Some entries also contain the names and ids of related entities stored in different endpoints.
+An endpoint has two parts: (1) the **listing pages**, which contain general information on entities, and (2) the **detail pages**, which contain all available data on a given entity. Some entries also contain the names and ids of related entities stored in different endpoints.
 
-    i. **Listing Page.** To access the listing page for a given endpoint, enter the following URL:
+    i. **Listing Page.** To access the listing page for an endpoint, enter a URL with the following pattern:
 
       ::
 
-          ocd.datamade.us/{end_point_name}/
+          ocd.datamade.us/{end point name}/
 
-      The endpoint name should be one of the following categories listed above. Example:
+      The endpoint name should be one of the categories listed above. Example:
 
       :: 
 
           ocd.datamade.us/events
 
-    ii. **Detail Page.** The listing page displays a collection of entries, and each entry receives a unique id that makes possible the entity detail page. To access a detail page, enter the following URL: 
+    ii. **Detail Page.** The listing page displays a collection of entries, and each entry receives a unique id that makes possible the entity detail page. To access a detail page, enter a URL with the following pattern: 
 
       :: 
 
@@ -57,12 +57,12 @@ Endpoint Details
 Bills
 #####
 
-The `bills endpoint <http://ocd.datamade.us/bills/>`_ contains information on individual pieces of legislation, including its classification, identifier, title, and subject. Each entry also provides the name and id of the organization that proposed the bill, the name and id of the bill jurisdiction, and the unique id of the bill itself.
+The `bills endpoint <http://ocd.datamade.us/bills/>`_ contains information on individual pieces of legislation, including the classification, identifier, title, and subject of the bill. Each entry also provides the name and id of the organization that proposed the bill, the name and id of the bill jurisdiction, and the unique id of the bill itself.
 
 Boundaries
 ##########
 
-The `boundaries endpoint <http://ocd.datamade.us/boundaries/>`_ contains geographic information on many of the divisions tracked by the API, primarily Illinois congressional districts, wards, and precincts. Unlike the other endpoints, boundary entities do not receive an id, but rather a URL. Each entry on the boundaries listing page contains the URL for the specific boundary, the URL of the boundary set (the parent set of the specific boundary), and the name and id of the division the boundary describes. The boundary-specific detail page contains URLs for the simple shape of the boundary, centeroid, boundary set and shape, as well as coordinates on its bound box.
+The `boundaries endpoint <http://ocd.datamade.us/boundaries/>`_ contains geographic information on many of the divisions tracked by the API, such as the Illinois congressional districts, wards, and precincts. Unlike the other endpoints, boundary entities do not receive an id, but rather a URL. Each entry on the boundaries listing page contains the URL for the boundary, the URL of the boundary set (the parent set of the specific boundary), and the name and id of the division the boundary describes. The boundary-specific detail page contains URLs for the simple shape of the boundary, centeroid, boundary set and shape, as well as coordinates on its bound box.
 
 Divisions
 #########
@@ -94,7 +94,7 @@ Votes
 
 The `votes endpoint <http://ocd.datamade.us/votes/>`_ contains information about every motion made on every piece of legislation within each jurisdiction tracked by the OCD API. The listing and detail pages within the votes endpoint also contain the name and id of the bill being voted on, and the organization conducting the vote. The detail page for each vote also lists the name and id of every voter and how they voted.
 
-Need more?
-~~~~~~~~~~
+Further Reading
+~~~~~~~~~~~~~~~
 
 More detailed information on the exact contents of listing and detail pages for endpoints can be found `here <http://docs.opencivicdata.org/en/latest/data/index.html>`_.
diff --git a/docs/index.rst b/docs/index.rst
@@ -3,31 +3,33 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-=============================
-Open Civic Data Documentation
-=============================
+=================================
+Open Civic Data API Documentation
+=================================
 
 Overview
 ========
 
-The primary goal of the Open Civic Data API (OCD) is to provide users with comprehensive, filterable database for exploring government data. The API allows users to search through information on legislation, politicians, governing bodies and divisions in an effort to make governments more transparent and accountable. The API is filtered using standard url query strings and returns data in an easily scrapable JSON format. DataMade uses the API to power many of its open government tools, including Chicago Councilmatic and LA Metro, but the database contains information on thousands of districts nationwide. The tool was created to help everyday citizens better understand their local governments and empower them to hold officials accountable to their constituents. 
+The Open Civic Data (OCD) API makes governments more transparent and accountable by providing a comprehensive, filterable library of government data. With this tool, everyday citizens can better understand local governments, track the legislative process, and hold officials accountable. 
+
+Users can conveniently explore information on legislation, politicians, governing bodies, and divisions. The API responds to standard URL query strings, and it returns data in an easily interpretable and scrapable JSON format. 
+
+`DataMade <https://datamade.us/>`_ uses the API to power many of its open government tools, including `Chicago <https://chicago.councilmatic.org/>`_, `NYC <https://nyc.councilmatic.org/>`_, and `Los Angeles Metro <https://boardagendas.metro.net/>`_ Councilmatics, but the database contains information on thousands of districts nationwide. 
 
 Requirements
 ============
 
-The Open Civic Data API is readily accessible to anyone with an internet browser. It requires no special programs or installations to run. However, because results are presented in JSON format, it’s helpful to have some kind of JSON reader to organize the page in a more user-friendly way. (JSONview is a great extension for people using Chrome [https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en] or Firefox [https://addons.mozilla.org/en-Us/firefox/addon/jsonview/])
+Anyone with an internet browser can readily access the Open Civic Data API. It requires no special programs or installations. The API, however, presents results in JSON. Thus, a JSON reader of some kind can help organize the page into a user-friendly, human-readable format. (JSONview, for instance, has an exceptional extension for `Chrome <https://chrome.google.com/webstore/detail/jsonview/chklaanhfefbnpoihckbnefhakgolnmc?hl=en>`_ or `Firefox <https://addons.mozilla.org/en-Us/firefox/addon/jsonview/>`_ users.)
+
 
+Learn more
+==========
+
+The following sections give a high-level overview of the OCD endpoints (i.e., the categories of civic data on the API) and walk through the process of querying the OCD library for specific results.
 
 .. toctree::
    :maxdepth: 2
 
    endpoints
    querying_endpoints
 
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
diff --git a/docs/querying_endpoints.rst b/docs/querying_endpoints.rst
@@ -1,20 +1,179 @@
 Querying Endpoints
 ==================
 
-Each of the endpoints can be individually filtered and searched to provide more specific results. While users can search the API using basic URL query strings, OCD also supports a handful of more advanced queries, including certain `Django URL Filters <https://github.com/miki725/django-url-filter>`_.
+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 <https://github.com/miki725/django-url-filter>`_.
 
 Query basics
 ~~~~~~~~~~~~
 
-    i. URL query strings always begin with a question mark (?)
+A question mark (?) always demarcates the beginning of a URL query string: 
 
       ::
 
-          http://ocd.datamade.us/bills/?{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
         
-    ii. If queries contain multiple parameters, separated them with an ampersand (&)
+
+Queries can contain multiple parameters. An ampersand (&) separates each parameter:
 
       ::
 
-          i.e. http://ocd.datamade.us/bills/?{param1}&{param2}&{param3}
+          # 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 <https://github.com/miki725/django-url-filter>`_.
+
+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