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

FieldTypeDescription
successbooleanWhether the API call succeeded.
status_codeintegerHTTP-style status code (e.g. 200).
messagestringHuman-readable status message.
resultobjectContains the trip payload (see §3).
errorobject | nullError 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

FieldTypeDescription
TrackTokenstring (UUID)Unique identifier for this trip.
S3LocationobjectAWS S3 storage coordinates for the raw file.
TripDataobjectFull trip payload including metadata and waypoints.

3.1 S3Location

FieldTypeDescription
S3Urlstring (URL)S3 endpoint base URL.
BucketstringS3 bucket name.
KeystringObject 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

FieldTypeDescription
TagsarrayUser-defined tags attached to the trip (may be empty).
TrackTokenstring (UUID)Same trip identifier as in result.TrackToken.
DateReceivedstring (ISO 8601)Timestamp when the server received the trip data (UTC).
StartDatestring (ISO 8601)Trip start timestamp (device local timezone).
EndDatestring (ISO 8601)Trip end timestamp (device local timezone).
StartReasonstringWhat triggered trip recording to begin. Known values: "MotionDetected".
StopReasonstringWhat triggered trip recording to end. Known values: "LowSpeedTimeout".
UserInfoobjectIdentifies the user, app instance, and company (see §4.1).
DeviceInfoobjectDevice and SDK metadata (see §4.2).
Waypointsarray[object]Ordered array of telematics waypoint samples (see §5).

4.1 UserInfo

FieldTypeDescription
UserIdstring (UUID)Unique user identifier.
InstanceIdstring (UUID)SDK installation instance identifier.
AppIdstring (UUID)Application identifier.
CompanyIdstring (UUID)Company/organization identifier.
CompanyCodeintegerNumeric 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

FieldTypeDescription
InstallationIdstring (UUID, uppercase)Unique installation ID on the device.
SdkVersionstringTelematics SDK version (e.g. "7.1.0.4").
AppVersionstringHost application version (e.g. "2.3.0.142").
DeviceModelstringHardware model identifier (e.g. "iPhone13,4", "Pixel7").
DeviceOsstringOperating system name: "iOS" or "Android".
DeviceOsVersionstringFull 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

FieldTypeUnitDescription
NumberintegerSequential index of this waypoint (0-based).
TotalMetersnumbermetersCumulative distance traveled from trip start.
PointDatestringISO 8601Timestamp of this sample (device local timezone).
TickTimestampintegerUnix epoch (s)Unix timestamp of this sample.
LatitudenumberdegreesWGS-84 latitude.
LongitudenumberdegreesWGS-84 longitude.
AccuracynumbermetersHorizontal GPS accuracy (radius of uncertainty).
HeightnumbercentimetersAltitude (note: values may be raw barometric/GPS altitude).
VerticalAccuracynumbermetersVertical position accuracy.
Speednumberkm/hInstantaneous GPS speed.
SpeedAccuracynumberkm/hSpeed measurement uncertainty.
MidSpeednumberkm/hSmoothed/median speed for the sample interval.
CoursenumberdegreesHeading/bearing (0–360, clockwise from true north).
CourseAccuracynumberdegreesHeading measurement uncertainty.

5.2 Derived Driving-Event Fields

FieldTypeUnitDescription
AccelerationnumberDetected forward acceleration event magnitude (0 = none).
DecelerationnumberDetected braking event magnitude (0 = none).
LateralnumberDetected lateral (cornering) event magnitude (0 = none).

5.3 Raw IMU — Accelerometer

FieldTypeUnitDescription
AccelerationXnumberm/s²Processed accelerometer X-axis reading (device-to-vehicle frame).
AccelerationXOriginalnumberm/s²Raw accelerometer X-axis reading (device frame).
AccelerationYnumberm/s²Processed accelerometer Y-axis reading.
AccelerationYOriginalnumberm/s²Raw accelerometer Y-axis reading.
AccelerationZnumberm/s²Processed accelerometer Z-axis reading.
AccelerationZOriginalnumberm/s²Raw accelerometer Z-axis reading.

5.4 Raw IMU — Gyroscope

FieldTypeUnitDescription
Yawnumberdeg/sYaw rate (rotation around vertical axis).
GyroscopeXnumberrad/sProcessed gyroscope X-axis (roll rate).
GyroscopeXOriginalnumberrad/sRaw gyroscope X-axis reading.
GyroscopeYnumberrad/sProcessed gyroscope Y-axis (pitch rate).
GyroscopeYOriginalnumberrad/sRaw gyroscope Y-axis reading.
GyroscopeZnumberrad/sProcessed gyroscope Z-axis (yaw rate).
GyroscopeZOriginalnumberrad/sRaw gyroscope Z-axis reading.

5.5 Device State & Peripheral Fields

FieldTypeDescription
DeviceBlockedboolean | nullWhether the device screen was locked/blocked. null if unknown.
ScreenEnabledbooleanWhether the screen was on during this sample.
BeaconIdstring | nullBluetooth beacon ID if detected; null otherwise.
VehicleIndicatorsobject | nullOBD-II / vehicle CAN-bus data if available; null otherwise.

5.6 Quantiles Object

Each 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):

KeySensorAxis
AccXAccelerometerX-axis
AccYAccelerometerY-axis
AccZAccelerometerZ-axis
GyroXGyroscopeX-axis
GyroYGyroscopeY-axis
GyroZGyroscopeZ-axis

Each category contains the same 7 statistical fields:

FieldTypeDescription
minnumberMinimum value in the sample window.
quantile_05number5th percentile.
quantile_25number25th percentile (Q1).
mediannumber50th percentile (median).
quantile_75number75th percentile (Q3).
quantile_95number95th percentile.
maxnumberMaximum 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 { ... }                                  │  │
│  └────────────────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────────────────┘