API Documentation v0.3.0
All API methods for v0.3.0 use the following root URL http://revisit.global/api/v0/.
http://revisit.global/api/v0/facilities.json
The Revisit API adheres to the FRED API specification. Please refer to the FRED documentation for basic usage.
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.
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.
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.
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.
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.
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.
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.
--
Returns all of the sites within a given radius of the specified coordinate pair. rad defaults to 0, units defaults to km.
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'
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
--
Returns all of the sites within a given bounding box, specified by the north/south latitudes and east/west longitudes of the desired region.
within: (required) North latitude value, west longitude value, south latitude value and east longitude value
sector: (optional) Sector type of the facilities to return.
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
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.
--
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.
within: (required) North latitude value, west longitude value, south latitude value and east longitude value
compressed: (required)
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
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).
--
Returns all versions of the specified facility.
history: (required)
Get all updates to facility:
http://revisit.global/api/v0/facilities/5480d81d2ecfcf6908432694.json?history
All Revisit API endpoints that return a facilities JSON object allow for text search on the name field.
search: (required) Part of the name for facilities to return.
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".
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.
bulk: (required)
debug: (optional)
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
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"}}
]}