> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pathstack.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Info>
  Devices are any telematics devices that you have connected through the PathStack portal. They can be anything for
  Truck GPS trackers to shipping trackers or boat beacons.
</Info>

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](/content/authentication) 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.

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://api.pathstack.io/device"

  querystring = {"telematics_provider":"navman"}

  headers = {"Authorization": "Bearer <access-token>"}

  response = requests.request("GET", url, headers=headers, params=querystring)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const options = {method: 'GET', headers: {Authorization: '<authorization>'}};

  fetch('https://api.pathstack.io/device', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```java Java theme={null}
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.util.Scanner;
  import org.json.JSONObject;

  public class DeviceRequest {
      public static void main(String[] args) {
          String url = "https://api.pathstack.io/device";
          String telematicsProvider = "navman";

          String fullUrl = url + "?telematics_provider=" + telematicsProvider;

          HttpURLConnection connection = (HttpURLConnection) new URL(fullUrl).openConnection();
          connection.setRequestMethod("GET");
          connection.setRequestProperty("Authorization", "Bearer <access-token>");

          try (Scanner scanner = new Scanner(connection.getInputStream())) {
              String responseBody = scanner.useDelimiter("\\A").next();
              JSONObject jsonResponse = new JSONObject(responseBody);
              
              // Access and use the parsed JSON data as needed
              // Example: String value = jsonResponse.getString("key");

              System.out.println(jsonResponse);
          }

          connection.disconnect();
      }
  }
  ```

  ```dotnet .NET theme={null}
  using System;
  using System.IO;
  using System.Net;
  using Newtonsoft.Json.Linq;

  class DeviceRequest
  {
      static void Main()
      {
          string url = "https://api.pathstack.io/device";
          string telematicsProvider = "navman";

          string fullUrl = $"{url}?telematics_provider={telematicsProvider}";

          HttpWebRequest request = (HttpWebRequest)WebRequest.Create(fullUrl);
          request.Method = "GET";
          request.Headers.Add("Authorization", "Bearer <access-token>");

          using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
          using (Stream responseStream = response.GetResponseStream())
          using (StreamReader reader = new StreamReader(responseStream))
          {
              string responseBody = reader.ReadToEnd();
              JObject jsonResponse = JObject.Parse(responseBody);

              // Access and use the parsed JSON data as needed
              // Example: string value = jsonResponse["key"].ToString();

              Console.WriteLine(jsonResponse);
          }
      }
  }
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.pathstack.io/device?telematics_provider=mtdata' \
    --header 'Authorization: Bearer <access-token>'
  ```
</CodeGroup>

This will return a response that looks something like this:

```json JSON theme={null}
{
  "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

<Info>
  A trip represents a journey that a device has taken from start to finish, and consist of many **positions**. A trip
  has a start and end position and time.
</Info>

<Note>
  Not all telematics providers have trip information. For cases where there is no trip information given, PathStack will
  use algorithms to estimate trips within the positions received.
</Note>

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

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://api.pathstack.io/device/{device_id}/trip"

  querystring = {
    "start_time_utc":"2024-01-09T10:58:39",
    "end_time_utc":"2024-01-10T10:58:39",
  }

  headers = {"Authorization": "Bearer <access-token>"}

  response = requests.request("GET", url, headers=headers, params=querystring)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const options = {method: 'GET', headers: {Authorization: 'Bearer <access-token>'}};

  fetch('https://api.pathstack.io/device/{device_id}/trip?start_time_utc=2024-01-09T10%3A58%3A39&end_time_utc=2024-01-10T10%3A58%3A39', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```java Java theme={null}
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.util.Scanner;
  import org.json.JSONObject;

  public class TripRequest {
      public static void main(String[] args) {
          String url = "https://api.pathstack.io/device/{device_id}/trip";

          String startTime = "2024-01-09T10:58:39";
          String endTime = "2024-01-10T10:58:39";

          String fullUrl = url + "?start_time_utc=" + startTime + "&end_time_utc=" + endTime;

          HttpURLConnection connection = (HttpURLConnection) new URL(fullUrl).openConnection();
          connection.setRequestMethod("GET");
          connection.setRequestProperty("Authorization", "Bearer <access-token>");

          try (Scanner scanner = new Scanner(connection.getInputStream())) {
              String responseBody = scanner.useDelimiter("\\A").next();
              JSONObject jsonResponse = new JSONObject(responseBody);

              // Access and use the parsed JSON data as needed
              // Example: String value = jsonResponse.getString("key");

              System.out.println(jsonResponse);
          }

          connection.disconnect();
      }
  }
  ```

  ```dotnet .NET theme={null}
  using System;
  using System.IO;
  using System.Net;
  using Newtonsoft.Json.Linq;

  class TripRequest
  {
      static void Main()
      {
          string url = "https://api.pathstack.io/device/{device_id}/trip";

          string startTime = "2024-01-09T10:58:39";
          string endTime = "2024-01-10T10:58:39";

          string fullUrl = $"{url}?start_time_utc={startTime}&end_time_utc={endTime}";

          HttpWebRequest request = (HttpWebRequest)WebRequest.Create(fullUrl);
          request.Method = "GET";
          request.Headers.Add("Authorization", "Bearer <access-token>");

          using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
          using (Stream responseStream = response.GetResponseStream())
          using (StreamReader reader = new StreamReader(responseStream))
          {
              string responseBody = reader.ReadToEnd();
              JObject jsonResponse = JObject.Parse(responseBody);

              // Access and use the parsed JSON data as needed
              // Example: string value = jsonResponse["key"].ToString();

              Console.WriteLine(jsonResponse);
          }
      }
  }
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url 'https://api.pathstack.io/device/{device_id}/trip?start_time_utc=2024-01-09T10%3A58%3A39&end_time_utc=2024-01-10T10%3A58%3A39' \
    --header 'Authorization: Bearer <access-token>'
  ```
</CodeGroup>

This will return a response that looks something like this:

```json JSON theme={null}
{
  "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

<Info>
  A position is a single point in time with a latitude and longitude. Positions are the building blocks of trips, and a
  trip may have hundreds or even thousands of positions.
</Info>

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.

<CodeGroup>
  ```python Python theme={null}
  import requests

  url = "https://api.pathstack.io/trip/{trip_id}/position"

  headers = {"Authorization": "Bearer <access-token>"}

  response = requests.request("GET", url, headers=headers)

  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const options = {method: 'GET', headers: {Authorization: 'Bearer <access-token>'}};

  fetch('https://api.pathstack.io/trip/{trip_id}/position', options)
    .then(response => response.json())
    .then(response => console.log(response))
    .catch(err => console.error(err));
  ```

  ```java Java theme={null}
  import java.net.HttpURLConnection;
  import java.net.URL;
  import java.util.Scanner;
  import org.json.JSONObject;

  public class PositionRequest {
      public static void main(String[] args) {
          String url = "https://api.pathstack.io/trip/{trip_id}/position";

          HttpURLConnection connection = (HttpURLConnection) new URL(url).openConnection();
          connection.setRequestMethod("GET");
          connection.setRequestProperty("Authorization", "Bearer <access-token>");

          try (Scanner scanner = new Scanner(connection.getInputStream())) {
              String responseBody = scanner.useDelimiter("\\A").next();
              JSONObject jsonResponse = new JSONObject(responseBody);

              // Access and use the parsed JSON data as needed
              // Example: String value = jsonResponse.getString("key");

              System.out.println(jsonResponse);
          }

          connection.disconnect();
      }
  }
  ```

  ```dotnet .NET theme={null}
  using System;
  using System.IO;
  using System.Net;
  using Newtonsoft.Json.Linq;

  class PositionRequest
  {
      static void Main()
      {
          string url = "https://api.pathstack.io/trip/{trip_id}/position";

          HttpWebRequest request = (HttpWebRequest)WebRequest.Create(url);
          request.Method = "GET";
          request.Headers.Add("Authorization", "Bearer <access-token>");

          using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
          using (Stream responseStream = response.GetResponseStream())
          using (StreamReader reader = new StreamReader(responseStream))
          {
              string responseBody = reader.ReadToEnd();
              JObject jsonResponse = JObject.Parse(responseBody);

              // Access and use the parsed JSON data as needed
              // Example: string value = jsonResponse["key"].ToString();

              Console.WriteLine(jsonResponse);
          }
      }
  }
  ```

  ```bash cURL theme={null}
  curl --request GET \
    --url https://api.pathstack.io/trip/{trip_id}/position \
    --header 'Authorization: Bearer <access-token>'
  ```
</CodeGroup>

This will return a response that looks something like this:

```json JSON theme={null}
{
  "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.](/content/pagination)