Developer Guide
Using the Get Location API
4.0 Using the Get Location API
You can use the Get Location API to obtain location information for a particular user.
Before using the Get Location API, you must obtain a Veriplace user identifier so you can request permission to locate the user.
4.1 About Location
Veriplace models location as both a geographical position and an accuracy measurement. The degree of accuracy available depends on three things – 1) the degree the user wants to reveal, 2) the degree that can be obtained by the carrier, and 3) the location mode being used by the application - see 4.2.6 Using Location Modes.
When thinking about location, keep in mind the following considerations:
- User preference is primary. If users limit access or accuracy, your application cannot force access or obtain a greater degree of accuracy.
- If users turn their phones off, current location information will not be available. In these cases, cached location information, or location information recorded during an earlier connection, may be available if the user permits its use.
- Carriers vary in their ability to pinpoint their users. Location derived form a single cell tower is less accurate than location derived from cell triangulation (two or more cell towers) or from GPS.
- Obtaining location information involves a tradeoff of time, cost and accuracy. For example, the most accurate location information - that based on GPS - usually takes the most time to obtain and often incurs the highest cost. The least accurate information - cell tower – usually takes the least time to obtain and as often available more cheaply.
4.2 Obtaining User Location
Your application can obtain location information for a mobile user whose identity you have previously obtained. You may make the request in one of three ways:
- a synchronous request which blocks until the result is ready;
- an asynchronous request which returns immediately, specifying a callback URL for Veriplace to push the result to your application;
- an asynchronous request which returns immediately, followed by a polling query to check for the result later.
All of these methods require an HTTP POST to a protected resource URL. Requests must be signed using HMAC-SHA1 and an Access Token representing the user's permission to be located. You can obtain the Access Token interactively, using the OAuth User Authorization process (in which case the uri parameter for authorization should be the same as the synchronous location request URL); or use the Verify Permission API to look up an existing Access Token for a user.
For synchronous requests, use the following URL:
https://veriplace.com/api/1.1/users/<userId>/locations
For asynchronous requests, use the following URL:
https://veriplace.com/api/1.1/request/users/<userId>/locations
The following optional parameters may be added to the URL query string:
- mode: the name of the location mode to use. See 4.2.6 Location Modes.
- callback: for asynchronous requests only, a URL where your application can receive HTTP an notification from Veriplace. See 4.5 Getting Asynchronous Results. Note that this must be a valid externally accessible URI; it cannot be at localhost.
- withNearestPOI=true: add this parameter if you want Veriplace to search for a nearby "point of interest". See 4.2.9 Points of Interest.
- withNearestIntersection=true: add this parameter if you want Veriplace to search for a nearby street intersection. This feature is not enabled for all applications. See 4.2.9 Points of Interest.
4.2.1 Accuracy
The accuracy for location information is determined by two measurements:
- Coordinates for longitude and latitude.
- An integer signifying the radius of uncertainty in meters.
The first measurement specifies the proximate location of the user, while the second measurement indicates an area around that location where the user is believed to be with a known probability.
Applications cannot require or specify a degree of accuracy for the following reasons:
- Carriers can employ a range of methods to locate users that vary in their accuracy.
- Users can opt to turn off location-finding for their device.
- Users can modify location-finding accuracy and limit the results to a general area, such as a city.
4.2.2 Relevance
Relevance refers to the timeliness of location information. Location information can be obtained in two formats – position determination (real-time) and cached. Position determination is more relevant, but this method may take longer to obtain location information.
Cached location information can be retrieved very quickly, and some location request strategies may optimize the retrieval so the information is recent and relevant.
4.2.3 Latency
Latency refers to the delay in obtaining location information after requesting it. Obtaining user location information can take time. Some position determination technologies, such as cell tower position determination, usually take very little time. Other methods need more time. For example, an A-GPS request typically takes 30 seconds but can take up to 90 seconds in extreme conditions, in part because A-GPS must retrieve almanac and ephemeris data from the network, obtain sufficiently strong satellite signals, perform the positioning computation, and finally return the results back to the requestor.
Applications that require low latency requests are encouraged to pick their location mode accordingly.
4.2.4 User Location Restrictions
Developers should be aware that users may want to restrict when and how they can be located. Some options Veriplace gives users include:
- Do not locate me more than # times per day/week/month.
- Do not locate me too frequently.
When the limits set by the user are met, location information cannot be retrieved for that user until the specified time period has elapsed. In these cases, the response message indicates the user has prevented the release of their location. Your application can use this code to prevent reiterative requests for more information until a certain amount of time has elapsed.
- Do not/only locate me at certain times of day.
The user’s device will not respond if time and dates windows for access have been specified by the user. Your application will get an error code indicating that access to location was restricted for privacy reasons.
- Do not locate me with too much accuracy.
The user can ask that their location be provided with less accuracy.
- Locate me only once before asking permission again.
The user can ask that you apply for permission each time you try to locate the user. In this case, the returned Access Token will not be valid for additional location requests.
4.2.5 Common Failure Conditions
The user cannot be located if any of the following conditions apply:
- User’s device is turned off or outside of coverage.
- User has restricted access to their location.
- Position determination fails to locate the user.
In these cases, an appropriate error code is returned so that the application can determine whether to try again or wait a suitable amount of time before re-trying.
4.2.6 Location Modes
Veriplace uses a variety of methods to identify the locations of users, including single cell tower, cell tower triangulation, and GPS among others. It is possible that wireless carriers will provide some methods but not others. Each method has advantages and drawbacks. For example, some are more accurate but slower while others are faster but cost more. Some methods are not always available at the same level of quality. For example, users in a rural area will get much lower accuracy from cell tower location because cell towers tend to be spread further apart in rural areas, while GPS can be imprecise in the densest urban environments due to reflection and interference from buildings.
To reduce the complexity of choices faced by your application, Veriplace provides the capacity to select the most appropriate mode of obtaining location information for your application. Veriplace currently provides a default mode that is free to use:
|
freedom |
Freedom mode is Veriplace's default location mode. This basic mode lets developers locate smartphone users for free. Most GPS enabled smartphones are supported, though there are no guarantees regarding the relevance or accuracy of the data. |
|---|
In addition, Veriplace currently provides two modes for professional access to location. These are intended for developers who are willing to pay for greater coverage rather than be limited to only locating smartphones:
|
zoom |
Zoom mode is suited for applications that want to determine, as precisely as possible, where a user is now, regardless of phone type. Zoom mode returns the highest accuracy possible for a given user and situation. Accuracy is optimized at the expense of higher latency and cost. |
|---|---|
|
area |
Area mode is suited for applications that only need to know the general area a user is presently in, typically at neighborhood- or city-level accuracy. Like zoom mode, area mode is not limited to smartphones. Latency and cost are reduced at the expense of accuracy. |
You can specify the mode you want to use with the following URL, which uses the zoom location mode as an example:
https://veriplace.com/api/1.0/users/<userId>/locations?mode=zoom
4.2.7 Expiration Dates
The expiration date for permission to use a user’s location data is specified in the location response XML encoding using the data element named expires as defined below.
<xs:element name="expires" type="xs:dateTime"/>
Every XML document containing location data that Veriplace returns indicates the expiration time of these data with an expires element, as shown below.
<expires>2008-01-14T23:06:39Z</expires>
Your application must not use or retain location data past its expiration date.
4.2.8 Get Location Sequence Diagram
There are five steps of communication that occurs between your application and Veriplace during the process of trying to obtain location information on a single user. These are illustrated in the sequence diagram below.
The sequence of events illustrated above is described below.
- Your application requests an OAuth Request Token using the Veriplace Request Token URL, which is granted.
- Your application redirects the User Agent to the Veriplace user authorization URL.
- Your application is re-directed back with permission.
- Your application exchanges the Request Token for an OAuth Access Token, which is granted.
- Your application uses the Access Token to obtain location information for a single user.
When the process is complete, your Access Token may or may not be reused, depending on the level of permission granted in Steps 2 and 3.
4.2.9 Points of Interest and Street Intersections
Using the optional withNearestPOI=true parameter, you can ask Veriplace to query a map service for the nearest "point of interest" to the user's location. A point of interest can be a business or other landmark that could serve as a point of reference for describing the user's whereabouts. Veriplace will provide the following information:
- name
- category (e.g. "Restaurants")
- position (using the same format as the user's location)
- phone number, if available
- distance from the user's location, in meters
- heading from the user's location, in degrees clockwise from due north
Similarly, you can also specify the parameter withNearestIntersection=true, to query the nearest street intersection to the user's location. If available, this is returned as a position in the same format as a user location, but with two street names. Note that this feature (unlike the point of interest query) is currently not enabled by default, because the underlying service has higher overhead; please contact WaveMarket if you would like to use it.
4.3 Successful Requests
If a synchronous location request is successful, you will receive an HTTP 200 ("OK") code and a response representing the user's location. This has the following properties:
- A unique ID specific to this location request.
- The date and time that the location was generated.
- An expiration date after which the location must be discarded.
- Longitude and latitude, measured in degrees.
- An uncertainty radius, measured in meters.
- Optional geographic address fields: street address, city, neighborhood, state, postal code, and country code. Veriplace attempts to calculate these for every location, but they will not always be available.
The XML encoding of a location response, when all of the above properties are present, looks like this. Note that <address>, or any element within <address>, may be absent.
<?xml version="1.0" encoding="UTF-8"?>
<location xmlns="http://veriplace.com/xml/1.1" id="1234">
<created>1970-01-14T23:06:39Z</created>
<expires>1970-01-14T23:06:39Z</expires>
<position>
<longitude>-122.123456</longitude>
<latitude>37.123456</latitude>
<uncertainty>100.0</uncertainty>
<address>
<street>5858 Horton St</street>
<city>Emeryville</city>
<neighborhood>Downtown</neighborhood>
<state>CA</state>
<postal>94608</postal>
<countryCode>USA</countryCode>
</address>
</position>
</location>
The same response in JSON encoding:
{
"location": {
"id": 1234,
"created": "1970-01-14T23:06:39Z",
"expires": "1970-01-14T23:06:39Z",
"position": {
"longitude": -122.123456,
"latitude": 37.123456,
"uncertainty": 100.0,
"address": {
"street": "5858 Horton St",
"city": "Emeryville",
"neighborhood": "Downtown",
"state": "CA",
"postal": "94608",
"countryCode": "USA"
}
}
}
}
If Veriplace includes a nearby point of interest in response to the withNearestPOI parameter, the following elements are added:
<?xml version="1.0" encoding="UTF-8"?>
<location xmlns="http://veriplace.com/xml/1.1" id="1234">
<!-- created, expires, position: same as above -->
<nearPointOfInterest>
<pointOfInterest>
<name>Amtrak Station</name>
<category>Train Stations</category>
<position>
<longitude>-122.12344</longitude>
<latitude>37.123456</latitude>
<!-- may also include address -->
</position>
<phone>111-555-1212</phone>
</pointOfInterest>
<distance>100.0</distance>
<heading>270.0</heading>
</nearPointOfInterest>
</location>
{
"location": {
/* (id, created, expires, position: same as above) */
"nearPointOfInterest": {
"pointOfInterest": {
"name": "Amtrak Station",
"category": "Train Stations",
"position": {
"longitude": -122.12344,
"latitude": 37.123456
},
"phone": "111-555-1212"
},
"distance": 100.0,
"heading": 270.0
}
}
}
If Veriplace includes a street intersection in response to the withNearestIntersection parameter, the following elements are added:
<?xml version="1.0" encoding="UTF-8"?>
<location xmlns="http://veriplace.com/xml/1.1" id="1234">
<!-- created, expires, position: same as above -->
<nearIntersection>
<intersection>
<position>
<longitude>-122.12344</longitude>
<latitude>37.123456</latitude>
<address>
<street>Hollis St.</street>
<street2>59th St.</street2>
<!-- also includes city, state, etc. -->
</address>
</position>
</intersection>
<distance>100.0</distance>
<heading>270.0</heading>
</nearIntersection>
</location>
{
"location": {
/* (id, created, expires, position: same as above) */
"nearIntersection": {
"intersection": {
"position": {
"longitude": -122.12344,
"latitude": 37.123456,
"address": {
"street": "Hollis St.",
"street2": "59th St."
}
}
},
"distance": 100.0,
"heading": 270.0
}
}
}
4.3.1 Successful Asynchronous Requests
For an asynchronous location request, if the user ID and Access Token were valid, you will receive an HTTP 200 code and a unique identifier, or nonce, representing the location request. You can use this value as an association key later when you get the result; see 4.5 Getting Asynchronous Results. The XML encoding of this value is as follows:
<?xml version="1.0" encoding="UTF-8"?>
<nonce xmlns="http://veriplace.com/xml/1.1" value="1234567890"/>
Or, in JSON encoding:
{ "nonce": { value: "1234567890" } }
4.4 Unsuccessful Location Requests
In accordance with the HTTP Response Codes section of the OAuth specification, you will receive an HTTP 400 ("Bad Request") or 401 ("Unauthorized") code if something went wrong with the OAuth signature. In some cases, a 401 error code will be accompanied by the reason phrase "Invalid / non-monotonic timestamp", which is commonly a sign that your system clock is misconfigured.
In addition, successful HTTP responses may still return several possible errors (defined by Veriplace XML Schema) that can occur when trying to obtain location. The errors are marked by a position error element in the response, which replaces the position element. The position error element may (but will not always) contain a cached position element representing the last known successful location result for this user. In XML, a response with an error and a cached position looks like this:
<?xml version="1.0" encoding="UTF-8"?>
<location xmlns="http://veriplace.com/xml/1.1" id="1234">
<created>1970-01-14T23:06:39Z</created>
<expires>1970-01-14T23:06:39Z</expires>
<positionError>
<code>100</code>
<message>Subscriber could not be located.</message>
<cachedPosition>
<longitude>-122.123456</longitude>
<latitude>37.123456</latitude>
<uncertainty>100.0</uncertainty>
</cachedPosition>
</positionError>
</location>
The same response in JSON encoding:
{
"location": {
"id": 1234,
"created": "1970-01-14T23:06:39Z",
"expires": "1970-01-14T23:06:39Z",
"positionError": {
"code": 100,
"message": "Subscriber could not be located.",
"cachedPosition": {
"longitude": -122.123456,
"latitude": 37.123456,
"uncertainty": 100.0
}
}
}
}
4.4.1 Position Failure (100)
This error code will be returned if location could not be obtained because, for example, the mobile device is turned off, out of service or unable to get a good GPS signal indoors.
4.4.2 Restricted (200)
This error code will be returned if the user has restricted access to their location. Access should be available at another time.
4.4.3 Permission Denied Message
In the event of an HTTP 401 ("Unauthorized") code, the provided Access Token should be considered invalid (or may have been revoked by the user). In this case, the Access Token should be discarded and user authorization obtained again.
4.4.4 Billing Not Authorized Message
In the event that a Veriplace location request incurs a cost and you do not have sufficient credit to cover this cost, you will receive an HTTP 403 ("Forbidden") code. In this case, additional credit must be added to your account balance.
4.5 Getting Asynchronous Results
As described above (4.2 Obtaining User Location), you may choose to post a location request to Veriplace and proceed with other tasks, rather than waiting until the location is available. This decision depends only on what is convenient for the architecture of your application; Veriplace processes the location request the same way in either case, the only difference is in how it delivers the result.
4.5.1 Querying Results
If you make an asynchronous request and do not specify a callback parameter, then it is up to you to query Veriplace for the result at some point in the future. You can do this by making an HTTP GET request to the following protected resource URL, using the same nonce value that was returned when you made the original request:
https://veriplace.com/api/1.1/requests/<nonce>
You can repeat the query as many times as necessary. If the request has completed, Veriplace returns an HTTP 200 status and an XML position or position error response, as described in 4.3 Successful Requests and 4.4 Unsuccessful Requests. If the request has not yet completed, Veriplace returns an HTTP 204 status ("No Content").
After 24 hours, the asynchronous request expires and any further queries with that nonce value will receive an HTTP 404 error.
4.5.2 Receiving Results by Callback (Push)
If your application can receive HTTP requests, you can tell Veriplace to push results to you at a URL of your choice, which you specify as the callback parameter of the asynchronous location request. Veriplace will make an HTTP POST request to this URL, using the application/x-www-form-urlencoded content type with the following parameters:
- nonce: the unique identifier that was returned when you made the original request
- user: the Veriplace user ID
- code: the HTTP status code representing the outcome of the request (200 if successful)
- reason: an optional error description, equivalent to the HTTP status message
- location: the Veriplace location ID, if the request was successful
For security reasons, the callback does not contain the actual location data. Instead, use the value of the location parameter to retrieve the location data using the Past Location API.
To confirm receipt of the callback, your application must return an HTTP 200 response within 2000 milliseconds. Otherwise, Veriplace will consider the request a failure and will retry up to 3 times before giving up.