Skip to main content

​
Trips

Trips are computed on-demand from GPS telemetry using motion detection. The algorithm analyzes speed and position data to identify when a device is moving vs stopped.

​
Query Limits

LimitValueDescription
Max date range31 daysPrevents excessive data queries
Max devices50 per requestLimits parallel processing

​
Get Trips (Multiple Devices)

​
none
GET /trips
Get trips and stops for multiple devices.

​
Query Parameters

​
from
string
required
ISO date string for start of range
​
to
string
required
ISO date string for end of range
​
hardware_ids
string
List of hardware IDs. Repeated (?hardware_ids=id1&hardware_ids=id2) or comma-separated (?hardware_ids=id1%2Cid2%2Cid3). Required for users, optional for admins.
See configuration parameters below. 
# User request – repeated or comma-separated
curl -H "X-API-Key: your-key" \
  "https://api.example.com/trips?hardware_ids=ABC123&hardware_ids=DEF456&from=2025-12-01T00:00:00Z&to=2025-12-17T00:00:00Z"
curl -H "X-API-Key: your-key" \
  "https://api.example.com/trips?hardware_ids=12317192%2C10631020&from=2025-12-01T00:00:00Z&to=2025-12-17T00:00:00Z"

# Admin request (all devices)
curl -H "X-API-Key: your-admin-key" \
  "https://api.example.com/trips?from=2025-12-01T00:00:00Z&to=2025-12-17T00:00:00Z"

{
  "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
    }
  }
}

​
Get Trips (Single Device)

​
none
GET /trips/:hardwareId
Get trips and stops for a single device.

​
Query Parameters

​
from
string
required
ISO date string for start of range
​
to
string
required
ISO date string for end of range
See configuration parameters below. 
curl -H "X-API-Key: your-key" \
  "https://api.example.com/trips/ABC123?from=2025-12-01T00:00:00Z&to=2025-12-17T00:00:00Z"

​
Get Active Trips

​
none
GET /trips/active
Get devices currently in motion using each device’s latest GPS sample.

​
Query Parameters

​
hardware_ids
string
List of hardware IDs. Repeated (?hardware_ids=id1&hardware_ids=id2) or comma-separated (?hardware_ids=id1%2Cid2%2Cid3). Required for users, optional for admins.
​
speedThreshold
number
Minimum speed in km/h to count as active (default: 2).
​
maxAgeSeconds
number
Maximum age of latest GPS sample in seconds (default: 300).
​
lookbackSeconds
number
How far back to load GPS history for trip detection (default: 14400).
See configuration parameters below. Active detection uses the same trip algorithm config. 
# User request
curl -H "X-API-Key: your-key" \
  "https://api.example.com/trips/active?hardware_ids=ABC123&hardware_ids=DEF456&minimalTripDuration=600"

# Admin request (all devices)
curl -H "X-API-Key: your-admin-key" \
  "https://api.example.com/trips/active"

{
  "activeTrips": [
    {
      "hardware_id": "ABC123",
      "speed": 19.6,
      "last_position_at": "2025-12-17T10:30:00.000Z",
      "last_position_age_seconds": 24,
      "location": { "lat": 37.7749, "long": -122.4194 },
      "trip": {
        "startTime": "2025-12-17T09:50:00.000Z",
        "endTime": "2025-12-17T10:30:00.000Z",
        "startLocation": { "lat": 37.7601, "long": -122.4312 },
        "endLocation": { "lat": 37.7749, "long": -122.4194 },
        "distance": 5234,
        "duration": 2400,
        "maxSpeed": 45.2,
        "avgSpeed": 7.8,
        "pointCount": 54
      }
    }
  ],
  "summary": {
    "activeCount": 1,
    "devicesQueried": 2,
    "configUsed": {
      "speedThreshold": 3,
      "minimalTripDuration": 300,
      "minimalTripDistance": 500,
      "minimalParkingDuration": 180,
      "minimalNoDataDuration": 1800,
      "minimalAvgSpeed": 1,
      "maxAcceleration": 10
    },
    "maxAgeSeconds": 300,
    "lookbackSeconds": 14400
  }
}

