Device Data API Endpoints

Base URLs

Dev

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

Production

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

---

Vehicle Data 🔏

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

GET {baseUrl}/v1/vehicle/{tokenId}/status

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	Bearer authentication using the token generated from the Token Exchange.

200: Success

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

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

Get Vehicle Raw Status by Vehicle ID

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

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	Bearer authentication using the token generated from the Token Exchange.

200: Success

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

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

Get Vehicle History by Vehicle ID

GET {baseUrl}/v1/vehicle/{tokenId}/history

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

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

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	Starting timestamp in the ISO8601 format (YYYY-MM-DD). Defaults to 2 weeks ago if not specified.
endDate	String	Ending timestamp in the ISO8601 format (YYYY-MM-DD). Defaults to today if not specified.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the token generated from the Token Exchange.

200: Success

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

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

---

User Device Data 🔐

Developer Notes

1. The following endpoints defers back to using the Authentication 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 {baseUrl}/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	For userDeviceId, please refer to the User Device entity under Devices API.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

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

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

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.

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

Path Parameters

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API.

Query Parameters

Name	Type	Description
startDate	String	Starting timestamp in the ISO8601 format (YYYY-MM-DD). Defaults to 2 weeks ago if not specified.
endDate	String	Ending timestamp in the ISO8601 format (YYYY-MM-DD). Defaults to today if not specified.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

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

Get Daily Distance Driven by User Device ID

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

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

Path Parameters

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API.

Query Parameters

Name	Type	Description
time_zone*	String	Timezone in TZ Identifier format. Common examples are America/Los_Angeles and America/New_York; etcetera source files (Etc/GMT-0) is also supported.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

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

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

404: Not Found

Get Total Distance Driven by User Device ID

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

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	For userDeviceId, please refer to the User Device entity under Devices API.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

{
    "distanceDriven": 778.0999999999985,
    "units": "kilometers"
}

401: Unauthorized

{
    "code": 401,
    "message": "Invalid JWT."
}

404: Not Found

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

POST {baseUrl}/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 look up the authenticated API user.

Path Parameters

Name	Type	Description
userDeviceId*	String	For userDeviceId, please refer to the User Device entity under Devices API.

Headers

Name	Type	Description
Authorization*	String	Bearer authentication using the access_token generated from the Web3 challenge.

200: Success

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

---

Swagger Doc

Swagger UI