location.history

The location.history command is used to obtain historical location entries for a Thing.

location history can be requested by specifying:

  • 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": "2021-01-01T00:00:00Z",
      "end": "2021-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
thingKey String Yes* Key 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.
 *One of the above parameters is required to identify the thing.
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. A value of zero returns the global maximum number of records.
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. The maximum offset you can set is 5000
limit Integer Limit the number of results returned. The maximum limit you can set is 5000
showAddress Boolean Whether to include the location address in the result entries.
returnIds Boolean Returns the id of the location

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": "2021-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": "2021-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": "2021-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
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.

Any locations that are published for a Thing for dates that are between existing location publishes will show zero for the delta value, and the surrounding locations will not have their delta values recalculated.