Developer Guide
Using the Polling API
10.0 Using the Polling API
While the Get Location API provides access to location data from one user at a time, sometimes you may simply want to know if there have been recent location updates for any users of your application. This type of batch query is available through the Polling API. Based on the Simple Update Protocol (SUP) standard which many social network applications use for update feeds, the Polling API returns a list of unique identifiers representing location updates for users that your application has permission to locate; you can then query the location details for any of these identifiers. This is not a true push service, but by making Polling API queries at intervals in the background, you can design your application to use a push model for location updates and avoid querying users who have no new locations.
Note, the Veriplace Java and .NET SDKs provide support classes to further simplify the process so that you can simply designate a listener object to receive location updates. This chapter describes the low-level API in case you are not using these frameworks.
10.1 What Is a Location Update?
The Polling API detects locations that have already been obtained by Veriplace; it does not generate new location requests. Veriplace-enabled smartphones push their locations to the server at regular intervals. Also, for any type of phone, if any application has made a successful on-demand location request, Veriplace will cache that location and add it to the update list. Location updates are therefore equivalent to the locations you would get for any individual user by using Freedom mode with the Get Location API, but aggregated from all the users that your application can locate.
10.2 Update Periods
Location updates are cached within a time window that moves forward at fixed intervals. For instance, if the interval is 60 seconds, then a query issued at 12:00:01 might return updates from 11:00:00-12:00:00, and repeating the query would return the same results until 13:00:01, at which point the window would be moved forward by 60 seconds. This is only an example; the actual starting and ending times are determined by the server, and are communicated to your application in the query results, so that you can schedule your next query to be after the last ending time.
As specified by SUP, the results returned by each Polling API query include an "available periods" indicating what intervals are supported by the server. Currently, the default is 60 seconds, but your application can also request an interval of 5 minutes (300 seconds) or 10 minutes (600 seconds).
10.2 Querying the Update List
You can request a list of recent location updates by submitting an HTTP GET to:
https://veriplace.com/api/1.2/updates
Requests must be signed using HMAC_SHA1 and the application-specific Access Token.
To specify a time window other than the default of 60 seconds, add the query string parameter seconds, for example:
https://veriplace.com/api/1.2/updates?seconds=300
10.2.1 Successful Requests
On success, you will receive an HTTP 200 ("OK") code and a document representing the list of updates, if any.
The JSON encoding for this document is described in section 3 of the SUP specification. It consists of a list of tuples, each of which contains a Veriplace user identifier (see Using the User Discovery API) and a unique identifier representing the user's new location. The document also always has the following properties, whether there were any updates or not:
- period: the size of the time window, in seconds
- since_time, updated_time: the starting and ending point of the time window, respectively, in RFC3339 format
- available_periods: a list of tuples representing valid intervals you can specify for the time window, each of which contains a number of seconds and the URL you would use for a query with that interval
The corresponding XML encoding looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<locationUpdates xmlns="http://veriplace.com/xml/1.2">
<updatedTime>1970-01-14T23:06:39Z</created>
<sinceTime>1970-01-14T23:05:39Z</expires>
<period>60</period>
<userUpdates id="12345678"> <!-- this number is a user identifier -->
<update id="111222333444"/> <!-- a location update ID for that user -->
<update id="111222333445"/> <!-- another update for the same user -->
</userUpdates>
<userUpdates id="12345679">
<update id="111222333446"/> <!-- a location update ID for the second user -->
</userUpdates>
<availablePeriods>
<period seconds="60" uri="http://veriplace.com/api/1.2/updates?seconds=60"/>
<period seconds="300" uri="http://veriplace.com/api/1.2/updates?seconds=300"/>
<period seconds="600" uri="http://veriplace.com/api/1.2/updates?seconds=600"/>
</availablePeriods>
</locationUpdates>
10.2.2 Unsuccessful Requests
You will receive an HTTP 400 status code if the request was malformed, and an HTTP 401 status code if the provided application-specific access token was invalid.
10.3 Querying Location Details
To obtain the actual location data for any individual location update returned by the update list query above, submit an HTTP GET request to:
https://veriplace.com/api/1.2/updates/<updateID>
The token for this request must be an Access Token for locating that particular user, rather than the application-specific Access Token used for the update list query.
10.3.1 Successful Requests
On success, you will receive an HTTP 200 ("OK") code and a document describing a single location, using the same XML or JSON encoding provided by the Get Location API.
10.3.2 Unsuccessful Requests
A code of 400 indicates that the specified update ID was invalid; a code of 401 indicates that the request did not contain a valid Access Token for locating that user.