LogoLogo
DocsHomeSupportContact
  • Getting Started
    • Introduction
    • Build on DIMO
  • DEVELOPER GUIDE
    • Developer Overview
    • Developer Console
    • Authentication
    • DIMO Developer SDKs
      • Data SDK
      • Login with DIMO SDK
        • React Component
        • Login with DIMO Redirect
        • Core Functionalities
      • TypeScript: Transactions SDK
      • SDK Release Notes
    • Low Code Tools
      • n8n: Getting Started
    • Permissions Contract: SACD
    • DIMO Credits
    • Response Types
    • Rate Limits
    • Developer FAQ
    • Developer Changelogs
    • Troubleshooting Common Issues
  • API References
    • Overview of DIMO API
    • Attestation API
    • Device Definitions API
    • Identity API
      • Schema & Types
      • Scalars
      • Nodes & Objects
        • AftermarketDevice
        • AftermarketDeviceConnection
        • DCN
        • DCNConnection
        • DeveloperLicense
        • DeviceDefinition
        • Earning
        • EarningsConnection
        • Manufacturer
        • Sacd
        • SyntheticDevice
        • Vehicle
        • VehicleConnection
        • VehicleEarnings
        • UserRewards
      • Common Queries
    • Telemetry API
      • Schema & Types
      • Scalars
      • Nodes & Objects
        • Signals
        • SignalsLatest
      • Common Queries
    • Token Exchange API
    • Trips API
    • Valuations API
  • DIMO Hardware
    • Introduction
    • DIMO Hardware Application
    • DIMO Manufacturing License
    • Development & Certification
    • Audits & Assessments
      • Hardware & Security Audit
      • Customer Experience Assessment
      • Integration Testing & Quality Control
      • Final Approval
    • DIMO Device License
      • Device Minting Certificates
    • Essential Documents
      • Hardware & Security Audit Checklist
      • Approved Hardware Auditors
      • DIMO Memorandum of Understanding (MOU)
  • Additional References
    • Developer License
    • DIMO GraphQL Basics
  • Deprecated Resources
    • Guides
      • Developer Journey
      • Quick Start Guide
      • Hello World
      • Code Exchange Flow
    • Data Availability
Powered by GitBook
On this page
  • Base URLs
  • User Device Data
  • Get User Device Status by User Device ID
  • Get User Device History by User Device ID
  • Send JSON Export Email of User Device Data by User Device ID
  • Vehicle Data
  • Get Vehicle Status by Vehicle ID
  • Get Vehicle Raw Status by Vehicle ID
  • Get Vehicle History by Vehicle ID
  • Get Daily Distance Driven by User Device ID
  • Get Total Distance Driven by User Device ID
  • Swagger Doc

Was this helpful?

  1. Deprecated Resources
  2. Deprioritized APIs
  3. Device Data API

Device Data API Endpoints

Last updated 5 months ago

Was this helpful?

This is a deprecated API

Base URLs

https://device-data-api.dimo.zone


User Device Data

Developer Notes

  1. The following endpoints defers back to using the Web3 access token given that API users are interacting with user devices under their personal possession. No additional permission is needed.

Get User Device Status by User Device ID

GET /v1/user/device-data/{userDeviceId}/status

Retrieves vehicle-related status data from the user device. Regardless of connection type, this attempts to fetch information from the devices that the API user owns.

Path Parameters

Name
Type
Description

userDeviceId*

String

Headers

Name
Type
Description

Authorization*

String

{
    "fuelPercentRemaining": 0.518,
    "odometer": 50414.2,
    "latitude": 37.697789,
    "longitude": -121.788662,
    "range": 331.37114474980734,
    "recordUpdatedAt": "2024-01-26T16:36:38Z",
    "recordCreatedAt": "2024-01-25T15:51:33.986023Z",
    "batteryVoltage": 12.641,
    "ambientTemp": 29
}

Get User Device History by User Device ID

Retrieves vehicle-related history data from the user device. Regardless of connection type, this attempts to fetch information from the devices that the API user owns.

Path Parameters

Name
Type
Description

userDeviceId*

String

Query Parameters

Name
Type
Description

startDate

String

endDate

String

Headers

Name
Type
Description

Authorization*

String