​
Get Active Trip (Single Device)

​
none
GET /trips/:hardwareId/active
Get active trip status for one device using its latest GPS sample.

​
Query Parameters

​
speedThreshold
number
Minimum speed in km/h to count as active (default: 2).
​
maxAgeSeconds
number
Maximum age of latest GPS sample in seconds (default: 300).
​
lookbackSeconds
number
How far back to load GPS history for trip detection (default: 14400).
See configuration parameters below. Active detection uses the same trip algorithm config. 
curl -H "X-API-Key: your-key" \
  "https://api.example.com/trips/ABC123/active?minimalTripDuration=600"

{
  "hardware_id": "ABC123",
  "active": true,
  "activeTrip": {
    "hardware_id": "ABC123",
    "speed": 19.6,
    "last_position_at": "2025-12-17T10:30:00.000Z",
    "last_position_age_seconds": 24,
    "location": { "lat": 37.7749, "long": -122.4194 },
    "trip": {
      "startTime": "2025-12-17T09:50:00.000Z",
      "endTime": "2025-12-17T10:30:00.000Z",
      "startLocation": { "lat": 37.7601, "long": -122.4312 },
      "endLocation": { "lat": 37.7749, "long": -122.4194 },
      "distance": 5234,
      "duration": 2400,
      "maxSpeed": 45.2,
      "avgSpeed": 7.8,
      "pointCount": 54
    }
  },
  "summary": {
    "configUsed": {
      "speedThreshold": 3,
      "minimalTripDuration": 300,
      "minimalTripDistance": 500,
      "minimalParkingDuration": 180,
      "minimalNoDataDuration": 1800,
      "minimalAvgSpeed": 1,
      "maxAcceleration": 10
    },
    "maxAgeSeconds": 300,
    "lookbackSeconds": 14400
  }
}

​
Get Trip Summary

​
none
GET /trips/:hardwareId/summary
Get summary statistics without full trip/stop details.
curl -H "X-API-Key: your-key" \
  "https://api.example.com/trips/ABC123/summary?from=2025-12-01T00:00:00Z&to=2025-12-17T00:00:00Z"

{
  "hardware_id": "ABC123",
  "from": "2025-12-01T00:00:00.000Z",
  "to": "2025-12-17T00:00:00.000Z",
  "totalTrips": 15,
  "totalStops": 14,
  "totalDistance": 125000,
  "totalTripDuration": 36000,
  "totalStopDuration": 72000,
  "maxSpeed": 55.5,
  "avgTripDistance": 8333,
  "positionsAnalyzed": 5000
}

​
Configuration Parameters

Optional query parameters to tune trip detection:
ParameterDefaultDescription
speedThreshold3km/h - below this speed is stopped
minimalTripDuration300seconds - minimum time to count as trip
minimalTripDistance500meters - minimum distance for trip
minimalParkingDuration180seconds - stopped time to end a trip
minimalNoDataDuration1800seconds - data gaps treated as stops
minimalAvgSpeed1km/h - minimum avg speed for trip
maxAcceleration10m/s² - filter GPS spikes

​
Trip Validation

A trip is only recorded if it meets all criteria:
  • Duration ≥ minimalTripDuration
  • Distance ≥ minimalTripDistance
  • Average speed ≥ minimalAvgSpeed
This filters out GPS drift where the device appears to move short distances. 
curl -H "X-API-Key: your-key" \
  "https://api.example.com/trips/ABC123?from=2025-12-01T00:00:00Z&to=2025-12-17T00:00:00Z&speedThreshold=5&minimalTripDuration=600"

​
Usage Pattern

  1. Query trips to get trip summaries with start/end times
  2. Query GPS positions for a specific trip’s time range to draw the route
# Get trips
curl -H "X-API-Key: your-key" \
  "https://api.example.com/trips/ABC123?from=2025-12-01T00:00:00Z&to=2025-12-17T00:00:00Z"

# Get GPS positions for a specific trip (to draw route on map)
curl -H "X-API-Key: your-key" \
  "https://api.example.com/devices/ABC123/gps?from=2025-12-17T08:00:00Z&to=2025-12-17T08:45:00Z"