Contents |
URL
https://api.geoloqi.com/1/location/update
Description
Updates the current user's location with an array of data points.
Note: By default, all apps created after August 13, 2013 do not store location history for their users. If you would like to enable this feature, please contact [email protected] to request access. You will need to be able to demonstrate your application's need for storing and retrieving history, and we will work with you to find a paid plan that can accommodate your needs.
Supported Formats
JSON
Supported Request Methods
POST
Sample Input
This is an example of the iPhone client sending a single point of data. Note that the location object is enclosed in an array. It is possible to send multiple updates at once, but even if sending only one, it must be in an array.
[{ "date": "2010-07-23T09:19:38-07:00", "location": { "position": { "latitude": 45.445793867111, "longitude": -122.64261245728, "speed": 10, "altitude": 0, "horizontal_accuracy": 24, "vertical_accuracy": 0 }, "type": "point" }, "raw": { "distance_filter": 5, "tracking_limit": 2, "rate_limit": 60, "battery": 86 }, "client": { "name": "Geoloqi", "version": "0.1", "platform": "iPhone OS 4", "hardware": "iPhone2,1" } }]
Parameters
The input data must be an array of data points.
Points
A data point is a JSON object with the following elements:
- date RequiredThe date of the recorded point, in ISO8601 format
- location RequiredAn object with two elements, "position" and "type". See the "location" section below
- client RequiredAn object corresponding to the client information. See the "client" section below
- raw OptionalAny key/value pair included in the "raw" section will be returned when the API is queried. See the "raw" section below.
- uuid OptionalA uuid for this point. If omitted, the server will generate one
location
The "location" block is composed of "type" and "position".
- type RequiredCurrently only the "point" type is supported. In the future, we plan to support other types such as "polygon", "neighborhood", or others. Suggestions are welcome.
- position RequiredPosition is an object with the keys listed below.
position
- latitude RequiredThe latitude of the point being recorded.
- longitude RequiredThe longitude of the point being recorded.
- speed OptionalThe speed of the point being recorded, given in kilometers per hour.
- altitude OptionalThe altitude of the point being recorded, given in kilometers.
- horizontal_accuracy OptionalThe horizontal accuracy of the of the point, given in meters.
- vertical_accuracy OptionalThe vertical accuracy of the point being recorded, given in meters.
raw
The "raw" section of the data sent includes information specific to the official Geoloqi mobile clients. You can include arbitrary key/value pairs in this section that are specific to your application, and they will be returned verbatim when you query the API. You can use this field to record app settings at each location update, or any other custom data you wish.
client
These values are present so we can track the types and versions of clients sending data.
- platform RequiredThe platform name the client is running on, for example, "iPhone OS 4.0.1", "Palm WebOS", "Android Donut", "ruby" are possible values.
- hardware RequiredThe hardware version the client is running. For example, an iPhone 3GS returns the string "iPhone2,1". See this page for more details.
- name RequiredFor official Geoloqi clients, this value should be set to "Geoloqi". For other clients, set a descriptive name for your application.
- version RequiredThe version number of the application sending data. This may be "1.0" for the official iPhone app, or you can use your own versioning scheme such as a date stamp like "20100731".
Response
Success
{"response":"ok"}
A response of "ok" indicates that the platform has received the update. The first point is available immediately after the response is received. Any remaining points are processed asynchronously on the platform, so there may be a negligible delay before they become available to proceeding API calls.
Errors
If there was an error, you will get a different response code such as "400 Bad Request" and the JSON returned will contain a descriptive error message. See Error Codes for more information.
{ "error": "invalid_input", "error_description": "Input data must be an array of data points" }
You can check for errors by looking at either the HTTP response code or by checking the value of "response" in the object returned. The text in the "error" key will be the same as the HTTP response code. "description" will contain a human-readable description of the error which will hopefully help you track down the reason the call failed.