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

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.

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'