Raw Trip Dataset — Structure & JSON Schema
This document describes the structure of a raw trip dataset as returned by the trip points retrieval API. All example values use fake/redacted data to protect sensitive information.
1. Overview
The raw trip dataset is a JSON response containing a single vehicle trip recorded by a mobile SDK. Each trip consists of metadata (timestamps, user/device info, S3 storage location) and an ordered array of waypoints — high-frequency telematics samples capturing GPS position, speed, IMU sensor readings (accelerometer & gyroscope), and per-second statistical quantiles for those sensors.
A typical trip file can contain hundreds to thousands of waypoints (one per second)
2. Top-Level Response Envelope
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the API call succeeded. |
status_code | integer | HTTP-style status code (e.g. 200). |
message | string | Human-readable status message. |
result | object | Contains the trip payload (see §3). |
error | object | null | Error details when success is false; otherwise null. |
Example (top-level)
{
"success": true,
"status_code": 200,
"message": "Trip points retrieved successfully",
"result": { "..." },
"error": null
}
3. result Object
result Object| Field | Type | Description |
|---|---|---|
TrackToken | string (UUID) | Unique identifier for this trip. |
S3Location | object | AWS S3 storage coordinates for the raw file. |
TripData | object | Full trip payload including metadata and waypoints. |
3.1 S3Location
S3Location| Field | Type | Description |
|---|---|---|
S3Url | string (URL) | S3 endpoint base URL. |
Bucket | string | S3 bucket name. |
Key | string | Object key path within the bucket, structured as trips/filtered/{InstanceId}/{UserId}/{TrackToken}.json (IDs without hyphens). |
Example
{
"S3Url": "https://s3.amazonaws.com",
"Bucket": "trip-incoming-2",
"Key": "trips/filtered/a1b2c3d4e5f647a8b9c0d1e2f3a4b5c6/d4e5f6a7b8c94d0e1f2a3b4c5d6e7f80/f0e1d2c3b4a5968778695a4b3c2d1e0f.json"
}
4. TripData Object
TripData Object| Field | Type | Description |
|---|---|---|
Tags | array | User-defined tags attached to the trip (may be empty). |
TrackToken | string (UUID) | Same trip identifier as in result.TrackToken. |
DateReceived | string (ISO 8601) | Timestamp when the server received the trip data (UTC). |
StartDate | string (ISO 8601) | Trip start timestamp (device local timezone). |
EndDate | string (ISO 8601) | Trip end timestamp (device local timezone). |
StartReason | string | What triggered trip recording to begin. Known values: "MotionDetected". |
StopReason | string | What triggered trip recording to end. Known values: "LowSpeedTimeout". |
UserInfo | object | Identifies the user, app instance, and company (see §4.1). |
DeviceInfo | object | Device and SDK metadata (see §4.2). |
Waypoints | array[object] | Ordered array of telematics waypoint samples (see §5). |
4.1 UserInfo
UserInfo| Field | Type | Description |
|---|---|---|
UserId | string (UUID) | Unique user identifier. |
InstanceId | string (UUID) | SDK installation instance identifier. |
AppId | string (UUID) | Application identifier. |
CompanyId | string (UUID) | Company/organization identifier. |
CompanyCode | integer | Numeric company code. |
Example
{
"UserId": "d4e5f6a7-b8c9-4d0e-1f2a-3b4c5d6e7f80",
"InstanceId": "a1b2c3d4-e5f6-47a8-b9c0-d1e2f3a4b5c6",
"AppId": "11111111-2222-3333-4444-555555555555",
"CompanyId": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
"CompanyCode": 100001
}
4.2 DeviceInfo
DeviceInfo| Field | Type | Description |
|---|---|---|
InstallationId | string (UUID, uppercase) | Unique installation ID on the device. |
SdkVersion | string | Telematics SDK version (e.g. "7.1.0.4"). |
AppVersion | string | Host application version (e.g. "2.3.0.142"). |
DeviceModel | string | Hardware model identifier (e.g. "iPhone13,4", "Pixel7"). |
DeviceOs | string | Operating system name: "iOS" or "Android". |
DeviceOsVersion | string | Full OS version string (e.g. "iOS 18.3.1"). |
Example
{
"InstallationId": "ABCDEF01-2345-6789-ABCD-EF0123456789",
"SdkVersion": "7.1.0.4",
"AppVersion": "2.3.0.142",
"DeviceModel": "iPhone13,4",
"DeviceOs": "iOS",
"DeviceOsVersion": "iOS 18.3.1"
}
5. Waypoint Object
Each waypoint is a single telematics sample, typically recorded once per second. The Waypoints array is ordered by Number (0-indexed, sequential).
5.1 Position & Motion Fields
| Field | Type | Unit | Description |
|---|---|---|---|
Number | integer | — | Sequential index of this waypoint (0-based). |
TotalMeters | number | meters | Cumulative distance traveled from trip start. |
PointDate | string | ISO 8601 | Timestamp of this sample (device local timezone). |
TickTimestamp | integer | Unix epoch (s) | Unix timestamp of this sample. |
Latitude | number | degrees | WGS-84 latitude. |
Longitude | number | degrees | WGS-84 longitude. |
Accuracy | number | meters | Horizontal GPS accuracy (radius of uncertainty). |
Height | number | centimeters | Altitude (note: values may be raw barometric/GPS altitude). |
VerticalAccuracy | number | meters | Vertical position accuracy. |
Speed | number | km/h | Instantaneous GPS speed. |
SpeedAccuracy | number | km/h | Speed measurement uncertainty. |
MidSpeed | number | km/h | Smoothed/median speed for the sample interval. |
Course | number | degrees | Heading/bearing (0–360, clockwise from true north). |
CourseAccuracy | number | degrees | Heading measurement uncertainty. |
5.2 Derived Driving-Event Fields
| Field | Type | Unit | Description |
|---|---|---|---|
Acceleration | number | — | Detected forward acceleration event magnitude (0 = none). |
Deceleration | number | — | Detected braking event magnitude (0 = none). |
Lateral | number | — | Detected lateral (cornering) event magnitude (0 = none). |
5.3 Raw IMU — Accelerometer
| Field | Type | Unit | Description |
|---|---|---|---|
AccelerationX | number | m/s² | Processed accelerometer X-axis reading (device-to-vehicle frame). |
AccelerationXOriginal | number | m/s² | Raw accelerometer X-axis reading (device frame). |
AccelerationY | number | m/s² | Processed accelerometer Y-axis reading. |
AccelerationYOriginal | number | m/s² | Raw accelerometer Y-axis reading. |
AccelerationZ | number | m/s² | Processed accelerometer Z-axis reading. |
AccelerationZOriginal | number | m/s² | Raw accelerometer Z-axis reading. |
5.4 Raw IMU — Gyroscope
| Field | Type | Unit | Description |
|---|---|---|---|
Yaw | number | deg/s | Yaw rate (rotation around vertical axis). |
GyroscopeX | number | rad/s | Processed gyroscope X-axis (roll rate). |
GyroscopeXOriginal | number | rad/s | Raw gyroscope X-axis reading. |
GyroscopeY | number | rad/s | Processed gyroscope Y-axis (pitch rate). |
GyroscopeYOriginal | number | rad/s | Raw gyroscope Y-axis reading. |
GyroscopeZ | number | rad/s | Processed gyroscope Z-axis (yaw rate). |
GyroscopeZOriginal | number | rad/s | Raw gyroscope Z-axis reading. |
5.5 Device State & Peripheral Fields
| Field | Type | Description |
|---|---|---|
DeviceBlocked | boolean | null | Whether the device screen was locked/blocked. null if unknown. |
ScreenEnabled | boolean | Whether the screen was on during this sample. |
BeaconId | string | null | Bluetooth beacon ID if detected; null otherwise. |
VehicleIndicators | object | null | OBD-II / vehicle CAN-bus data if available; null otherwise. |
5.6 Quantiles Object
Quantiles ObjectEach waypoint includes a Quantiles object containing statistical distributions of raw sensor readings collected during the 1-second sample interval. This provides insight into intra-second sensor variability.
Categories (6 total):
| Key | Sensor | Axis |
|---|---|---|
AccX | Accelerometer | X-axis |
AccY | Accelerometer | Y-axis |
AccZ | Accelerometer | Z-axis |
GyroX | Gyroscope | X-axis |
GyroY | Gyroscope | Y-axis |
GyroZ | Gyroscope | Z-axis |
Each category contains the same 7 statistical fields:
| Field | Type | Description |
|---|---|---|
min | number | Minimum value in the sample window. |
quantile_05 | number | 5th percentile. |
quantile_25 | number | 25th percentile (Q1). |
median | number | 50th percentile (median). |
quantile_75 | number | 75th percentile (Q3). |
quantile_95 | number | 95th percentile. |
max | number | Maximum value in the sample window. |
Example Waypoint (fake coordinates)
{
"Number": 42,
"TotalMeters": 523.17,
"PointDate": "2026-01-15T14:30:42+01:00",
"TickTimestamp": 1736948442,
"Latitude": 48.8566,
"Longitude": 2.3522,
"Accuracy": 5.12,
"Height": 3520.0,
"VerticalAccuracy": 3,
"Speed": 45.20,
"SpeedAccuracy": 1.05,
"MidSpeed": 44.80,
"Course": 128.50,
"CourseAccuracy": 8.3,
"Acceleration": 0,
"AccelerationX": -1.234,
"AccelerationXOriginal": 0.045,
"AccelerationY": -3.210,
"AccelerationYOriginal": -4.263,
"AccelerationZ": -9.110,
"AccelerationZOriginal": -9.041,
"Deceleration": 0,
"Lateral": 0,
"Yaw": -2.15,
"GyroscopeX": -0.032,
"GyroscopeXOriginal": -0.006,
"GyroscopeY": -0.018,
"GyroscopeYOriginal": -0.005,
"GyroscopeZ": -0.125,
"GyroscopeZOriginal": -0.012,
"DeviceBlocked": null,
"ScreenEnabled": false,
"BeaconId": null,
"VehicleIndicators": null,
"Quantiles": {
"AccX": {
"max": 0.350,
"median": -0.115,
"min": -0.219,
"quantile_05": -0.198,
"quantile_25": -0.150,
"quantile_75": 0.015,
"quantile_95": 0.294
},
"AccY": {
"max": 0.083,
"median": 0.019,
"min": -0.342,
"quantile_05": -0.320,
"quantile_25": -0.240,
"quantile_75": 0.045,
"quantile_95": 0.070
},
"AccZ": {
"max": 10.097,
"median": 9.879,
"min": 9.832,
"quantile_05": 9.840,
"quantile_25": 9.863,
"quantile_75": 9.896,
"quantile_95": 10.079
},
"GyroX": {
"max": 0.016,
"median": 0.010,
"min": -0.006,
"quantile_05": -0.005,
"quantile_25": -0.003,
"quantile_75": 0.012,
"quantile_95": 0.015
},
"GyroY": {
"max": 0.004,
"median": 0.001,
"min": -0.009,
"quantile_05": -0.008,
"quantile_25": -0.005,
"quantile_75": 0.003,
"quantile_95": 0.004
},
"GyroZ": {
"max": -0.012,
"median": -0.022,
"min": -0.025,
"quantile_05": -0.024,
"quantile_25": -0.023,
"quantile_75": -0.015,
"quantile_95": -0.013
}
}
}
6. JSON Schema
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://damoov.com/schemas/raw-trip-dataset.json",
"title": "Raw Trip Dataset",
"description": "API response containing a single raw vehicle trip with high-frequency telematics waypoints.",
"type": "object",
"required": ["success", "status_code", "message", "result", "error"],
"properties": {
"success": {
"type": "boolean",
"description": "Whether the API call succeeded."
},
"status_code": {
"type": "integer",
"description": "HTTP-style status code."
},
"message": {
"type": "string",
"description": "Human-readable status message."
},
"error": {
"type": ["object", "null"],
"description": "Error details if success is false; null otherwise."
},
"result": {
"type": "object",
"required": ["TrackToken", "S3Location", "TripData"],
"properties": {
"TrackToken": {
"type": "string",
"format": "uuid",
"description": "Unique trip identifier."
},
"S3Location": {
"$ref": "#/$defs/S3Location"
},
"TripData": {
"$ref": "#/$defs/TripData"
}
}
}
},
"$defs": {
"S3Location": {
"type": "object",
"required": ["S3Url", "Bucket", "Key"],
"properties": {
"S3Url": {
"type": "string",
"format": "uri",
"description": "S3 endpoint base URL."
},
"Bucket": {
"type": "string",
"description": "S3 bucket name."
},
"Key": {
"type": "string",
"description": "Object key path: trips/filtered/{InstanceId}/{UserId}/{TrackToken}.json"
}
}
},
"TripData": {
"type": "object",
"required": [
"Tags", "TrackToken", "DateReceived", "StartDate", "EndDate",
"StartReason", "StopReason", "UserInfo", "DeviceInfo", "Waypoints"
],
"properties": {
"Tags": {
"type": "array",
"items": { "type": "string" },
"description": "User-defined tags for the trip."
},
"TrackToken": {
"type": "string",
"format": "uuid"
},
"DateReceived": {
"type": "string",
"format": "date-time",
"description": "Server-side receipt timestamp (UTC)."
},
"StartDate": {
"type": "string",
"format": "date-time",
"description": "Trip start timestamp (device local timezone)."
},
"EndDate": {
"type": "string",
"format": "date-time",
"description": "Trip end timestamp (device local timezone)."
},
"StartReason": {
"type": "string",
"description": "Trigger for trip start (e.g. 'MotionDetected')."
},
"StopReason": {
"type": "string",
"description": "Trigger for trip end (e.g. 'LowSpeedTimeout')."
},
"UserInfo": {
"$ref": "#/$defs/UserInfo"
},
"DeviceInfo": {
"$ref": "#/$defs/DeviceInfo"
},
"Waypoints": {
"type": "array",
"items": { "$ref": "#/$defs/Waypoint" },
"description": "Ordered array of telematics samples (1 per second)."
}
}
},
"UserInfo": {
"type": "object",
"required": ["UserId", "InstanceId", "AppId", "CompanyId", "CompanyCode"],
"properties": {
"UserId": {
"type": "string",
"format": "uuid"
},
"InstanceId": {
"type": "string",
"format": "uuid"
},
"AppId": {
"type": "string",
"format": "uuid"
},
"CompanyId": {
"type": "string",
"format": "uuid"
},
"CompanyCode": {
"type": "integer"
}
}
},
"DeviceInfo": {
"type": "object",
"required": [
"InstallationId", "SdkVersion", "AppVersion",
"DeviceModel", "DeviceOs", "DeviceOsVersion"
],
"properties": {
"InstallationId": {
"type": "string",
"format": "uuid",
"description": "Device installation UUID (uppercase)."
},
"SdkVersion": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+\\.\\d+$"
},
"AppVersion": {
"type": "string",
"pattern": "^\\d+\\.\\d+\\.\\d+\\.\\d+$"
},
"DeviceModel": {
"type": "string",
"description": "Hardware model identifier."
},
"DeviceOs": {
"type": "string",
"enum": ["iOS", "Android"]
},
"DeviceOsVersion": {
"type": "string"
}
}
},
"Waypoint": {
"type": "object",
"required": [
"Number", "TotalMeters", "PointDate", "TickTimestamp",
"Latitude", "Longitude", "Accuracy", "Height", "VerticalAccuracy",
"Speed", "SpeedAccuracy", "MidSpeed", "Course", "CourseAccuracy",
"Acceleration", "AccelerationX", "AccelerationXOriginal",
"AccelerationY", "AccelerationYOriginal",
"AccelerationZ", "AccelerationZOriginal",
"Deceleration", "Lateral", "Yaw",
"GyroscopeX", "GyroscopeXOriginal",
"GyroscopeY", "GyroscopeYOriginal",
"GyroscopeZ", "GyroscopeZOriginal",
"DeviceBlocked", "ScreenEnabled", "BeaconId",
"VehicleIndicators", "Quantiles"
],
"properties": {
"Number": {
"type": "integer",
"minimum": 0,
"description": "Sequential waypoint index (0-based)."
},
"TotalMeters": {
"type": "number",
"minimum": 0,
"description": "Cumulative distance from trip start (meters)."
},
"PointDate": {
"type": "string",
"format": "date-time",
"description": "Sample timestamp (device local timezone)."
},
"TickTimestamp": {
"type": "integer",
"description": "Unix epoch timestamp (seconds)."
},
"Latitude": {
"type": "number",
"minimum": -90,
"maximum": 90,
"description": "WGS-84 latitude (degrees)."
},
"Longitude": {
"type": "number",
"minimum": -180,
"maximum": 180,
"description": "WGS-84 longitude (degrees)."
},
"Accuracy": {
"type": "number",
"minimum": 0,
"description": "Horizontal GPS accuracy (meters)."
},
"Height": {
"type": "number",
"description": "Altitude (centimeters)."
},
"VerticalAccuracy": {
"type": "number",
"minimum": 0,
"description": "Vertical position accuracy (meters)."
},
"Speed": {
"type": "number",
"minimum": 0,
"description": "Instantaneous GPS speed (km/h)."
},
"SpeedAccuracy": {
"type": "number",
"minimum": 0,
"description": "Speed measurement uncertainty (km/h)."
},
"MidSpeed": {
"type": "number",
"minimum": 0,
"description": "Smoothed/median speed (km/h)."
},
"Course": {
"type": "number",
"minimum": 0,
"maximum": 360,
"description": "Heading (degrees, clockwise from true north)."
},
"CourseAccuracy": {
"type": "number",
"minimum": 0,
"description": "Heading uncertainty (degrees)."
},
"Acceleration": {
"type": "number",
"description": "Forward acceleration event magnitude (0 = none)."
},
"AccelerationX": {
"type": "number",
"description": "Processed accelerometer X-axis (m/s²)."
},
"AccelerationXOriginal": {
"type": "number",
"description": "Raw accelerometer X-axis (m/s²)."
},
"AccelerationY": {
"type": "number",
"description": "Processed accelerometer Y-axis (m/s²)."
},
"AccelerationYOriginal": {
"type": "number",
"description": "Raw accelerometer Y-axis (m/s²)."
},
"AccelerationZ": {
"type": "number",
"description": "Processed accelerometer Z-axis (m/s²)."
},
"AccelerationZOriginal": {
"type": "number",
"description": "Raw accelerometer Z-axis (m/s²)."
},
"Deceleration": {
"type": "number",
"description": "Braking event magnitude (0 = none)."
},
"Lateral": {
"type": "number",
"description": "Cornering event magnitude (0 = none)."
},
"Yaw": {
"type": "number",
"description": "Yaw rate (deg/s)."
},
"GyroscopeX": {
"type": "number",
"description": "Processed gyroscope X-axis / roll rate (rad/s)."
},
"GyroscopeXOriginal": {
"type": "number",
"description": "Raw gyroscope X-axis (rad/s)."
},
"GyroscopeY": {
"type": "number",
"description": "Processed gyroscope Y-axis / pitch rate (rad/s)."
},
"GyroscopeYOriginal": {
"type": "number",
"description": "Raw gyroscope Y-axis (rad/s)."
},
"GyroscopeZ": {
"type": "number",
"description": "Processed gyroscope Z-axis / yaw rate (rad/s)."
},
"GyroscopeZOriginal": {
"type": "number",
"description": "Raw gyroscope Z-axis (rad/s)."
},
"DeviceBlocked": {
"type": ["boolean", "null"],
"description": "Whether device screen was locked. Null if unknown."
},
"ScreenEnabled": {
"type": "boolean",
"description": "Whether the screen was on."
},
"BeaconId": {
"type": ["string", "null"],
"description": "Bluetooth beacon ID if detected."
},
"VehicleIndicators": {
"type": ["object", "null"],
"description": "OBD-II / CAN-bus data if available."
},
"Quantiles": {
"$ref": "#/$defs/Quantiles"
}
}
},
"Quantiles": {
"type": "object",
"description": "Per-second statistical distributions of raw sensor readings.",
"required": ["AccX", "AccY", "AccZ", "GyroX", "GyroY", "GyroZ"],
"properties": {
"AccX": { "$ref": "#/$defs/QuantileStats" },
"AccY": { "$ref": "#/$defs/QuantileStats" },
"AccZ": { "$ref": "#/$defs/QuantileStats" },
"GyroX": { "$ref": "#/$defs/QuantileStats" },
"GyroY": { "$ref": "#/$defs/QuantileStats" },
"GyroZ": { "$ref": "#/$defs/QuantileStats" }
}
},
"QuantileStats": {
"type": "object",
"description": "Seven-number statistical summary of sensor readings within a 1-second window.",
"required": ["min", "quantile_05", "quantile_25", "median", "quantile_75", "quantile_95", "max"],
"properties": {
"min": { "type": "number", "description": "Minimum value." },
"quantile_05": { "type": "number", "description": "5th percentile." },
"quantile_25": { "type": "number", "description": "25th percentile (Q1)." },
"median": { "type": "number", "description": "50th percentile (median)." },
"quantile_75": { "type": "number", "description": "75th percentile (Q3)." },
"quantile_95": { "type": "number", "description": "95th percentile." },
"max": { "type": "number", "description": "Maximum value." }
}
}
}
}
7. Data Flow Diagram
┌──────────────────────────────────────────────────────────────────────┐
│ API Response Envelope │
│ success, status_code, message, error │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ result │ │
│ │ ├── TrackToken (UUID) │ │
│ │ ├── S3Location { S3Url, Bucket, Key } │ │
│ │ └── TripData │ │
│ │ ├── Tags [] │ │
│ │ ├── TrackToken, DateReceived, StartDate, EndDate │ │
│ │ ├── StartReason, StopReason │ │
│ │ ├── UserInfo { UserId, InstanceId, AppId, CompanyId, ... }│ │
│ │ ├── DeviceInfo { InstallationId, SdkVersion, ... } │ │
│ │ └── Waypoints [0..N] │ │
│ │ ├── Position: Lat, Lon, Height, Accuracy │ │
│ │ ├── Motion: Speed, MidSpeed, Course │ │
│ │ ├── Events: Acceleration, Deceleration, Lateral │ │
│ │ ├── IMU Accel: X/Y/Z (Processed + Original) │ │
│ │ ├── IMU Gyro: X/Y/Z (Processed + Original) + Yaw │ │
│ │ ├── Device: ScreenEnabled, DeviceBlocked, BeaconId │ │
│ │ └── Quantiles │ │
│ │ ├── AccX { min, q05, q25, median, q75, q95, max }│ │
│ │ ├── AccY { ... } │ │
│ │ ├── AccZ { ... } │ │
│ │ ├── GyroX { ... } │ │
│ │ ├── GyroY { ... } │ │
│ │ └── GyroZ { ... } │ │
│ └────────────────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────┘
Updated 11 days ago