{
    "took": 94,
    "timed_out": false,
    "_shards": {
        "total": 403,
        "successful": 403,
        "skipped": 387,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 633,
            "relation": "eq"
        },
        "max_score": 1.99739,
        "hits": [
            {
                "_index": "device-status-prod-2024-01-24",
                "_id": "2bPwGLvWstG3eWtLXO82b5VYDP0",
                "_score": 1.99739,
                "_source": {
                    "data": {
                        "lora": {
                            "devAddr": "7C080048",
                            "dc_balance": 237787349,
                            "fPort": "2",
                            "app_eui": "44494D4F5A4F4E45",
                            "payload_size": "31",
                            "fcnt": "26",
                            "deveui": "F4CE36B7251BF81C"
                        },
                        "ambientTemp": 32,
                        "odometer": 50406.1,
                        "year": 2021,
                        "latitude": 37.69915,
                        "deviceDefinitionId": "26G4j1YDaZhFeCsn12MAlyU3Y2H",
                        "nsat": 4,
                        "vinLast8": "M5023425",
                        "speed": 0,
                        "makeSlug": "lexus",
                        "barometricPressure": 101,
                        "fuelPercentRemaining": 0.522,
                        "modelSlug": "nx",
                        "engineLoad": 0.216,
                        "model": "NX",
                        "region": "Americas",
                        "make": "Lexus",
                        "longitude": -121.87175,
                        "timestamp": "2024-01-24T20:58:43.000Z",
                        "range": 333.9299952884159
                    },
                    "subject": "2UZb3drEbIkLdMFcvEFqhjrX4X6",
                    "specversion": "1.0",
                    "location": {
                        "lon": "-121.87175",
                        "lat": "37.69915"
                    },
                    "id": "2bPwGLvWstG3eWtLXO82b5VYDP0",
                    "source": "dimo/integration/2ULfuC8U9dOqRshZBAi0lMM1Rrx",
                    "time": "2024-01-24T20:58:44.463Z",
                    "type": "zone.dimo.device.status.update"
                }
            }
        ]
    }
}

Send JSON Export Email of User Device Data by User Device ID

Path Parameters

Name
Type
Description

userDeviceId*

String

Headers

Name
Type
Description

Authorization*

String

{
    "status": "success",
    "userId": "CioweGY5RDI2MzIzQWI0OTE33UE2ZDU3QzI2NTE1QjAxRGUwMTg1NTM3ODcSBHdlYjE",
    "userDeviceId": "2UZb3drEbIkLdMFcvEFahjrX3X6",
    "message": "your request has been received; data will be sent to the email associated with your account"
}

DIMO Warning

This endpoint will be deprecated for non-J1939 developers, please use instead. For J1939 protocol developers, please reach out to the DIMO team to retain access to this API.

Developer Notes

To access the Vehicle data under the Device Data API, a token exchange transaction is required to obtain a 2nd JWT to get permission to access a given vehicle. Please check Token Exchange API prior to using this endpoint.

Get Vehicle Status by Vehicle ID

Retrieves the Vehicle Status by the Vehicle identified with the provided Vehicle ID.

Path Parameters

Name
Type
Description

tokenId*

String

Vehicle token ID, this is the token ID of your vehicle NFT. A prerequisite is to obtain a token that is permitted to access trips data for this specific vehicle.

Headers

Name
Type
Description

Authorization*

String

{
    "fuelPercentRemaining": 0.518,
    "odometer": 50414.2,
    "latitude": 37.697789,
    "longitude": -121.788662,
    "recordUpdatedAt": "2024-01-25T13:22:45Z",
    "recordCreatedAt": "2024-01-25T15:51:33.986023Z",
    "batteryVoltage": 12.709,
    "ambientTemp": 29
}
{
    "code": 401,
    "message": "Invalid JWT."
}

Get Vehicle Raw Status by Vehicle ID

Retrieves the Vehicle Raw Status by the Vehicle identified with the provided Vehicle ID.

Path Parameters

Name
Type
Description

tokenId*

String

Vehicle token ID, this is the token ID of your vehicle NFT. A prerequisite is to obtain a token that is permitted to access trips data for this specific vehicle.

Headers

Name
Type
Description

Authorization*

String

