Developer

Electric Vehicle Search

VERSION 1.20.0
PUBLIC PREVIEW

To use the Maps SDK in your application you need to obtain a TomTom API key by following these instructions. Remember to keep your API key secure.

This API is unavailable on a Freemium or Pay As You Grow (PAYG) basis. [Request access]() to contact our sales team.

What is the EV Search?

TomTom Electric Vehicle Search (EV Search) is the service that provides up-to-date information about EV stations and their characteristics, such us accessibility, opening hours, and charging power. The service is based on the TomTom EV Charging Stations database. These APIs can be useful for drivers of electric cars to decide where to charge their EVs.

Upon completing this guide you will know how to retrieve detailed EV charging stations information.

API setup

The EV Search API is part of the TomTom SDK Search API.

Follow these steps to set up and use this API in your project:

Configure the project as described in the Project setup guide.

Then add the Search module dependency in the build.gradle.kts of your application module and synchronize the project.

implementation("com.tomtom.sdk.search:search-online:1.20.0")

The EV Search API is available to be used once you have successfully completed the Search module set up and added it as a dependency to your project.

Common use cases

The EV Search API provides the following functionality:

  • Searching for EV charging stations in a user-defined area (near a specific location) or along a route
  • Showing only EV charging stations matching the vehicle’s connector type, or matching the user’s preferred charging power rate
  • Showing only EV charging stations and their connectors that are currently available to the user

Working with EV Search

EV Search nearby

EV Search near a specific location requests can be created using the EvSearchOptions class, by providing a EvSearchOptions.geobias.

Unlike Fuzzy Search, EV Search uses geoBias coordinates for searching instead of a text query.

Additionally, the results can be refined by specifying the search radius, user locale, required power range, connector types, station status, and access type.

Also you can specify the maximum number of results to be returned.

Some useful parameters for the EV Search nearby are:

  • EvSearchOptions.geoBias: to perform geo-biased search, which boosts the ranking of search results based on the distance to geo-bias coordinates. This is a required parameter.
  • EvSearchOptions.radius: to limit results to a specific radius around the geo-bias coordinates.

Example

Once you have an EvSearchOptions object, provide it to the Search.evSearch(options, callback) API.

1val options =
2    EvSearchOptions(
3        geoBias = GeoPoint(latitude = 52.377271, longitude = 4.909466),
4        radius = Distance.kilometers(1),
5    )
6

7search.evSearch(
8    options,
9    object : EvSearchCallback {
10        override fun onSuccess(result: EvSearchResponse) {
11            /*
12                Your code goes here
13             */
14        }
15

16        override fun onFailure(failure: SearchFailure) {
17            /*
18                Your code goes here
19             */
20        }
21    },
22)

The following example shows how to use the EV Search API to find EV stations near a specific location:

1val options =
2    EvSearchOptions(
3        // user-defined area where the EV results will be biased towards
4        geoBias = GeoPoint(latitude = 52.377956, longitude = 4.897070),
5        radius = Distance.kilometers(1),
6        limit = 5,
7        // filter out EV stations with less than 100 kW
8        minPower = Power.kilowatts(100),
9        // filter out EV stations with more than 900 kW
10        maxPower = Power.kilowatts(900),
11        // filter out EV stations which do not have Tesla connectors
12        connectors = listOf(ConnectorType.Tesla),
13        // filter out EV stations which are not in-use or unavailable
14        status = Status.Available,
15        // filter out EV stations which are not public
16        accessTypes = listOf(AccessType.Public),
17    )
18

19search.evSearch(
20    options,
21    object : EvSearchCallback {
22        override fun onSuccess(result: EvSearchResponse) {
23            /*
24                Your code goes here
25             */
26        }
27

28        override fun onFailure(failure: SearchFailure) {
29            /*
30                Your code goes here
31             */
32        }
33    },
34)

The # API result expectations section explains the processing of results, which is shared between EV Search nearby and along a route APIs.

EV Search along a route

Similar to an EV Search near a location, there is also the possibility to do an EV Search along a route.

To do it you need to provide a route.

Example

Once you have an EvSearchOptions object, provide it to the Search.evSearch(options, callback) API.

1val options =
2    EvSearchOptions(
3        route = listOf(
4            GeoPoint(latitude = 52.36759, longitude = 4.9041635),
5            GeoPoint(latitude = 52.3676151, longitude = 4.9041241),
6            GeoPoint(latitude = 52.367835, longitude = 4.9037272),
7        ),
8    )
9

10search.evSearch(
11    options,
12    object : EvSearchCallback {
13        override fun onSuccess(result: EvSearchResponse) {
14            /*
15                Your code goes here
16             */
17        }
18

19        override fun onFailure(failure: SearchFailure) {
20            /*
21                Your code goes here
22             */
23        }
24    },
25)

The following section explains the processing of results, which is shared between EV Search nearby and along a route APIs.

API result expectations

The Search.evSearch(options, callback) API returns an EvSearchResponse object that contains the search results. If the request fails, a SearchFailure is returned.

The EvSearchResponse object contains a list of EVSearchResult instances. Every EVSearchResult object contains information about the EV station, such as the station ID, name, charging power, opening hours with time zone, and a Place object that contains the address and location of the station.

Next steps

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