Start requesting data

Now that you have connected your devices up the PathStack, it’s time to start using it! There are many different types of data you can request, but we’ll focus on the 3 main types in this guide: Devices, Trips, and Positions.

​

Devices

Devices are likely to be the first resource that you would like to request. By requesting devices, you can then get a list of devices that you have access to, and can use the IDs of these devices to request more refined data such as trips.

To get a list of devices, Authenticate and make a call to the /device endpoint. This will return a list of devices that you have connected. Optionally, you can filter by the telematics provider.

This will return a response that looks something like this:

{
  "data": [
    {
      "system_device_id": "1",
      "registration": "TRUCK1",
      "make": "Volvo",
      "model": "FH600",
      "year": null,
      "active": true,
      "id": "38c6d776-b2de-488e-bcd3-be3df6df37ea",
      "connection_id": "c2708314-1fb4-4955-ab6d-1c6d0735d1d5"
    },
    ...
  ],
  "links": {
    "previous": null,
    "current": "/device?page=0",
    "next": null
  }
}

Each element in the list is a device, and there are attributes such as make and model. An important attribute is id, which you can use to get the trips for a particular device, which you will see in the next section.

​

Trips

Once you have the list of devices, you can fetch the trips for a device by making a call to /device/{device_id}/trip endpoint. You can filter trips by start time and end time by passing start_time_utc and end_time_utc.

This will return a response that looks something like this:

{
  "data": [
    {
      "start_latitude": -31.92827606201172,
      "start_longitude": 133.01011657714844,
      "end_latitude": -32.27043533325195,
      "end_longitude": 125.48701477050781,
      "system_trip_id": "1",
      "start_time": "2024-01-09T23:53:03",
      "end_time": "2024-01-10T08:14:54",
      "distance_metres": 752820.000000007,
      "duration_seconds": 30111,
      "driving_seconds": 30111,
      "idling_seconds": 30111,
      "auxiliary_seconds": null,
      "id": "cf096434-5169-401c-93ea-647d880b8350",
      "device_id": "38c6d776-b2de-488e-bcd3-be3df6df37ea"
    },
    ...
  ],
  "links": {
    "previous": null,
    "current": "/device/{device_id}/trip?page=0",
    "next": null
  }
}

Each element in the list is a trip which the device has taken, and there are additional attributes such as trip duration. An important attribute is id, which is the unique ID of the trip. This id can be used to request the positions for a trip, as you will see in the next section.

​

Positions

Once you have a list of trips, if you want you can request the positions for each trip, using the /trip/{trip_id}/position endpoint.

This will return a response that looks something like this:

{
  "data": [
    {
      "latitude": 0,
      "longitude": 0,
      "time": "2024-01-11T05:17:13.094Z",
      "speed_kilometres_per_hour": 0,
      "hdop": 0,
      "vdop": 0,
      "number_of_satellites": 0,
      "heading": 0,
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "trip_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
    },
    ...
  ],
  "links": {
    "previous": null,
    "current": "/trip/{trip_id}/position?page=0",
    "next": "/trip/{trip_id}/position?page=1"
  }
}

The Devices, Trips, Positions and Events endpoints are all paginated. You can find out more here.