API Documentation v0.3.0

Jonathan Wohl edited this page Sep 29, 2015 · 2 revisions

Revisit API

All API methods for v0.3.0 use the following root URL http://revisit.global/api/v0/.

Example

http://revisit.global/api/v0/facilities.json

Basic API

The Revisit API adheres to the FRED API specification. Please refer to the FRED documentation for basic usage.

Authentication

As per the FRED specification, the default authentication method Basic HTTP Authentication. At present, a username and password must be requested from the Sustainable Engineering Lab in order to modify Revisit data. In the future, we plan to implement an API key system that will allow clients to interact fully with the REST API.

Rate Limiting

In order to improve performance for all users, rate limiting is enforced on a per-IP basis. If designed properly, client applications should be able to use the Revisit API without exceeding these limits.

Modifications to the FRED API

In order to better suit our application some parts of the FRED API were not matched identically. Most of the changes add functionality, such as geo-spatial queries, and are detailed below with examples.

ID and supplied IDs for facilities

The FRED API states that facilities can be added with a custom ID field, however what that ID field is called is a bit ambiguous. The only ID field we allow and enforce is the uuid field. Please note that all queries for a specific site happen on that field. Unlike the FRED API, only 24 character hex values are permitted when submitting custom ids. This is true for bulk uploads as well. If an _id/id is passed in for an upload of any kind, it will be ignored.

Deletion

Revisit allows the deletion of facilities, however the underlying facility object is simply marked as deleted and is not destroyed. The "deleted" facility will only be shown in responses when requested with the showDeleted query parameter. Any authorized user can delete a facility however only admin users can request to see deleted facilities.

Pagination and additional fields in the facilities JSON object.

When querying Revisit endpoints you'll notice additional fields outside of the expected facilities array such as limit, offset and total. They are supplied for your convenience to help inform you of the available facilities in the database for that specific query. We have also added a hard limit of a thousand to the returned number of facilities, i.e limit=off is equivalent to limit=1000 in the Revisit API.

In addition to the limit and offset options specified in the FRED API, Revisit allows a paginated style for facilities JSON object responses. We provide per_page and page options which are used in place of limit and offset. If the page query param is found in the request, the paginated style is used, and the limit, offset, and total fields in the facilities JSON object response are replaced with page, per_page and total_entries.

Geo-Spatial Queries

In addition to the FRED API methods, the Revisit API offers several geo-spatial querying options. This is useful in situations where you want to a list of facilities within a certain distance of a specified coordinate pair, or find all of the facilities within a given region.

Note: All query parameters available on the facilities endpoint (defined in the FRED specification) also work with geo-spatial query parameters.

--

/facilities.json?near=lat,lng[&rad=num&units=mi]

Returns all of the sites within a given radius of the specified coordinate pair. rad defaults to 0, units defaults to km.

Parameters

near: (required) latitude and longitude coordinate

rad: (optional) radius in which to search, in kilometers, defaults to 0 so set it if you expect any results.

units: (optional) units for the radius, can be either 'km' or 'mi'; defaults to 'km'

Examples

Get facilities within 4 kilometers of (7.3859,5.113):

http://revisit.global/api/v0/facilities.json?near=7.3859,5.113&rad=4

Get facilities within 1 miles of (12.1859,9.113):

http://revisit.global/api/v0/facilities.json?near=12.185,9.11&rad=1&units=mi

--

/facilities.json?within=nlat,wlng,slat,elng

Returns all of the sites within a given bounding box, specified by the north/south latitudes and east/west longitudes of the desired region.

Parameters

within: (required) North latitude value, west longitude value, south latitude value and east longitude value

sector: (optional) Sector type of the facilities to return.

Examples

Get health facilities within the bounding box [(7.4859,5.113),(7.3859,5.213)]:

http://revisit.global/api/v0/facilities.json?within=7.4859,5.113,7.3859,5.213

Server-side Compression

In order to facilitate usage of the Revisit service on offline mobile devices, we've implemented a quadtree index combined with LZ compression which greatly reduces the size of the data while maintaining the ability to search it geographically. This way, a client application that uses data from the Revisit API can fetch and store facilities from a large geographic region with a minimal storage footprint.

--

/facilities.json?within=nlat,wlng,slat,elng&compressed

Returns all of the sites within a given bounding box, specified by the north/south latitudes and east/west longitudes of the desired region, in a compressed quadtree structure.

All nodes of the quadtree from the root down to the leaf nodes, which contain the data, are included in the result.

Parameters

within: (required) North latitude value, west longitude value, south latitude value and east longitude value

compressed: (required)

Examples

Get facilities within the bounding box [(7.4859,5.113),(7.3859,5.213)] as a compressed quadtree:

http://revisit.global/api/v0/facilities.json?within=7.4859,5.113,7.3859,5.213&compressed

History and Rollback queries

The Revisit API provides history for all facilities updated via the API. Specific facilities can be viewed to see all updates over time. This feature can be accessed via an additional query parameter to the site request.

Note: Facilities added outside the API or facilities added via the bulk upload endpoint will not have their original state recorded (i.e. version 0 == first update or first query to history).

--

/facilities/{uuid}.json?history

Returns all versions of the specified facility.

Parameters

history: (required)

Examples

Get all updates to facility:

http://revisit.global/api/v0/facilities/5480d81d2ecfcf6908432694.json?history

Text Search

All Revisit API endpoints that return a facilities JSON object allow for text search on the name field.

/facilities.json?search=searchTerm

/facilities.json?near=lat,lng[&rad=num&units=mi]&search=searchTerm

/facilities.json?within=nlat,wlng,slat,elng[&sector=type]&search=searchTerm

Parameters

search: (required) Part of the name for facilities to return.

Examples

Get facilities that contain Brooklyn in their name

http://revisit.global/api/v0/facilities.json?search=Brooklyn

Note: This text search does not match partial words, though it does perform word stemming. For example, searching "ru" would not return names that include the word "run", but searching for "running" would return names including the work "run".

Bulk uploads

The add facility endpoint allows for bulk uploads when specified. A facilities JSON object similar to the one returned in the facilities.json endpoint is expected to posted in either a file or the request body. The endpoint responds with a JSON object containing the number of facilities submitted, the number of facilities successfully saved, and the number of facilities rejected due to colliding uuids, missing required fields, or malformed format. Add the query parameter debug for a detailed error message for each failed facility.

/facilities.json?bulk[&debug]

Parameters

bulk: (required)

debug: (optional)

POST parameters

BODY: (optional if file supplied) A facilities JSON object matching the facility object returned in the facilities.json GET endpoint.

FILE: (optional if body posted) A facilities json object matching the facility object returned in the facilities.json GET endpoint

Examples

Posting a facilities JSON object with two facilities.

http://revisit.global/api/v0/facilities.json?bulk

In post body:

{facilities:[
    {"name":'Etobicoke General', "properties": {"sector": "health"}},
    {"name":'SickKids Hospital', "properties": {"sector": "health"}}
]}

Posting a facilities JSON object with two facilities with custom uuids and the debug flag set. The colliding uuids will allow the first facility to be created, but will generate an error for the second. The errors field in the response will describe the type of error when debug is set.

http://revisit.global/api/v0/facilities.json?bulk&debug

In post body:

{facilities:[
    {"name":'Etobicoke General', "uuid": "12345678901234567890abcd", "properties": {"sector": "health"}},
    {"name":'SickKids Hospital', "uuid": "12345678901234567890abcd", "properties": {"sector": "health"}}
]}
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.