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. |