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

# Get Trips

> Get trips and stops for multiple devices within a date range.

Returns computed trips and stops from GPS telemetry for multiple devices. Trips are computed on-demand using motion detection.

## Query parameters

<ParamField query="from" type="string" required>
  ISO 8601 date string (start of time range).
</ParamField>

<ParamField query="to" type="string" required>
  ISO 8601 date string (end of time range). Max range: 31 days.
</ParamField>

<ParamField query="hardware_ids" type="string[]">
  Filter by hardware IDs. Repeated or comma-separated. Max 50 devices per request. Results are automatically scoped to devices you have access to.
</ParamField>

<ParamField query="speedThreshold" type="number" default="3">
  km/h — below this speed is considered stopped.
</ParamField>

<ParamField query="minimalTripDuration" type="number" default="300">
  Seconds — minimum moving time to count as a trip.
</ParamField>

<ParamField query="minimalTripDistance" type="number" default="500">
  Meters — minimum distance to count as a trip.
</ParamField>

<ParamField query="minimalParkingDuration" type="number" default="180">
  Seconds — minimum stopped time to end a trip.
</ParamField>

<ParamField query="minimalNoDataDuration" type="number" default="1800">
  Seconds — data gaps longer than this are treated as stops.
</ParamField>

<ParamField query="minimalAvgSpeed" type="number" default="1">
  km/h — minimum average speed to count as a trip.
</ParamField>

<ParamField query="maxAcceleration" type="number" default="10">
  m/s² — filter GPS spikes exceeding this value.
</ParamField>

## Response

<ResponseField name="trips" type="object[]" required>
  <Expandable title="Trip object">
    <ResponseField name="hardware_id" type="string" required>Device hardware ID.</ResponseField>
    <ResponseField name="startTime" type="string" required>Trip start time (ISO 8601).</ResponseField>
    <ResponseField name="endTime" type="string" required>Trip end time (ISO 8601).</ResponseField>
    <ResponseField name="startLocation" type="object" required>Start coordinates (`lat`, `long`).</ResponseField>
    <ResponseField name="endLocation" type="object" required>End coordinates (`lat`, `long`).</ResponseField>
    <ResponseField name="distance" type="number" required>Distance in meters.</ResponseField>
    <ResponseField name="duration" type="number" required>Duration in seconds.</ResponseField>
    <ResponseField name="maxSpeed" type="number" required>Maximum speed in km/h.</ResponseField>
    <ResponseField name="avgSpeed" type="number" required>Average speed in km/h.</ResponseField>
    <ResponseField name="pointCount" type="number" required>Number of GPS points in the trip.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="stops" type="object[]" required>
  <Expandable title="Stop object">
    <ResponseField name="startTime" type="string" required>Stop start time (ISO 8601).</ResponseField>
    <ResponseField name="endTime" type="string" required>Stop end time (ISO 8601).</ResponseField>
    <ResponseField name="location" type="object" required>Stop coordinates (`lat`, `long`).</ResponseField>
    <ResponseField name="duration" type="number" required>Duration in seconds.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="object" required>
  <Expandable title="Summary">
    <ResponseField name="totalTrips" type="number" required>Total trips found.</ResponseField>
    <ResponseField name="totalStops" type="number" required>Total stops found.</ResponseField>
    <ResponseField name="totalDistance" type="number" required>Total distance in meters.</ResponseField>
    <ResponseField name="totalDuration" type="number" required>Total trip duration in seconds.</ResponseField>
    <ResponseField name="totalStopDuration" type="number" required>Total stop duration in seconds.</ResponseField>
    <ResponseField name="positionsAnalyzed" type="number" required>GPS positions processed.</ResponseField>
    <ResponseField name="devicesQueried" type="number" required>Number of devices queried.</ResponseField>
    <ResponseField name="configUsed" type="object" required>Trip detection parameters used.</ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash theme={null}
  curl -H "X-API-Key: YOUR_API_KEY" \
    "https://your-api-host/trips?hardware_ids=ABC123&hardware_ids=DEF456&from=2025-12-01T00:00:00Z&to=2025-12-17T00:00:00Z"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "trips": [
      {
        "hardware_id": "ABC123",
        "startTime": "2025-12-17T08:00:00.000Z",
        "endTime": "2025-12-17T08:45:00.000Z",
        "startLocation": { "lat": 37.7749, "long": -122.4194 },
        "endLocation": { "lat": 37.7899, "long": -122.401 },
        "distance": 5234,
        "duration": 2700,
        "maxSpeed": 45.2,
        "avgSpeed": 6.9,
        "pointCount": 54
      }
    ],
    "stops": [
      {
        "startTime": "2025-12-17T08:45:00.000Z",
        "endTime": "2025-12-17T09:30:00.000Z",
        "location": { "lat": 37.7899, "long": -122.401 },
        "duration": 2700
      }
    ],
    "summary": {
      "totalTrips": 1,
      "totalStops": 1,
      "totalDistance": 5234,
      "totalDuration": 2700,
      "totalStopDuration": 2700,
      "positionsAnalyzed": 120,
      "devicesQueried": 2,
      "configUsed": {
        "speedThreshold": 3,
        "minimalTripDuration": 300,
        "minimalTripDistance": 500,
        "minimalParkingDuration": 180,
        "minimalNoDataDuration": 1800,
        "minimalAvgSpeed": 1,
        "maxAcceleration": 10
      }
    }
  }
  ```
</ResponseExample>