IOTO International Inc                                  October 17, 2019
                                                        


          

Goverlytics API: Reference and Developer Documentation

Status The Goverlytics API is currently in development. This document will be continuously updated, in parallel with development. Documentation will be added for new API resources and endpoints as they are implemented in the API. Existing URIs and methods are subject to change. For more information about the current status of this document, email IOTO International Inc at enquiries@ioto.ca. Copyright Notice Goverlytics® is a registered trademark. Except as expressly provided in the agreement, Goverlytics and its licensors exclusively own all associated intellectual property rights. You will not remove, alter or obscure any copyright, trademark, service mark or other proprietary rights notices incorporated in or accompanying the Goverlytics API. IOTO API Documentation [Page 1]


DOC 0001                       Goverlytics                  October 2019


Table of Contents

   1. Introduction ....................................................2
      1.1. API Reference ..............................................3
      1.2. Authentication .............................................3
      1.3. Status Codes ...............................................3
           1.3.1. HTTP Status Codes ...................................4
           1.3.2. Error Types .........................................5
           1.3.3. Error Handling ......................................5
      1.4. Request Syntax .............................................6
           1.4.1. URL Encoding ........................................6
           1.4.2. AND OR Operators ....................................6
           1.4.3. Space Character .....................................6
           1.4.4. Proximity Operator ..................................7
      1.5. Pagination .................................................7
           1.5.1. Auto-Pagination .....................................7
      1.6. Versioning .................................................8
   2. Resources .......................................................8
      2.1. Debates ....................................................8
           2.1.1. Debates Endpoints and Methods .......................9
           2.1.2. The Debate Object ..................................10
      2.2. MPs .......................................................11
           2.2.1. MPs Endpoints and Methods ..........................11
           2.2.2. The MP Object ......................................12

1. Introduction

Introducing the Goverlytics API — a Canadian politics modelling and analytics engine. The Goverlytics API delivers analysis of Canadian political data in an accessible form and makes it easier for end-users to create their own customized analysis tools. The API is currently in its beta stage. We have extended a priority invitation to those who have expressed interest in the project. If you are curious about the API and would like an authentication credential, you can send an email to IOTO International Inc at enquiries@ioto.ca. For users with an authentication credential, we grant you a limited terminable license to copy and use our API. This license is subject to certain restrictions set out in the User Agreement, as well as additional restrictions outlined in Goverlytics’ Privacy Policy and Terms & Conditions. IOTO API Documentation [Page 2]


DOC 0001                       Goverlytics                  October 2019


1.1. API Reference

The Goverlytics API follows REST principles. It uses predictable resource-oriented URLs and returns JSON-encoded responses with standard HTTP response codes.

1.2. Authentication

The Goverlytics API uses access tokens to make access control decisions and authorize API requests. When a user logs in to a Goverlytics web application, the application receives an access token and a refresh token. The application passes the access token as a credential when it calls the API. Access tokens are sent on the Authorization header of every API request. They are represented as signed JSON Web Tokens (JWTs) and assert claims about the user and the user’s permissions. These claims are used to generate the JWT’s signature, which is validated by the Goverlytics API before it performs the requested operation. If the signature is invalid, the request will not be processed. Access tokens expire one hour after they are issued. Instead of requiring the user to re-authenticate, the Goverlytics web application will use a refresh token to obtain a new access token from the API.

1.3. Status Codes

Goverlytics uses standard HTTP response codes to indicate the success or failure of an API request: 2xx Success. 4xx Failure due to client error. 5xx Failure due to an error with our servers (these are rare). A 400 Bad Request error can be handled programmatically and will include an error code that briefly explains the error reported. IOTO API Documentation [Page 3]


DOC 0001                       Goverlytics                  October 2019


1.3.1. HTTP Status Codes