{
    "vin": {
        "value": "JTJGARBZ0M5023425",
        "source": "dimo/integration/22N2xaPOq2WW2gAHBHd0Ikn4Zob",
        "timestamp": "2024-01-25T21:51:38Z"
    },
    "make": {
        "value": "LEXUS",
        "source": "dimo/integration/22N2xaPOq2WW2gAHBHd0Ikn4Zob",
        "timestamp": "2024-01-25T21:51:38Z"
    },
    "year": {
        "value": 2021,
        "source": "dimo/integration/22N2xaPOq2WW2gAHBHd0Ikn4Zob",
        "timestamp": "2024-01-25T21:51:38Z"
    },
    "model": {
        "value": "NX 300 5-DOOR SUV 4X2",
        "source": "dimo/integration/22N2xaPOq2WW2gAHBHd0Ikn4Zob",
        "timestamp": "2024-01-25T21:51:38Z"
    },
    "errors": {
        "value": [
            {
                "type": "odometer",
                "errorCode": 502,
                "errorType": "UPSTREAM",
                "resolution": {
                    "type": "RETRY_LATER"
                },
                "description": "Smartcar received an error from an upstream source. Please retry your request at a later time."
            },
            {
                "type": "tires/pressure",
                "errorCode": 502,
                "errorType": "UPSTREAM",
                "resolution": {
                    "type": "RETRY_LATER"
                },
                "description": "Smartcar received an error from an upstream source. Please retry your request at a later time."
            },
            {
                "type": "fuel",
                "errorCode": 502,
                "errorType": "UPSTREAM",
                "resolution": {
                    "type": "RETRY_LATER"
                },
                "description": "Smartcar received an error from an upstream source. Please retry your request at a later time."
            },
            {
                "type": "location",
                "errorCode": 502,
                "errorType": "UPSTREAM",
                "resolution": {
                    "type": "RETRY_LATER"
                },
                "description": "Smartcar received an error from an upstream source. Please retry your request at a later time."
            }
        ],
        "source": "dimo/integration/22N2xaPOq2WW2gAHBHd0Ikn4Zob",
        "timestamp": "2024-01-25T21:51:38Z"
    },
    "timestamp": {
        "value": "2024-01-25T21:51:38.314435345Z",
        "source": "dimo/integration/22N2xaPOq2WW2gAHBHd0Ikn4Zob",
        "timestamp": "2024-01-25T21:51:38Z"
    },
    "vehicleId": {
        "value": "609324ff-c83d-419d-b240-f1fd98487e47",
        "source": "dimo/integration/22N2xaPOq2WW2gAHBHd0Ikn4Zob",
        "timestamp": "2024-01-25T21:51:38Z"
    }
}
{
    "code": 401,
    "message": "Invalid JWT."
}

Get Vehicle History by Vehicle ID

Retrieves the Vehicle History by the Vehicle identified with the provided Vehicle ID.

Path Parameters

Name
Type
Description

tokenId*

String

Vehicle token ID, this is the token ID of your vehicle NFT. A prerequisite is to obtain a token that is permitted to access trips data for this specific vehicle.

Query Parameters

Name
Type
Description

startDate

String

endDate

String

Headers

Name
Type
Description

Authorization*

String

{
    "took": 29,
    "timed_out": false,
    "_shards": {
        "total": 403,
        "successful": 403,
        "skipped": 400,
        "failed": 0
    },
    "hits": {
        "total": {
            "value": 152,
            "relation": "eq"
        },
        "max_score": 1.9834392,
        "hits": [
            {
                "_index": "device-status-prod-2024-01-24",
                "_id": "2bPvm7ZY2dAkslUlNOyxanXawBf",
                "_score": 1.9834392,
                "_source": {
                    "data": {
                        "lora": {
                            "devAddr": "7C080048",
                            "dc_balance": 237796046,
                            "fPort": "2",
                            "app_eui": "44494D4F5A4F4E45",
                            "payload_size": "31",
                            "fcnt": "18",
                            "deveui": "F4CE36B7251BF81C"
                        },
                        "ambientTemp": 32,
                        "odometer": 50404.2,
                        "year": 2021,
                        "latitude": 37.681686,
                        "deviceDefinitionId": "26G4j1YDKZhFeCsn12MAlyU3Y2H",
                        "nsat": 4,
                        "vinLast8": "M5023425",
                        "speed": 11,
                        "makeSlug": "lexus",
                        "barometricPressure": 101,
                        "fuelPercentRemaining": 0.518,
                        "modelSlug": "nx",
                        "engineLoad": 0.263,
                        "model": "NX",
                        "region": "Americas",
                        "make": "Lexus",
                        "longitude": -121.87558,
                        "timestamp": "2024-01-24T20:54:43.000Z",
                        "range": 331.37114474980734
                    },
                    "subject": "2UZb3drEbIkLdMFcvEFqhjrX4X6",
                    "specversion": "1.0",
                    "location": {
                        "lon": "-121.87558",
                        "lat": "37.681686"
                    },
                    "id": "2bPvm7ZY2dAkslUlNOyxanXawBf",
                    "source": "dimo/integration/2ULfuC8U9dOqRshZBAi0lMM1Rrx",
                    "time": "2024-01-24T20:54:44.376Z",
                    "type": "zone.dimo.device.status.update"
                }
            }
        ]
    }
}
{
    "code": 401,
    "message": "Invalid JWT."
}

