API Documentation

Logistimatics API

Endpoints

GET https://api.logistimatics.com/api/devices

GET https://api.logistimatics.com/api/positions

GET https://api.logistimatics.com/api/sensor

GET or POST https://api.logistimatics.com/api/command

PUT or DELETE https://api.logistimatics.com/api/webhook

Authentication

Send the following header with each request:

Authorization: Bearer API_KEY

With API_KEY set to the API key you received from us.

Need an API key? Please email us at hello@logistimatics.com.

/devices

Send a GET request to /devices and you will receive JSON response formatted like:

[
  {
    "device_id": "00000-02378",
    "name": "Shipment tracker",
    "last_ping_at": "2018-07-02T04:11:26.000Z",
    "battery_percentage": 5,
    "last_position_at": "2018-07-01T21:20:41.000Z",
    "latitude": 36.0904711111111,
    "longitude": -79.8008877777778,
    "address": "1201-1203 Grayland St, Greensboro, NC 27408, USA",
    "accuracy": 0
  },
  {
    "device_id": "00000-01131",
    "name": "#01131 Mobile-200",
    "last_ping_at": "2018-07-12T17:42:49.000Z",
    "battery_percentage": 50,
    "last_position_at": "2018-07-12T17:30:51.000Z",
    "latitude": 36.0670288888889,
    "longitude": -79.7904977777778,
    "address": "511 South Elm Street, Greensboro, NC 27406",
    "accuracy": 0
  },
  {
    "device_id": "00000-02236",
    "name": "#02236 Auto-320",
    "last_ping_at": "2018-07-12T17:43:14.000Z",
    "battery_percentage": 89,
    "last_position_at": "2018-07-12T17:05:46.000Z",
    "latitude": 36.08699,
    "longitude": -79.77139,
    "address": "1080 Homeland Avenue, Greensboro, NC 27405",
    "accuracy": 0
  }
]

/positions

Send a GET request the following query parameters:

  • device_id: Numeric (required). Logistimatics’ device serial number. Device serial numbers are on a sticker on the device and look like 0000-01234. For this API, only the digits past the hyphen are needed and leading zeroes can be elided (e.g. 01234 or 1234).
  • start_at: Numeric (optional). Seconds since Unix epoch. Defaults to 1 day before end_at.
  • end_at: Numeric (optional). Seconds since Unix epoch. Defaults to now.

For /positions, you will receive a JSON response formatted like:

[
  {
    "latitude": 43.3020888888889,
    "longitude": -96.44688,
    "address": "1696 Us 18 St, Lyon County, IA, USA",
    "timestamp": "2018-01-04T17:49:09+00:00",
    "accuracy": 0,
    "fix": "gps",
    "battery_percentage": 50
  },
  {
    "latitude": 43.30216,
    "longitude": -96.45152,
    "address": "1696 Us 18 St, Lyon County, IA, USA",
    "timestamp": "2018-01-04T17:48:49+00:00",
    "accuracy": 1000,
    "fix": "cell",
    "battery_percentage": 50
  },
  {
    "latitude": 43.3022355555556,
    "longitude": -96.4560622222222,
    "address": "1696 Us 18 St, Lyon County, IA, USA",
    "timestamp": "2018-01-04T17:48:29+00:00",
    "accuracy": 10,
    "fix": "wifi",
    "battery_percentage": 50
  }
]

Responses are limited to 10,000 records. Our trackers do not report more frequently than once every 20 seconds, so you should be able to pull 1-2 days worth of records at a time. We keep position records for 90 days.

/command

Send a POST request with a JSON body with the following parameters:

  • device_id: Numeric (required). Logistimatics’ device serial number. Device serial numbers are on a sticker on the device and look like 0000-01234. For this API, only the digits past the hyphen are needed and leading zeroes can be elided (e.g. 01234 or 1234).
  • command: String (required). Command string to send to the tracker to change reporting frequency, etc.

Each different hardware model has its own unique command format. We are happy to work with you to determine the correct command to send.

The response will look like

