location.history

Location history can be requested by specifying the following:

A definite time period using a start and end date
A time period defined by the "last period of time" style query (last "24h", etc.)
A last number of records
A fix type filter

TR50 Request


                        // Definite time period request
{
  "cmd": {
    "command": "location.history",
    "params": {
      "thingKey": "mything",
      "start": "2014-01-01T00:00:00Z",
      "end": "2014-01-31T23:59:59Z",
      "offset": 1,
      "limit": 10,
      "showAddress": true,
      "returnIds": true,
      "showAll": false
    }
  }
}

// Last period of time request
{
  "cmd": {
    "command": "location.history",
    "params": {
      "thingKey": "mything",
      "last": "24h",
      "showAddress": true,
      "returnIds": true,
      "showAll": false
    }
  }
}

// Last number of records request
{
  "cmd": {
    "command": "location.history",
    "params": {
      "thingKey": "mything",
      "records": 100,
      "showAddress": true,
      "returnIds": true,
      "showAll": false
    }
  }
}

 
// Last number of records request, filtering by fixType
{
  "cmd": {
    "command": "location.history",
    "params": {
      "thingKey": "mything",
      "records": 100,
      "fixType": "GPS",
      "showAddress": true,
      "returnIds": true,
      "showAll": false
    }
  }
}

Request Parameters


Name	Type	Required	Description
	Thing Identifier Parameters		Identifies the Thing associated with the location entries. If omitted, the thingKey associated with your session will be used. See Thing Identifier Parameters table below for supported parameters.
showAll	Boolean		If true, all records will be returned that fall within the specified constraints. Otherwise, results will be intermediately sampled to stay within the platform's maximum number of data records.
start	String	Yes	When doing a definite time period request this is the timestamp for the start of the specified time window.
end	String	Yes	When doing a definite time period request this is the timestamp for the end of the specified time window.
last	String		When doing a last period of time request this specifies the last X amount of time in seconds (s), minutes (m), hours (h), or days (d).
records	Integer		When doing a last number of records request this specifies the number of records to return.
fixType	String		A filter to restrict the returned records to the fixType specified.
offset	Integer		The starting list offset, used for pagination. Defaults to 0 if not specified.
limit	Integer		Limit the number of results returned. Defaults to the configured maximum limit.
showAddress	Boolean		Whether to include the location address in the result entries.
returnIds	Boolean		Returns the id of the location

Thing Identifier Parameters


Name	Type	Description
thingKey	String	Key of the thing
thingId	String	Id of the thing
esn	String	Esn of the thing
iccid	String	Iccid of the thing
imei	String	Imei of the thing
imsi	String	Imsi of the thing
meid	String	Meid of the thing
msisdn	String	Msisdn of the thing

TR50 Response

If the command is sent successfully a success message and the result values found are returned. Otherwise, an error and error message will be returned.

The number of records returned is limited by the Management Portal. In cases where your selection has more results than the limit of the platform you should shorten your time window or lower the number of records you are requesting.


                        {
  "cmd": {
    "success": true,
    "params": {
      "sampling": 0,
      "values": [
        {
          "ts": "2014-06-23T10:26:02.558Z",
          "thingId": "531c907b5d80f1330c238757",
          "corrId": "trip-20140623-10:18:37",
          "lat": 26.39454,
          "lng": -80.11374,
          "fixAcc": 0,
          "fixType": "GPS",
          "heading": 329.5,
          "altitude": 0,
          "speed": 24,
          "delta": 413.87793470273
        },
        {
          "ts": "2014-06-23T10:26:40.878Z",
          "thingId": "531c907b5d80f1330c238757",
          "corrId": "trip-20140623-10:18:37",
          "lat": 26.39484,
          "lng": -80.11328,
          "fixAcc": 0,
          "fixType": "GPS",
          "heading": 72.6,
          "altitude": 0,
          "speed": 23,
          "delta": 56.735322393119
        },
        {
          "ts": "2014-06-23T10:26:42.238Z",
          "thingId": "531c907b5d80f1330c238757",
          "corrId": "trip-20140623-10:18:37",
          "lat": 26.39506,
          "lng": -80.11273,
          "fixAcc": 0,
          "fixType": "GPS",
          "heading": 0,
          "altitude": 0,
          "speed": 0,
          "delta": 60.05967424394
        }
      ]
    }
  }
}

Response Parameters


Name	Type	Description
values	Integer	An array of value objects describing the location entries.
sampling	Integer	If nonzero, the results have been sampled at this specific interval.

Value Object


Name	Type	Description
id	String	The id of the location (if returnIds set to true)
thingId	String	The unique identifier of the Thing associated with the location entry.
ts	String	The timestamp associated with the location entry.
duration	Int	The number of seconds that have elapsed since the previous location publish (the length of time the thing has been at the current location).
corrId	String	The correlation identifier associated with the location entry.
lat	Float	The latitude coordinate associated with the location entry.
lng	Float	The longitude coordinate associated with the location entry.
fixAcc	Float	The fix accuracy of the location data.
fixType	String	The fix type of the location data.
heading	Float	The heading associated with the location entry.
altitude	Float	The altitude associated with the location entry.
speed	Float	The speed associated with the location entry.
address	Object	Only included if showAddress is set to true. See location.decode response for address components.
delta	Float	The distance from the previous published location, in meters.