The Goverlytics API returns the following HTTP status codes in its response header: 200 OK Success. 400 Bad Request The request could not be accepted due to a missing or invalid parameter. Refer to the attached error code for more information. 401 Unauthorized No access token in the Authorization header of the API request. The user may not be logged in to the application. 403 Forbidden Invalid access token. The user does not have permissions to perform the request. 404 Not Found The requested resource does not exist. Check the request URI for invalid parameters. 405 Method Not Allowed The request method is not supported for the requested resource. 500 Internal Server Error The request may be valid, but an error within our servers prevented it from being completed. 503 Service Unavailable The request may be valid, but our servers are temporarily unavailable.

1.3.2. Error Types

When an invalid request causes an error that can be handled programatically, the Goverlytics API will return a 400 Bad Request code. It will also return information about the error type in the response body. This information can be used to resolve errors on the client side. The Goverlytics API can describe the following errors: 48: Invalid HTTP Method Invalid HTTP method selected for current endpoint. IOTO API Documentation [Page 4]


DOC 0001                       Goverlytics                  October 2019


   1516: Invalid Path
     Request URI contains invalid path parameters. See API 
     documentation for available andpoints.

   2342: Invalid Query String Parameter(s)
     Request URI contains invalid query string parameters. See API 
     documentation for available queries.

   815: Invalid Query String Value(s)
     Can be caused by any of the following:

     invalid_date_range
       Invalid date string in the date query. Use DDMMYY format.

     invalid_keywords_query
       Invalid search term in the keywords query. Remember to use 
       URL-encoded symbols and/or proximity operators.
     
     invalid_mp_name
       Invalid MP last name in the mp query. Our API could not find an MP 
       with that last name. Ensure that you are using the correct 
       spelling and that all symbols in the query are URL-encoded, 
       including spaces.
     
     invalid_party_name
       Invalid party name in the party parameter. Our API could not find 
       a Canadian political party with that name. Make sure you are using 
       the party’s common name. For example, “Liberal” or “NDP”.
     
     invalid_province_code
       Invalid province (or territory) abbreviation in the province 
       parameter. Remember to use a valid Canadian postal abbreviation. 
       This field is case-sensitive.
     
     invalid_riding_name
       Invalid riding name in the riding parameter. Our API could not 
       find a riding with that name. Ensure that you are using the 
       correct spelling and that all symbols in the query are 
       URL-encoded.

1.3.3. Error Handling

When the Goverlytics API encounters an error, it returns a 4xx or 5xx HTTP status code to the user, describing the error. The requested API operation is not completed.

1.4. Request Syntax

Invalid URI syntax in an API request will result in a 400 Bad Request or 404 Not Found error. These errors are sometimes caused by symbols, such as “-” and “‘“, being passed into the request URI without URL-encoding. Queries are not case sensitive, unless otherwise specified. IOTO API Documentation [Page 5]


DOC 0001                       Goverlytics                  October 2019


1.4.1. URL Encoding

Symbols used in query strings must be URL-encoded to be properly passed into the API request’s URI. Some helpful URL-encodings include: %20 [space character] %25 % %27 ‘ %2E . %24 $ %26 & %2D - %7C | You can see examples of URL-encoded symbols in the following subsections.

1.4.2. AND OR Operators

A user can pass multiple arguments into a single query string using the URL-encoded AND and OR operators, “&” and “|”. For example, to filter for debates that contain both of the keywords “pipeline” and “indigenous”: GET /debates?keywords=pipeline%26indigenous

1.4.3. Space Character

Another helpful URL-encoded character is the space character. It can be used to search for MPs that have a prefix before their last name. For example, to filter debates for speakers with the “van Rossum,” use: GET /debates?mp=van%20rossum The space character is accepted in all Goverlytics query strings, except for the keywords query.

1.4.4. Proximity Operator

URL-encoded spaces cannot be used in the keywords query. When filtering for a phrase, use the proximity operator “<->” instead. For example, to filter debates for mentions of “climate change” use: GET /debates?keywords=climate<->change The “-” in the proximity operator is actually a placeholder for word proximity. It can be replaced with an integer to find words that are within a certain proximity to each other. For example: GET /debates?keywords=green<10>energy IOTO API Documentation [Page 6]


DOC 0001                       Goverlytics                  October 2019


1.5. Pagination

