Developer

EV POI details

VERSION 2.1.2

Get detailed information about Electric Vehicle (EV) charging stations (EV POIs) by their identifiers. This guide covers how to build request options, make calls using the Search interface, and handle responses including partial successes.

In addition to common POI information, the EV POI Details API provides EV-specific availability information that is not available in the non-EV POI Details API. This guide covers EV charging station details only. For POIs in other categories, see Point of Interest details.

When to use EV POI Details

  • After an EV Search to refresh information for selected charging stations.
  • When you already know one or more EV charging station IDs and need their details.

EV POI Details options

Use the EvPoiDetailsOptions to define which EV POIs to fetch and the locale of the result text. You can request details for a single Place.Id or multiple IDs.

Single ID

1val options = buildEvPoiDetailsOptions(id) {
2    locale = Locale.FRANCE
3}

Multiple IDs

val ids: Set<Place.Id> = setOf(id1, id2)
val options = buildEvPoiDetailsOptions(ids)

Making the request

To make a request, obtain a corresponding Search instance and call Search.requestEvPoiDetails with the options you built.

val result = search.requestEvPoiDetails(options)

Handling the response

The EvPoiDetailsResponse contains: - evPoiDetails: Set<EvPoiDetails> — details for successfully retrieved EV POIs. - failedIds: Set<Place.Id> — IDs that could not be resolved (invalid or non-EV POIs).

1when (result) {
2    is com.tomtom.sdk.common.Result.Success -> {
3        val evPoiDetails = result.value().evPoiDetails
4

5        for (details in evPoiDetails) {
6            val chargingPark = details.place.details?.chargingPark
7            chargingPark?.chargingStations?.forEach { station ->
8                station.chargingPoints.forEach { chargingPoint ->
9                    chargingPoint.status // Status indicates whether the point is available, occupied, etc.
10                    chargingPoint.connectors // Connectors provide information about the type of plug available
11                }
12            }
13            // Map to your UI as needed
14            // YOUR CODE GOES HERE
15        }
16

17        if (result.value().failedIds.isNotEmpty()) {
18            // Inform the user or retry for specific IDs
19            // YOUR CODE GOES HERE
20        }
21    }
22    is com.tomtom.sdk.common.Result.Failure -> {
23        val failure: SearchFailure = result.failure()
24

25        // Show an error message to the user or log the error for debugging
26        // YOUR CODE GOES HERE
27    }
28}

Partial success is possible: some IDs may succeed while others end up in failedIds.

If the call fails, you will receive a SearchFailure. Handle it gracefully and inform the user. For multi-ID requests, also check failedIds in successful responses.

Next steps

Since you have learned how to work with EV Search, here are recommendations for the next steps: