Esri's Geotrigger Service is replacing Geoloqi! Learn More | FAQ

location/update

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 Required
    The date of the recorded point, in ISO8601 format
  • location Required
    An object with two elements, "position" and "type". See the "location" section below
  • client Required
    An object corresponding to the client information. See the "client" section below
  • raw Optional
    Any key/value pair included in the "raw" section will be returned when the API is queried. See the "raw" section below.
  • uuid Optional
    A uuid for this point. If omitted, the server will generate one

location

The "location" block is composed of "type" and "position".

  • type Required
    Currently 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 Required
    Position is an object with the keys listed below.

position

  • latitude Required
    The latitude of the point being recorded.
  • longitude Required
    The longitude of the point being recorded.
  • speed Optional
    The speed of the point being recorded, given in kilometers per hour.
  • altitude Optional
    The altitude of the point being recorded, given in kilometers.
  • horizontal_accuracy Optional
    The horizontal accuracy of the of the point, given in meters.
  • vertical_accuracy Optional
    The 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 Required
    The platform name the client is running on, for example, "iPhone OS 4.0.1", "Palm WebOS", "Android Donut", "ruby" are possible values.
  • hardware Required
    The hardware version the client is running. For example, an iPhone 3GS returns the string "iPhone2,1". See this page for more details.
  • name Required
    For official Geoloqi clients, this value should be set to "Geoloqi". For other clients, set a descriptive name for your application.
  • version Required
    The 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.