Get Daily Distance Driven by User Device ID

Retrieves a daily summary of distances driven (in kilometers) tracked on the user device.

Path Parameters

Name
Type
Description

userDeviceId*

String

Query Parameters

Name
Type
Description

time_zone*

String

Headers

Name
Type
Description

Authorization*

String

{
    "days": [
        {
            "date": "2024-01-14",
            "distance": 37.19921875
        },
        {
            "date": "2024-01-15",
            "distance": null
        },
        {
            "date": "2024-01-16",
            "distance": null
        },
        {
            "date": "2024-01-17",
            "distance": 8.40234375
        },
        {
            "date": "2024-01-18",
            "distance": 14.5
        },
        {
            "date": "2024-01-19",
            "distance": null
        },
        {
            "date": "2024-01-20",
            "distance": null
        },
        {
            "date": "2024-01-21",
            "distance": null
        },
        {
            "date": "2024-01-22",
            "distance": null
        },
        {
            "date": "2024-01-23",
            "distance": null
        },
        {
            "date": "2024-01-24",
            "distance": 11
        }
    ]
}
{
    "code": 401,
    "message": "Invalid JWT."
}

Get Total Distance Driven by User Device ID

Retrieves a total distance driven (in kilometers) tracked on the user device since connection was established. Returns 0 if no odometer data was ever received.

Path Parameters

Name
Type
Description

userDeviceId*

String

Headers

Name
Type
Description

Authorization*

String

{
    "distanceDriven": 778.0999999999985,
    "units": "kilometers"
}
{
    "code": 401,
    "message": "Invalid JWT."
}


Swagger Doc

For userDeviceId, please refer to the User Device entity under .

Bearer authentication using the access_token generated from the .

GET /v1/user/device-data/{userDeviceId}/historical

This endpoint returns the historical data of a given time period, the data volume is very large so please handle with care.

For userDeviceId, please refer to the User Device entity under .

Starting timestamp in the (YYYY-MM-DD). Defaults to 2 weeks ago if not specified.

Ending timestamp in the (YYYY-MM-DD). Defaults to today if not specified.

Bearer authentication using the access_token generated from the .

POST /v1/user/device-data/{userDeviceId}/export/json/email

Enqueues a data export job for the user device identified by the userDeviceId. A link to download a JSON file of signals will be emailed to the address on file for the API user. This email is defined under the email.address if you .

For userDeviceId, please refer to the User Device entity under .

Bearer authentication using the access_token generated from the .

Vehicle Data

GET /v1/vehicle/{tokenId}/status

Bearer authentication using the token generated from the .

GET /v1/vehicle/{tokenId}/status-raw

Bearer authentication using the token generated from the .

GET /v1/vehicle/{tokenId}/history

This endpoint returns the historical data of a given time period, the data volume is very large so please handle with care.

Starting timestamp in the (YYYY-MM-DD). Defaults to 2 weeks ago if not specified.

Ending timestamp in the (YYYY-MM-DD). Defaults to today if not specified.

Bearer authentication using the token generated from the .

GET /v1/user/device-data/{userDeviceId}/daily-distance

For userDeviceId, please refer to the User Device entity under .

Timezone in format. Common examples are America/Los_Angeles and America/New_York; etcetera source files (Etc/GMT-0) is also supported.

Bearer authentication using the access_token generated from the .

GET /v1/user/device-data/{userDeviceId}/distance-driven

For userDeviceId, please refer to the User Device entity under .

Bearer authentication using the access_token generated from the .

⚠️
🔏
⚠️
🔐
{baseUrl}
{baseUrl}
{baseUrl}
{baseUrl}
{baseUrl}
{baseUrl}
{baseUrl}
{baseUrl}
Devices API
Web3 challenge
Devices API
Web3 challenge
Devices API
Web3 challenge
Devices API
Web3 challenge
Devices API
Web3 challenge
ISO8601 format
ISO8601 format
Token Exchange
Token Exchange
ISO8601 format
ISO8601 format
Token Exchange
TZ Identifier
LogoSwagger UI
look up the authenticated API user