Electric Vehicle Search

VERSION 1.8.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.

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.8.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
  • 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

EV search requests can be created using the EvSearchOptions class.

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 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 =
4 GeoBias(
5 coordinate = GeoPoint(latitude = 52.377271, longitude = 4.909466),
6 radius = Distance.kilometers(1),
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 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.

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 =
5 GeoBias(
6 coordinate = GeoPoint(latitude = 52.377956, longitude = 4.897070),
7 radius = Distance.kilometers(1),
8 ),
9 limit = 5,
10 // filter out EV stations with less than 100 kW
11 minPower = Power.kilowatts(100),
12 // filter out EV stations with more than 900 kW
13 maxPower = Power.kilowatts(900),
14 // filter out EV stations which do not have Tesla connectors
15 connectors = listOf(ConnectorType.Tesla),
16 // filter out EV stations which are not in-use or unavailable
17 status = Status.Available,
18 // filter out EV stations which are not public
19 accessTypes = listOf(AccessType.Public),
20 )
21
22search.evSearch(
23 options,
24 object : EvSearchCallback {
25 override fun onSuccess(result: EvSearchResponse) {
26 /*
27 Your code goes here
28 */
29 }
30
31 override fun onFailure(failure: SearchFailure) {
32 /*
33 Your code goes here
34 */
35 }
36 },
37)

Next steps

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