Sorry, you need to enable JavaScript to visit this website.

API

There are two types of information feeds: static and dynamic. Both types of feeds are available in every country where we offer service. Customers can provide their clients with updated availability information for all nearby charging stations.

EV Service API is available in versions 1.8 and 1.5 (legacy). The following sections describe general format of possible requests and responses. For exemplary responses for specific API version see subpages.

The Static Feed

The static feed provides comprehensive information that does not change rapidly; it is supposed to be downloaded a few times per day to pick up the latest changes. The feed has a hierarchical structure of the following elements:

  • Charging park - may include a group of one or more charging stations.

  • Charging station - may include one or more charging points. Each charging station often corresponds to a single "pole" that provides one or more charging points.

  • Charging point - Each charging point provides point location and a plug type.

The charging park holds shared properties of the grouped charging stations like operator, address, location, opening hours, etc.

Element Type Description

Charging park

charging stations who are close to each other can be grouped into a charging park.

Charging station

Often corresponds to a single "pole". One station often has more than one charging point.

Charging point

Corresponds to a EVSE. This can be thought of as the charging facility capable of accomodating one car.

Charging parks, stations and points have two IDs associated with them.

  • Uuid is a globally unique ID. It uniquely identifies an entity. The uuid is used as reference in the dynamic feed.

  • ExternalId is an ID used by external providers. In the case of charging points for certain providers this may be the EVSE ID. The external ID may not uniquely identify an entity in this feed.

The Dynamic Feed

The dynamic feed provides frequently updated information of the current availability for different types of charging points for each station, referenced by the unique per-station-ID provided in the static feed and a unique charging point ID.

Element Type Description

Charging station update

References a charging station by a uuid and includes updated charging points.

Charging point update

References a charging point.

Request

Format

https://<baseURL>/electromobility/<version>/<feedType>/<countryCode>?key=<apiKey>

Example

The static feed for Germany

https://api.tomtom.com/electromobility/1.8/static/de?key=<apiKey>

The dynamic feed for Germany

https://api.tomtom.com/electromobility/1.8/dynamic/de?key=<apiKey>

Parameters

Parameter Description Required Example Default

baseURL

Base URL for calling TomTom services.

Yes

api.tomtom.com

-

version

The version of the service to call.

Yes

v1

-

feedType

The type of information requested: + static - Static information about all stations in the country, such as name, location, and opening hours. + dynamic - Dynamic information about the current availability for all stations in the country.

Yes

static + dynamic

-

countryCode

The ISO 3166-1 alpha-2 code of the country of interest in lowercase letters. See the Country Coverage for supported countries.

Yes

de

-

apiKey

Authorization key for access to the API.

Yes

-

-

Headers

Header Description Required Example Default

[Accept-Encoding]

Requests that the response is compressed in the specified way. The service supports http compression if desired. Currently, gzip is supported.

No

gzip

-

[If-None-Match]

Provides the entity-tag (E-tag) of the requested resource as last received by the client. Allows efficient updates of cached information with a minimum amount of transaction overhead: The service can respond with a 304 (not modified) message if the data that would otherwise be provided has the same entity tag.

No

"4f3d2af4"

-

[If-Modified-Since]

Specifies the time stamp of the last actual update of the requested resource received by the client. Allows the service to respond with a 304 (not modified) message if no newer data is available.

No

Sat, 29 Oct 1994 19:43:31 GMT

-

Request Content

Plain GET messages are to be used to create requests for both the static and the dynamic feed.

Response

Response Codes

Code Meaning and possible causes

200

OK

304

Not Modified: The requested content did not change since the last request, as indicated by the value(s) of the If-Modified-Since and/or or If-None-Match http header fields.

401

Unauthorized: The supplied API key is not valid for this request (or missing)

404

Not Found: The specified path was not valid. At least one of the path parameters was omitted or not entered correctly. If an unsupported or invalid country code was specified, the included response message provides a list of valid available country codes.

500

Internal Server Error: Oops.

Response Headers

Header

Description

Values

Content-Encoding

The service supports http compression if desired. Currently, gzip is supported.

gzip

Content-Type

The format of the served resource. The service always provides data in xml.

application/xml

Date

A timestamp specifying when the response was sent. Can be used by the client in the If-Modified-Since header field of subsequent requests in order to optimize the update procedure.

Example: + "Wed, 20 Jul 2016 14:23:59 GMT"