EVSearch

VERSION 0.48.0
PUBLIC PREVIEW

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. 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 TomTom SDK Search module. Follow these steps to set up and use it in your project Search module. The EV Search API is available to be used once you have completed the setup of the TomTom SDK Search module.

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 struct.

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:completion:) API.

1let options = EVSearchOptions(geoBias: CLLocationCoordinate2DMake(52.377271, 4.909466))
2
3onlineSearch.evSearch(options: options) { result in
4 switch result {
5 case let .success(evSearchResponse):
6 // handle success
7 break
8 case let .failure(error):
9 // handle error
10 break
11 }
12}

The Search.evSearch(options:completion:) API returns an EVSearchResponse object that contains the search results. If the request fails, an Error 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:

1let options = EVSearchOptions(
2 geoBias: CLLocationCoordinate2DMake(52.37, 4.901), // search for EV stations around this coordinate
3 radius: Measurement.tt.kilometers(2.0), // a radius around the geoBias location
4 limit: 5,
5 minPower: Measurement.tt.kilowatts(100.0), // only return EV stations with at least 100 kW
6 maxPower: Measurement.tt.kilowatts(900.0), // only return EV stations with at most 900 kW
7 connectors: [.tesla], // only return EV stations with Tesla connectors
8 status: .available, // only return EV stations that are available right now
9 accessTypes: [.public] // only return publicly accessible EV stations
10)
11
12onlineSearch.evSearch(options: options) { result in
13 switch result {
14 case let .success(searchResponse):
15 // handle success
16 break
17 case let .failure(error):
18 // handle error
19 break
20 }
21}

Next steps

Since you have learned how to use the EV search, here are recommendations for the next steps: