Device Definitions API

Utility endpoints for Device Definitions.

Overview

The Device Definitions API provides helper functions for accessing vehicle device definitions that are now stored in Tableland, a decentralized cloud database. The API enables developers to decode Vehicle Identification Numbers (VINs) to retrieve corresponding device definition IDs and search for vehicle definitions by make, model, year, and other filters.

Base URL

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

Endpoints

Submit a VIN decoding request

Submits a decoding request for vehicle identification number, returns the device definition ID corresponding to the VIN. Use application/json for raw body parameters.

Parameters

countryCodestringRequired

3-letter ISO 3166-1 alpha-3 country code. Examples: 'USA', 'CHL', 'JPN'.

vinstringRequired

The Vehicle Identitifcation Number (VIN) of the vehicle.

POST/device-definitions/decode-vin

const vinDecodeRequest = await dimo.DeviceDefinitions.decodeVin({
  developerJwt: "eyJhbGc...ILlujqw",
  countryCode: "USA",
  vin: "1HGCM66886A015965"
})

Response

{
  deviceDefinitionId: 'lexus_nx_2021',
  newTransactionHash: ''
}

Get device definitions by search

Retrieves a list of device definitions by search filters.

Parameters

querystringRequired

Query filter (e.g. Lexus gx 2023)

makeSlugstringOptional

Make of the vehicle (e.g. audi, lexus, etc)

modelSlugstringOptional

Model of the vehicle (e.g. Tacoma, Accord, etc)

yearintegerOptional

Year of the vehicle (e.g. 2024)

pageintegerOptional

Page number (for pagination, defaults to the 1st page)

pageSizeintegerOptional

Page size (to specify the items to show in one page)

POST/device-definitions/search

const vinDecodeRequest = await dimo.DeviceDefinitions.search({
  developerJwt: "eyJhbGc...ILlujqw",
  query: "Lexus gx 2023",
  makeSlug,
  modelSlug,
  year,
  page,
  pageSize
})

Response

{
"deviceDefinitions": [
  {
    "id": "lexus_gx_2023",
    "legacy_ksuid": "2ZvYP0pSbQoXPh2WUdQPeA6g4dM",
    "name": "2023 Lexus GX",
    "make": "Lexus",
    "model": "GX",
    "year": 2023,
    "imageUrl": ""
  },
  {
    "id": "lexus_gx-460_2023",
    "legacy_ksuid": "2CMmZpP6YjaKQlQnGDSAzQ4PJEG",
    "name": "2023 Lexus GX 460",
    "make": "Lexus",
    "model": "GX 460",
    "year": 2023,
    "imageUrl": ""
  }
],
"facets": {
  "makes": [
    {
      "name": "Lexus",
      "count": 2
    }
  ],
  "models": [
    {
      "name": "GX",
      "count": 1
    },
    {
      "name": "GX 460",
      "count": 1
    }
  ],
  "years": [
    {
      "name": "2023",
      "count": 2
    }
  ]
},
"pagination": {
  "page": 1,
  "pageSize": 20,
  "totalItems": 2,
  "totalPages": 1
}
}