Pagination increases API performance by limiting the number of objects fetched by each API call. Pagination decreases API response times, saves on unnecessary bandwidth usage, and avoids server-side errors from API response length limits. Goverlytics utilizes SQL-based pagination via the LIMIT and OFFSET clauses. A user may choose to paginate the results of their API request by specifying a limit parameter. The response will return only as many objects as the limit parameter specifies. For example, if a user wants to view the first 15 MPs in the Liberal party (as they are listed in the Goverlytics database), they should set the limit parameter to 15: GET /mps?party=liberal&limit=15 To access the next “page,” the user will need to adjust the offset parameter. To view the next 15 MPs, they should keep the limit at 15 and set the offset parameter to 15: GET /mps?party=liberal&limit=15&offset=15 This will send a request for the next 15 MPs.

1.5.1. Auto-Pagination

When an API response is very long and contains many objects, Goverlytics will auto-paginate results. For example, if a user requests all MP speeches that contain the word “climate,” Goverlytics may fetch only the first 10 speeches. If the user wants to read more, another request can be sent for the next 10 speeches. Auto-pagination utilizes the limit and offset parameters in the same way a user would. IOTO API Documentation [Page 7]


DOC 0001                       Goverlytics                  October 2019


   When backwards-incompatible changes are made to the API, we release 
   a new, dated version of the API. Older Goverlytics web applications 
   will continue to point to the old API and will continue to receive 
   up-to-date information from the Goverlytics server about Canadian 
   politics.

2. Resources

The Goverlytics API includes five resources: Debates, MPs, Bills, Votes, and Committees. When a successful API request is made to a resource endpoint, the Goverlytics API returns zero-to-many JSON objects of that resource type in its response body. Filter parameters can be used to sort or narrow down the set of results returned in an API response. Filters are appended to endpoint URLs as query strings. Multiple filters can be included in each query string, for example: GET /debates?mp=trudeau%7Cscheer and multiple query strings can be included in each request: GET /debates?province=BC&mp=May&keywords=climate Together, these techniques can be used to increase the granularity of API responses and to explore interesting subsets of data.

2.1. Debates

Debate objects allow you to view interjections made by MPs in the House of Commons. They contain a Hansard transcript of the MP’s interjection, as well as the date and time it occurred and the topics that were discussed. Debate objects are returned to the user in chronological order. Without any queries, the debates endpoint will return all of the debate objects associated with the current parliament session, paginated to 10 debate objects. IOTO API Documentation [Page 8]


DOC 0001                       Goverlytics                  October 2019


2.1.1. Debates Endpoints and Methods

