Vehicle Metadata Provider

Introduction

The VehicleMetadataProvider enables developers to build vehicle selection interfaces that allow end-users to discover and select their electric vehicle for long-distance route planning.

For electric vehicles, accurate metadata is critical for calculating range, identifying appropriate charging stations along the route, and providing realistic travel time estimates that include charging stops. This guide demonstrates how to create a progressive vehicle selection flow using the provider’s filtering methods, specifically optimized for EV route planning scenarios.

Upon completing this guide, you will know how to build a UI to select vehicles by brand, model, and variant, to retrieve a configured Vehicle object ready for long-distance EV navigation planning.

Project setup

Configure the project as described in the Project setup guide. Then add the following dependencies to the build.gradle.kts file of your application module and synchronize the project as shown in the following example:

implementation("com.tomtom.sdk.vehicle:vehicle-metadata-provider:2.3.0-rc03")

Creating a vehicle metadata provider instance

Before using the vehicle metadata functionality, create an instance of VehicleMetadataProvider. We recommend to enable offline caching to ensure vehicle data availability even in areas with limited connectivity.

Important: Initial data fetch and subsequent updates will always require network access.

Initialize the provider with your application context, API key, and a cache directory:

1val vehicleMetadataProvider = VehicleMetadataProvider(
2    context = applicationContext,
3    apiKey = "YOUR_API_KEY",
4    cacheDirectory = CacheDirectory.DefaultDirectory,
5)

For online-only usage (requires continuous network connectivity):

1val vehicleMetadataProvider = VehicleMetadataProvider(
2    context = applicationContext,
3    apiKey = "YOUR_API_KEY",
4    cacheDirectory = CacheDirectory.NoDirectory,
5)

Important: Remember to close the provider when it’s no longer needed by calling vehicleMetadataProvider.close() to free up resources.

Building an EV vehicle selection flow

The VehicleMetadataProvider offers a hierarchical filtering approach ideal for EV selection: Brand → Model → Variant. This allows users to narrow down to their specific EV configuration, which is crucial for accurate range calculations and charging station planning.

Requesting vehicle brands

Start by retrieving the list of available vehicle brands. This provides the first level of filtering for your vehicle selection UI.

Create BrandOptions to configure the request. You can filter by engine type brands with at least one electric vehicle model:

1val brandOptions = BrandOptions(
2    engineType = EngineType.BATTERY_ELECTRIC
3)
4
5vehicleMetadataProvider.requestBrands(brandOptions) { result ->
6    result.onSuccess { brandsResponse ->
7        val evBrands = brandsResponse.brands
8        // Display brands to user
9        displayBrands(evBrands)
10    }.onFailure { failure ->
11        showError("Failed to load brands: ${failure.message}")
12    }
13}

The response contains a BrandsResponse with a list of Brand objects. Each brand has:

• id: A BrandId to use in subsequent filtering steps
• name: The display name of the brand (e.g., "Tesla", "BMW")

Requesting vehicle models

Once the user selects a brand, retrieve the available models for that brand using requestModels(). This step further narrows down the selection. Pass the selected BrandId from the previous step:

1val selectedBrandId = brand.id // BrandId from user selection
2
3val modelOptions = ModelOptions(
4    brandId = selectedBrandId,
5    engineType = EngineType.BATTERY_ELECTRIC
6)
7
8vehicleMetadataProvider.requestModels(modelOptions) { result ->
9    result.onSuccess { modelsResponse ->
10        val evModels = modelsResponse.models
11        // Display models to user
12        displayModels(evModels)
13    }.onFailure { failure ->
14        showError("Failed to load models: ${failure.message}")
15    }
16}

The response contains a ModelsResponse with a list of Model objects. Each model includes:

• id: A ModelId for the next filtering step
• name: The model name (e.g., "Model 3", "i4")
• brand: The associated Brand object with complete brand information

Requesting vehicle variants

The final filtering step retrieves specific variants with detailed specifications. The detailed specification can be used to have the user select the exact vehicle configuration, which is important for accurate routing.

To retrieve variants, call requestVehicleMetadata() with the selected BrandId and ModelId:

1val selectedBrandId = brand.id // BrandId from brand selection
2val selectedModelId = model.id // ModelId from model selection
3
4val metadataOptions = VehicleMetadataOptions(
5    brandId = selectedBrandId,
6    modelId = selectedModelId,
7    engineType = EngineType.BATTERY_ELECTRIC
8)
9
10vehicleMetadataProvider.requestVehicleMetadata(metadataOptions) { result ->
11    result.onSuccess { metadataResponse ->
12        val evVariants = metadataResponse.vehicleMetadata
13        // Display detailed vehicle variant information to user
14        displayEvVariants(evVariants)
15    }.onFailure { failure ->
16        showError("Failed to load vehicle metadata: ${failure.message}")
17    }
18}

The response contains a VehicleMetadataResponse with a list of VehicleMetadata objects. Each variant includes:

• id: The VehicleMetadataId needed for vehicle retrieval
• model: The complete Model object with brand information
• vehicleType: The type of vehicle (e.g., VehicleType.CAR)
• engineType: Confirmed as EngineType.BATTERY_ELECTRIC
• driveTrain: Drive configuration (e.g., DriveTrain.FWD, DriveTrain.RWD)
• variant: Variant name with manufacturer-specific details (e.g., "Long Range", "Performance")
• producedFrom / producedTo: Production date range
• productionStatus: Current status derived from production dates
• electricVehicleProperties: EV-specific data including:
  • Battery capacity
  • Plug types

Retrieving a configured Vehicle object for routing

Prerequisites for EV retrieval

To retrieve a configured vehicle, you need its unique vehicle ID. There are two ways to obtain this ID:

Option A: Discovery through filtering (consumer EV applications)

Use the filtering flow described above (requestBrands() → requestModels() → requestVehicleMetadata()) to let end-users discover and select their vehicle variant. The vehicle ID is included in the metadata response.

Option B: Pre-configured ID (fleet or automotive scenarios)

In fleet management or automotive environments, IDs may be known in advance and stored in the application’s configuration or retrieved from a fleet management system.

Retrieving the vehicle for EV route planning

Once you have the EV’s vehicle variant ID, call retrieveVehicle() to obtain a configured Vehicle:

1val evVehicleId = VehicleMetadataId(UUID.fromString("0f8e24bc-afd2-402e-ac9e-a3a35568be53")) // Obtained from filtering or pre-configured
2
3val retrieveOptions = buildRetrieveElectricVehicleOptions(
4    vehicleId = evVehicleId,
5    chargeLevel = ChargeLevel(
6        currentCharge = Energy.kilowattHours(15.0), // Should be provided by the user or vehicle system
7        maxCharge = Energy.kilowattHours(55.0), // Can be derived from vehicle metadata
8    ),
9    vehicleType = VehicleType.Car,
10)
11
12vehicleMetadataProvider.retrieveVehicle(retrieveOptions) { result ->
13    result.onSuccess { evVehicle ->
14        // Vehicle is configured with EV-specific properties and ready for long-distance EV route planning.
15        useEvForNavigation(evVehicle)
16    }.onFailure { failure ->
17        showError("Failed to retrieve EV: ${failure.message}")
18    }
19}

You can further customize vehicle properties using VehicleProvider.updateVehicleProperties().

Next steps

Now that you know how to select and retrieve a vehicle for route planning with VehicleMetadataProvider, here are recommendations on what to explore next: