Developer

EVSearch

VERSION 0.66.0
PUBLIC PREVIEW

What is the EV search?

TomTom Electric Vehicle Search (EV search) is a service that provides up-to-date information about EV stations and their characteristics, such as 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 station information.

API setup

The EV Search API is part of the 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 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 near a location

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. You can also 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

3search.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

12search.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}

EV Search along a route

To search for EV charging stations along a route, specify the route’s waypoints. This functionality is similar to searching for charging stations around a specific location.

Example

The following example shows how to use the EV Search API to find EV stations along a route:

1let route: Route = currentRoute
2let progress: RouteProgress = currentProgress
3

4let remainingRoute = route.routePoints.filter { $0.routeOffset > progress.distanceAlongRoute }
5let remainingCoordinates = remainingRoute.map { $0.coordinate }
6

7let options = EVSearchOptions(
8    route: remainingCoordinates,
9    limit: 5,
10    minPower: Measurement.tt.kilowatts(100.0), // only return EV stations with at least 100 kW
11    maxPower: Measurement.tt.kilowatts(900.0), // only return EV stations with at most 900 kW
12    connectors: [.tesla], // only return EV stations with Tesla connectors
13    status: .available, // only return EV stations that are available right now
14    accessTypes: [.public] // only return publicly accessible EV stations
15)
16

17search.evSearch(options: options) { result in
18    switch result {
19    case let .success(searchResponse):
20        // handle success
21        break
22    case let .failure(error):
23        // handle error
24        break
25    }
26}

Next steps

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