All endpoints; with all possible methods, path parameters, and query parameters: Method | Endpoint | Path | Query String ---------------------------------------------------------- GET | /debates | | ?keywords=search_term | | | ?speaker=mp_last_name | | | ?party=party_name | | | ?province=province_code | | | ?riding=riding_name An example API request, using two filters (aggregates all Conservative MPs' speeches about pharmacare): GET /debates?keywords=pharmacare&party=NDP All paths and query strings are optional.
2.1.1.1. Debates Parameters
A description of each Debates parameter. Hierarchical parameters are added to the API request URI's path; non-hierarchical parameters, such as filters, are appended to the request's URI as query strings. Query Parameters: keywords Filter debates by speeches that contain a specific word or phrase. Use proximity operators to define a phrase. For example, “climate<->change”. speaker Filter debates by the last name of the speaker (an MP). party Filter debates by the party affiliation of the speaker, using the party’s common name. Accepted common names include (left column): Bloc The Bloc Québécois CCF The Co-operative Commonwealth Federation Conservative The Conservative Party of Canada Green The Green Party of Canada Liberal The Liberal Party of Canada NDP The New Democratic Party PPC The People’s Party of Canada Independent Independent IOTO API Documentation [Page 9]


DOC 0001                       Goverlytics                  October 2019


   province
     Filter debates by the speaker’s riding’s province (or territory). 
     Use ISO standard Canadian postal abbreviations, like “AB” for 
     Alberta. This field is case-sensitive.

   riding
     Filter debates by the speaker’s riding. Enter the full name of the 
     riding, including spaces and hyphens (use URL-encoding).

2.1.2. The Debate Object

Successful API calls to the debates resource will return a list of zero to many JSON debate objects in the response body. A debate object: { “time”: “10-31-2019 21:23:55”, “speech”: null, “speaker”: /mps/mp, “speech_contents”: null, “ranked_topics”: null, “wordcount”: 1234 }
2.1.2.1. Debate Object Attributes
Debate objects contain the following attributes: time (string) The date and time of the interjection. speech (string) A Hansard transcript of the entire interjection. speaker (string) The MP associated with this speech. speech_contents [string] Important topics mentioned in the speech. ranked_topics [string] Topics discussed in the interjection, ranked by relevance. Identifies the most likely topic of discussion. wordcount (int) The total number of words spoken in the interjection. For French interjections translated into English, this is the number of words in the English translation of the interjection. IOTO API Documentation [Page 10]


DOC 0001                       Goverlytics                  October 2019


2.2. MPs

MP objects allow you to view MPs currently sitting in the House of Commons. They contain a vital information about MPs, as well as which party they belong to, and which riding they represent. MP objects are returned to the user in alphabetic order, by last name. Without any queries, the debates endpoint will return all MPs that are members of the current parliament session.

2.2.1. MPs Endpoints and Methods

All endpoints; with all possible methods, path parameters, and query parameters: Method | Endpoint | Path | Query String ---------------------------------------------------------- GET | /mps | | ?party=party_name | | | ?province=province_code | | | ?riding=riding_name Another request, using two filters (aggregates all NDP MPs in British Columbia): GET /mps?party=ndp&province=bc All paths and query strings are optional.
2.2.1.1. MPs Parameters
A description of each MPs parameter. Hierarchical parameters are added to the API request URI's path; non-hierarchical parameters, such as filters, are appended to the request's URI as query strings. IOTO API Documentation [Page 11]


DOC 0001                       Goverlytics                  October 2019



    
   Query Parameters:

   party
     Filter MPs by their party affiliation, using the party’s common 
     name. Accepted common names include (left column):
 
         Bloc              The Bloc Québécois
         CCF               The Co-operative Commonwealth Federation
         Conservative      The Conservative Party of Canada
         Green             The Green Party of Canada
         Liberal           The Liberal Party of Canada
         NDP               The New Democratic Party
         PPC               The People’s Party of Canada
         Independent       Independent
 
   province
     Filter MPs by their riding’s province (or territory). Use ISO 
     standard Canadian postal abbreviations, like “AB” for Alberta. 
     This field is case-sensitive.
 
   riding
     Filter MPs by riding. Enter the full name of the riding, including 
     spaces and hyphens (use URL-encoding).

2.2.2. The MP Object

Successful API calls to the debates resource will return a list of zero to many JSON MP objects in the response body. An MP object: { “first_name”: null, “last_name”: null, “party_name”: null, “riding_name”: null, “riding _province”: null, “started”: “10-31-2019”, “twitter”: null, “headshot”: “filepath/to/picture” } IOTO API Documentation [Page 12]


DOC 0001                       Goverlytics                  October 2019


2.2.2.1. MP Object Attributes
Debate objects contain the following attributes: first_name (string) MP’s first name. last_name (string) MP’s last name. party_name (string) Common name of the party the MP is affiliated with. riding_name (string) Name of the MP’s riding. riding_province (string) Province (or territory) of the MP’s riding, as a standard Canadian postal abbreviation string (for example, "AB" for Alberta). start_date (string) Day the MP joined parliament (DD_MM_YYYY format). twitter (string) MP’s Twitter username. Can be passed along to the Twitter API to begin analyzing an MP’s Twitter activity. headshot (string) File path to the MP’s House of Commons headshot, as a string (on IOTO.ca site only). IOTO API Documentation [Page 13]

Html markup produced by rfcmarkup 1.129c, available from https://tools.ietf.org/tools/rfcmarkup/