{
  "id": "a414130f-80c7-43d6-93b4-4707b60c19bb",
  "status": "queued",
  "created_at": "2019-05-01T01:23:45+00:00",
  "command": "YOUR_COMMAND_HERE",
}

with the status field set to "queued". The command will only be sent once the tracker checks in with our server and receives it. Queued commands will be retried for up to 24 hours. After that, they will expire and have their status sent to "failed".

To view the status of the last few commands sent to a tracker, you can send a GET request to /command to view the status of recent commands.

Send a GET request with the following query parameters:

  • device_id: Numeric (required). See above for explanation.
  • limit: Numeric (optional). Returns the last limit commands and responses to the commands. Defaults to 10, max is 100.

The response will be an array of records ordered in descending order by updated_at that looks like:

[{
  "id": "0c7bc4b9-de47-4eb4-8879-b144b43fe8c7",
  "status": "received",
  "created_at": "2019-05-01T02:23:46+00:00",
  "updated_at": "2019-05-01T02:23:46+00:00",
  "response": "RESPONSE_FROM_TRACKER"
}, {
  "id": "a414130f-80c7-43d6-93b4-4707b60c19bb",
  "status": "queued|sent|failed",
  "created_at": "2019-05-01T01:23:45+00:00",
  "updated_at": "2019-05-01T02:23:45+00:00",
  "command": "YOUR_COMMAND_HERE"
}]

Note that the "status" field for a command can be one of "queued", "sent", or "failed". Status "sent" means that the server sent the command to the tracker while "failed" means that the command timed out before being successfully sent.

Responses from the tracker will have a status "received" and payload in the "response" field. In general, there is no easy way to match a command and a response. This is a limitation of the firmware on every tracker model we have seen. We understand the inconvenience; we are forced to work around it in our own internal systems.

/sensor

Some of our devices provide temperature or other environmental information which is available through the /sensor endpoint. Currently this endpoint is in beta.

/webhook

Send a PUT request with the following body:

  • name: Unique name for this webhook. You may create multiple webhooks with different names.
  • url: Webhook URL to receive POST requests. You will receive a webhook request for every message a tracker sends.

On success, the webhook endpoint will return:

{
  "added": true // or false
}

It may take up to 5 minutes for a newly added webhook to begin sending data. If added is false, then a webhook with this name already exists. The existing webhook is not modified.

The webhook payload will have this form. Note that all fields, with the exception of meta.deviceId, are optional. Additional fields may be present.

{
  "meta": {
    "deviceId": "00000-01234",
    "name": "My tracker",
    "imei": "353549090779561",
    "sentAt": "2019-08-20T14:52:01Z",
    "receivedAt": "2019-08-20T14:52:01Z",
  },
  "position": {
    "timestamp": "2019-08-20T14:52:01Z",
    "latitude": 1.23,
    "longitude": -1.23,
    "address": "123 Main St",
    "altitude": 100, // meters
    "accuracy": 20, // meters. 0 or null means < 5 meters
  },
  "state": {
    "batteryPercentage": 85,
    "odometer": 12000, // meters
    "runtime": "234:32:20.123", // hours:minutes:seconds
  },
  "alarms": {
    "sos": true,
    "removal": true,
    "batteryLow": true,
    "motion": true,
    "temperatureLow": true,
    "temperatureHigh": true,
    "temperatureInRange": true,
    "temperatureOutOfRange": true,
    "lightLow": true,
    "lightHigh": true,
  },
  "sensor": {
    "temperature": 23, // deg celsius
  }
}

To delete a webhook, send a DELETE request with the following body:

  • name: Unique name of the webhook.

The response will look like:

{
  "deleted": true // or false
}

If deleted is true, the webhook was deleted. If deleted is false, then no webhook was found with this name.

Example

As a quick test, you might try

export API_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJvcmdhbml6YXRpb25faWQiOjI5MDcsImlhdCI6MTUyNDIzMjY0MH0.Y7V5DrNln059CxLpvlikp2MZ_0zY8I-pfD4EPqglrd4
curl -H "Authorization: Bearer ${API_KEY}" 'https://gps.logistimatics.com/api/positions?device_id=16590'