EV Service

Service version: v1
Last edit: 2022.08.05

Purpose

The EV Service API provides information about charging stations and the current availability of charging points. There are two types of information feeds: static and dynamic. Both static and dynamic feeds are served per country. Customers can provide their clients with updated availability information for all nearby charging stations.

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 TypeDescription
Charging parkCharging stations that are close to each other can be grouped into a charging park.
Charging stationOften corresponds to a single "pole". One station often has more than one charging point.
Charging pointCorresponds to an EVSE (Electric Vehicle Supply Equipment). 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 typeDescription
Charging station updateReferences a charging station by a UUID and includes updated charging points.
Charging point updateReferences a charging point.

Request data

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

HTTPS method: GET

  • Constants and parameters enclosed in curly brackets { } must be replaced with their values.
  • Please see the following Request parameters section with the required and optional parameters tables for their values. The generic request format is as follows.

Format

GET
URL request example
https://{baseURL}/electromobility/{version}/{feedType}/{countryCode}?key={apiKey}

Example

The static feed for Germany:

GET
URL request example
https://api.tomtom.com/electromobility/v1/static/de?key={apiKey}

The dynamic feed for Germany:

GET
URL request example
https://api.tomtom.com/electromobility/v1/dynamic/de?key={apiKey}

Request parameters

  • Required parameters must be used or the call will fail.
  • Parameters and values are case-sensitive.

Note: There are no optional parameters in this endpoint.

Required parameterDescription
baseURL
string
Base URL for calling TomTom services.
Value: api.tomtom.com
versionNumber
string
The version of the service to call.
Value: The current version is 1.
feedType
string
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.
Values: static or dynamic
countryCode
string
The ISO 3166-1 alpha-2 code of the country of interest in lowercase letters. See the Country Coverage for supported countries.
key
string
An API Key valid for the requested service.
Value: Your valid API Key.

Request headers

Note: There are no required request headers in this endpoint.

Optional headersDescription
Accept-EncodingRequests that the response is compressed in the specified way. The service supports HTTP compression if desired. Currently, gzip is supported.
Value: gzip
If-None-MatchProvides 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.
Value: Example entity-tag (E-tag): 4f3d2af4
If-Modified-SinceSpecifies 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.
Value: Example time stamp: Sat, 29 Oct 1994 19:43:31 GMT

Response data

Response codes

CodeMeaning & possible causes
200OK
304Not 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.
401Unauthorized: The supplied API key is not valid for this request (or missing)
404Not 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.
500Internal Server Error: Oops.

Response headers

HeaderDescription
Content-EncodingThe service supports http compression if desired. Currently, gzip is supported.
Value: gzip
Content-TypeThe format of the served resource. The service always provides data in xml.
Value: application/xml
DateA 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.
Value: Example timestamp: Wed, 20 Jul 2016 14:23:59 GMT
EtagEntity-tag of the served resource. Can be used by the client in the If-None-Match header field of subsequent requests in order to optimize the update procedure.
Value: Example entity-tag (E-tag): 4f3d2af4

Static feed

Example response (XML)

The available static information for all known charging stations in the requested country is provided as XML. The order of the stations is not specified.

