Electric Vehicle Search
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.15.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 )67search.evSearch(8 options,9 object : EvSearchCallback {10 override fun onSuccess(result: EvSearchResponse) {11 /*12 Your code goes here13 */14 }1516 override fun onFailure(failure: SearchFailure) {17 /*18 Your code goes here19 */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 towards4 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 kW8 minPower = Power.kilowatts(100),9 // filter out EV stations with more than 900 kW10 maxPower = Power.kilowatts(900),11 // filter out EV stations which do not have Tesla connectors12 connectors = listOf(ConnectorType.Tesla),13 // filter out EV stations which are not in-use or unavailable14 status = Status.Available,15 // filter out EV stations which are not public16 accessTypes = listOf(AccessType.Public),17 )1819search.evSearch(20 options,21 object : EvSearchCallback {22 override fun onSuccess(result: EvSearchResponse) {23 /*24 Your code goes here25 */26 }2728 override fun onFailure(failure: SearchFailure) {29 /*30 Your code goes here31 */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 )910search.evSearch(11 options,12 object : EvSearchCallback {13 override fun onSuccess(result: EvSearchResponse) {14 /*15 Your code goes here16 */17 }1819 override fun onFailure(failure: SearchFailure) {20 /*21 Your code goes here22 */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: