Skip to main content

Vehicle Segments

Get segmented trip data from DIMO-connected vehicles.

Overview​

The segments resource serves as the "trips" part of the Telemetry API, allowing developers to gather trip data for vehicles. Maximum date range: 31 days.

Each segment includes summary signals, start/end location, and (when requested) event counts. A default set of signal requests is always applied (e.g. speed, odometer; for refuel/recharge also the level signal at start and end). When signalRequests is provided, those requests are added on top of the default set; duplicates (same name and agg) are omitted.

Detection Mechanism​

Segments can be detected using different mechanisms. This is a crucial part of querying segments.

DetectionMechanism Enum

ignitionDetection
Ignition-based detection: Segments are identified by isIgnitionOn state transitions. Most reliable for vehicles with proper ignition signal support.
frequencyAnalysis
Frequency analysis: Segments are detected by analyzing signal update patterns. Uses pre-computed materialized view for optimal performance. Ideal for real-time APIs and bulk queries.
changePointDetection
Change point detection: Uses CUSUM algorithm to detect statistical regime changes. Monitors cumulative deviation in signal frequency via materialized view. Excellent noise resistance with 100% accuracy match to ignition baseline. Best alternative when ignition signal is unavailable - same accuracy, same speed as frequency analysis.
idling
Idling: Segments are contiguous periods where engine RPM remains in idle range.
refuel
Refuel: Detects where fuel level rises significantly.
recharge
Recharge: Hybrid detection. Uses charging signals and state of charge for detection.

segments​

The segments query allows you to retrieve trip segments.

Query Arguments

Arguments

tokenIdInt!Required
The vehicle token ID.
fromTime!Required
Start time of the range.
toTime!Required
End time of the range.
mechanismDetectionMechanism!Required
The method used to detect segments.
configSegmentConfigOptional
Configuration for segment detection parameters.
signalRequests[SegmentSignalRequest!]Optional
Request specific signal aggregations per segment. Each request specifies a signal name and aggregation type.
eventRequests[SegmentEventRequest!]Optional
Request specific event counts per segment. Each request specifies an event name.
limitIntOptional
Maximum number of segments to return. Default 100, max 200.
afterTimeOptional
Cursor for pagination: return only segments with startTime > after (exclusive). Pass the start timestamp of the last segment from the previous page.

Response Fields (Segment)

Fields

startSignalLocation!
Segment start with timestamp and location. Contains `timestamp` (Time!) and `value` (Location! with latitude, longitude, hdop).
endSignalLocation
Segment end with timestamp and location. Null if segment is ongoing (extends beyond query range).
durationInt!
Duration in seconds. If ongoing: from start to query 'to' time. If complete: from start to end.
isOngoingBoolean!
True if segment extends beyond query time range (last activity is ongoing). When true, `end` is not included.
startedBeforeRangeBoolean!
True if segment started before query time range. Indicates start may be approximate.
signals[SignalAggregationValue!]
Per-segment signal aggregates. Each entry has `name` (String!), `agg` (String!), and `value` (Float!).
eventCounts[EventCount!]
Per-segment event counts. Each entry has `name` (String!) and `count` (Int!).

SegmentConfig

Configuration

maxGapSecondsInt
Maximum gap (seconds) between data points before a segment is split. For ignitionDetection: filters noise from brief ignition OFF events. For frequencyAnalysis: maximum gap between active windows to merge. Default: 300 (5 min), Min: 60, Max: 3600.
minSegmentDurationSecondsInt
Minimum segment duration (seconds) to include in results. Filters very short segments (testing, engine cycling). Default: 240 (4 min), Min: 60, Max: 3600.
signalCountThresholdInt
[frequencyAnalysis/idling] Minimum signal count per window for activity detection. Higher values = more conservative, lower = more sensitive. Default: 10, Min: 1, Max: 3600.
maxIdleRpmInt
[idling only] Upper bound for idle RPM. Windows with max(RPM) <= this are considered idle. Default: 1000, Min: 300, Max: 3000.
minIncreasePercentInt
[refuel/recharge only] Minimum percent increase within a window to consider it a level-increase window. Default: 15.

Input Types

SegmentSignalRequest

nameString!
The signal name to aggregate (e.g. "speed", "powertrainFuelSystemRelativeLevel").
aggFloatAggregation!
The aggregation type (AVG, MAX, MED, MIN, RAND, FIRST, LAST).

SegmentEventRequest

nameString!
The event name to count per segment.
query GetSegments {
segments(
  tokenId: 117315
  from: "2025-11-01T09:21:19Z"
  to: "2025-11-07T09:21:19Z"
  mechanism: frequencyAnalysis
  signalRequests: [
    { name: "speed", agg: MAX }
  ]
  eventRequests: [
    { name: "HarshBraking" }
  ]
  limit: 50
) {
  start {
    timestamp
    value { latitude longitude }
  }
  end {
    timestamp
    value { latitude longitude }
  }
  duration
  isOngoing
  startedBeforeRange
  signals { name agg value }
  eventCounts { name count }
}
}

Response Example

{
"data": {
  "segments": [
    {
      "start": {
        "timestamp": "2025-11-01T21:07:00Z",
        "value": { "latitude": 40.7128, "longitude": -74.006 }
      },
      "end": {
        "timestamp": "2025-11-01T22:02:00Z",
        "value": { "latitude": 40.758, "longitude": -73.9855 }
      },
      "duration": 3300,
      "isOngoing": false,
      "startedBeforeRange": false,
      "signals": [
        { "name": "speed", "agg": "MAX", "value": 88.5 }
      ],
      "eventCounts": [
        { "name": "HarshBraking", "count": 2 }
      ]
    }
  ]
}
}