1<?xml version="1.0" encoding="UTF-8"?>
2<chargingParks xmlns="http://www.tomtom.com/service/tis/chargingstation/static/1.0" xmlns:la="http://www.tomtom.com/service/tis/location/address/1.0" xmlns:lb="http://www.tomtom.com/service/tis/locBbox" xmlns:lh="http://www.tomtom.com/service/tis/location/hash/1.0" xmlns:lp="http://www.tomtom.com/service/tis/location/point/1.0" xmlns:meta="http://www.tomtom.com/service/tis/chargingstation/metadata/1.0" xmlns:oh="http://www.tomtom.com/service/tis/openinghours/1.0" xmlns:p="http://www.tomtom.com/service/tis/primitives/1.0" schemaVersion="1.0">
3 <meta:metaData>
4 <meta:creatorVersion>0.01-9.1.RC2@0</meta:creatorVersion>
5 <meta:creatorUUID>1232abdf-6ef7-4310-81b5-e7e4be3786f0</meta:creatorUUID>
6 <meta:creationTimeUTC>2016-01-13T09:06:46Z</meta:creationTimeUTC>
7 <meta:description>Example showing static charging station information</meta:description>
8 </meta:metaData>
9 <chargingPark>
10 <uuid>9876dcba-5f0e-2314-435a-aa34cd12f9fe</uuid>
11 <properties>
12 <name>Baker Motor</name>
13 <accessibilityType>public</accessibilityType>
14 <countryCode>DE</countryCode>
15 <contact>
16 <email>aEmail@address.com</email>
17 <web>http://tomtom.com</web>
18 <phone>+49 228 123231</phone>
19 <fax>+49 228 123232</fax>
20 </contact>
21 <operator>
22 <name>operator's name</name>
23 <contact>
24 <email>operatorEmail@address.com</email>
25 <web>http://tomtom.com/operator</web>
26 <phone>+49 228 223231</phone>
27 <fax>+49 228 223232</fax>
28 </contact>
29 <address>
30 <la:street>An den Treptowers 1</la:street>
31 <la:city>Berlin</la:city>
32 <la:postalCode>5455</la:postalCode>
33 <la:country>DE</la:country>
34 </address>
35 </operator>
36 <oh:openingHours>
37 <oh:openingPeriod>
38 <oh:day>
39 <oh:from>Mo</oh:from>
40 <oh:to>Fr</oh:to>
41 </oh:day>
42 <oh:time>
43 <oh:opens>00:00</oh:opens>
44 </oh:time>
45 </oh:openingPeriod>
46 <oh:openingPeriod>
47 <oh:day>
48 <oh:from>Sa</oh:from>
49 <oh:to>So</oh:to>
50 </oh:day>
51 <oh:time>
52 <oh:opens>06:30</oh:opens>
53 <oh:closes>10:00</oh:closes>
54 </oh:time>
55 </oh:openingPeriod>
56 </oh:openingHours>
57 </properties>
58 <locations>
59 <lb:boundingBox>
60 <lb:lowerLeft>
61 <p:latitude>50.73689</p:latitude>
62 <p:longitude>7.10662</p:longitude>
63 </lb:lowerLeft>
64 <lb:upperRight>
65 <p:latitude>50.73698</p:latitude>
66 <p:longitude>7.10674</p:longitude>
67 </lb:upperRight>
68 </lb:boundingBox>
69 <lp:pointLocation>
70 <p:latitude>50.73689</p:latitude>
71 <p:longitude>7.10674</p:longitude>
72 </lp:pointLocation>
73 <lh:locationHash>7230324</lh:locationHash>
74 </locations>
75 <chargingStations>
76 <chargingStation>
77 <uuid>1232abdf-6ef7-4310-81b5-e7e4be3786f0</uuid>
78 <externalId>anExternalId-A</externalId>
79 <name>First station</name>
80 <payment>
81 <method>Subscription</method>
82 </payment>
83 <locations>
84 <lb:boundingBox>
85 <lb:lowerLeft>
86 <p:latitude>50.73689</p:latitude>
87 <p:longitude>7.10662</p:longitude>
88 </lb:lowerLeft>
89 <lb:upperRight>
90 <p:latitude>50.73698</p:latitude>
91 <p:longitude>7.10674</p:longitude>
92 </lb:upperRight>
93 </lb:boundingBox>
94 <lp:pointLocation>
95 <p:latitude>50.73689</p:latitude>
96 <p:longitude>7.10674</p:longitude>
97 </lp:pointLocation>
98 <lh:locationHash>6138943</lh:locationHash>
99 </locations>
100 <chargingPoints>
101 <chargingPoint>
102 <uuid>5e332e95-b0bc-3f35-0000-00090af7026d</uuid>
103 <externalId>anExternalId-A_1a</externalId>
104 <name>First point</name>
105 <plugType>DC Charging &gt;50kW</plugType>
106 <locations>
107 <lp:pointLocation>
108 <p:latitude>50.73689</p:latitude>
109 <p:longitude>7.10676</p:longitude>
110 </lp:pointLocation>
111 </locations>
112 </chargingPoint>
113 <chargingPoint>
114 <uuid>7260f725-04ea-38a4-0000-00090af7026d</uuid>
115 <externalId>anExternalId-A_1b</externalId>
116 <name>Second point</name>
117 <plugType>380 - 480V, 3-Phase ≤63A</plugType>
118 </chargingPoint>
119 <chargingPoint>
120 <uuid>2823a471-1d57-311f-0000-00090af7026d</uuid>
121 <externalId>anExternalId-A_2a</externalId>
122 <name>Third point</name>
123 <plugType>Tesla</plugType>
124 <locations>
125 <lp:pointLocation>
126 <p:latitude>50.73689</p:latitude>
127 <p:longitude>7.10678</p:longitude>
128 </lp:pointLocation>
129 </locations>
130 </chargingPoint>
131 </chargingPoints>
132 </chargingStation>
133 <!-- Can contain more -->
134 </chargingStations>
135 </chargingPark>
136</chargingParks>

Request usage and freshness

By the nature of this static feed, there are infrequent changes in the provided content. It is reasonable to expect update requests approximately once per day. Using the support for the If-None-Match or If-Modified-Since header fields, update request frequencies higher than once per day could be used to minimize the delay between updated information being available on the server and being received by the client.

Dynamic feed

Example response (XML)

The Dynamic feed provides information for all known charging points in the requested country, referenced by a UUID. The order of the stations is not specified.

1<?xml version="1.0" encoding="UTF-8"?>
2<chargingParksDynamic xmlns="http://www.tomtom.com/service/tis/chargingstation/dynamic/1.0" xmlns:meta="http://www.tomtom.com/service/tis/chargingstation/metadata/1.0" schemaVersion="1.0">
3 <meta:metaData>
4 <meta:creatorVersion>0.01-9.1.RC2@0</meta:creatorVersion>
5 <meta:creatorUUID>1232abdf-6ef7-4310-81b5-e7e4be3786f0</meta:creatorUUID>
6 <meta:creationTimeUTC>2016-01-13T09:06:46Z</meta:creationTimeUTC>
7 <meta:description>Example showing dynamic charging station information</meta:description>
8 </meta:metaData>
9 <chargingStationUpdate>
10 <referenceUuid>798c93fc-ba74-102b-b5ef-00304891a58c</referenceUuid>
11 <chargingPointUpdates>
12 <chargingPointUpdate>
13 <referenceUuid>7260f725-04ea-38a4-0000-00090af7026d</referenceUuid>
14 <status>available</status>
15 </chargingPointUpdate>
16 <chargingPointUpdate>
17 <referenceUuid>2823a471-1d57-311f-0000-00090af7026d</referenceUuid>
18 <status>occupied</status>
19 </chargingPointUpdate>
20 </chargingPointUpdates>
21 <!-- Can contain more -->
22 </chargingStationUpdate>
23</chargingParksDynamic>

Response usage and freshness

Updates are provided regularly, and typically at a rate of once per minute. Using the support for If-None-Match or If-Modified-Since header fields, any update request frequencies higher than once-per-minute can be used to minimize the delay between updated information being available in the server and being received by the client.