Developer

EV Search Nearby

Request Access
Service version: 2
Last edit: 2024.12.06
TomTom Maps

Important note
This EV Search API is unavailable on a Freemium or Pay As You Grow (PAYG) basis.
Click the Request Access button above to contact our Sales team.

Purpose

The EV Search Nearby endpoint provides information about the nearest EV POIs (points of interest) based on either a circular area or a bounding box. By providing optional request parameters, the API allows filtering of the response by connector type, availability status, etc.

The API accepts the search coordinates and radius, to search within a circular area or the top-left and bottom-right coordinates of the bounding box. Therefore there are two valid sets of required parameters: lat, lon and radius or topLeft and btmRight. In case both sets are provided, the API will return the radius-based circular search results.

Request data

HTTPS method: GET

For ease of viewing and identification:

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

Request format

get
Request format
https://{baseURL}/search/{versionNumber}/evsearch?key={Your_API_Key}&lat={latitude}&lon={longitude}&radius={radius}&status={status}&connector={connector}&accessType={accessType}&restriction={restriction}&capability={capability}&minPowerKW={minPowerKW}&maxPowerKW={maxPowerKW}&limit={limit}&view={view}

URL example

get
Request URL example
https://api.tomtom.com/search/2/evsearch?key={Your_API_Key}&lat=52.36&lon=4.89&radius=1000&status=Available&connector=IEC62196Type2Outlet&accessType=Public,Authorized&restriction=evOnly&capability=ChargingProfileCapable&minPowerKW=22.2&maxPowerKW=43.2&limit=20&view=Unified

Request curl command example

get
Request curl command
curl 'https://api.tomtom.com/search/2/evsearch?key={Your_API_Key}&lat=52.36&lon=4.89&radius=1000&status=available,unknown&connector=IEC62196Type2Outlet&accessType=Public&restriction=evOnly&capability=ChargingProfileCapable&minPowerKW=22.2&maxPowerKW=43.2&limit=20&view=Unified'

Request parameters

The following table describes the parameters that can be used in a request.

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

baseURL
string

The base URL for calling the API.
Value: api.tomtom.com

versionNumber
string

The service version.
Value: The current value is 2.

key
string

An API Key valid for the requested service.
Value: Your valid API Key.

Optional parametersDescription

lat
double

Latitude of the location to search for.
Value: A double value between -90 and 90.
Example: 37.337

lon
double

Longitude of the location to search for.
Value: A double value between -180 and 180.
Example: -121.89

radius
integer

Radius in meters to search within.
Value: An integer value between 1 and 100000 representing the radius in meters.
Example: 1000

topLeft
string

The top-left corner of the bounding box to search within. It should be used in combination with the btmRight parameter.
Value: A comma-separated string composed by lat,lon.
Example: 52.3749,4.8641

btmRight
string

The bottom-right corner of the bounding box to search within. It should be used in combination with the topLeft parameter.
Value: A comma-separated string composed by lat,lon.
Example: 52.361,4.8977

limit
integer

Maximum number of search results that will be returned.
Value: An integer value between 1 and 100.
Default: 10

status
string

The comma separated status values of charging points to be filtered.
Enum:

  • Available
  • Reserved
  • Occupied
  • OutOfService
  • Unknown

connector
string

A comma-separated list of connector types which could be used to restrict the result to specific connector types. See the list of Supported Connector Types.
Value: A comma-separated list of connector types (in any order).
Example: IEC62196Type2Outlet,IEC62196Type2CableAttached

accessType
string

The comma separated access types, which could be used to restrict the results to EV POIs with specific access types.
Enum:

  • Public
  • Authorized
  • Restricted
  • Private

restriction
string

The comma separated restrictions, which could be used to restrict the results to EV POIs with specific restrictions.
Enum:

  • evOnly
  • plugged
  • disabled
  • customers
  • motorcycles

capability
string

The comma-separated capabilities, which could be used to restrict the results to EV POIs with specific capabilities.
Enum:

  • ChargingProfileCapable
  • ChargingPreferencesCapable
  • ChipCardSupport
  • ContactlessCardSupport
  • CreditCardPayable
  • DebitCardPayable
  • PedTerminal
  • RemoteStartStopCapable
  • Reservable
  • RfidReader
  • StartSessionConnectorRequired
  • TokenGroupCapable
  • UnlockCapable
  • PlugAndCharge

minPowerKW
double

An optional parameter that could be used to restrict the result to charging stations with connectors having a specific minimal value of power in kilowatts (closed interval

  • with that value).
    Value: A double value representing the power rate in kilowatts.
    Example: 22.2
    This parameter might be used together with [maxPowerKW].

maxPowerKW
double

An optional parameter that could be used to restrict the result to charging stations with connectors having a specific maximum value of power in kilowatts (closed interval with that value).
Value: A double value representing the power rate in kilowatts.
Example: 43.2
This parameter might be used together with [minPowerKW].

view


string

Geopolitical View. The context used to resolve the handling of disputed territories.


Enum: Unified, AR, IL, IN, MA, PK, RU, TR, CN


Default values:

  • Argentina, default view: AR, available views: Unified, IL, IN, MA, PK, RU, TR, CN

  • India, default view: IN, available views: -

  • Morocco, default view: MA, available views: Unified, AR, IL, IN, PK, RU, TR, CN

  • Pakistan, default view: PK, available views: Unified, AR, IL, IN, MA, RU , TR, CN

  • Russia, default view: RU, available views: Unified, AR, IL, IN, MA, PK, TR, CN

  • Turkey, default view: TR, available views: Unified, AR, IL, IN, MA, PK, RU, CN

  • China, default view: CN, available views: Unified, AR, IL, IN, MA, PK, RU, TR

  • Others, default view: Unified, available views: AR, IL, IN, MA, PK, RU, TR, CN

Request headers

The following table describes HTTP request headers.

Optional headersDescription
Tracking-ID

Specifies an identifier for the request.

  • It can be used to trace a call.

  • The value must match the regular expression '^[a-zA-Z0-9-]{1,100}$'.

  • An example of the format that matches this regular expression is UUID (e.g., 9ac68072-c7a4-11e8-a8d5-f2801f1b9fd1 ). For details check RFC 4122.

  • If specified, it is replicated in the Tracking-ID response header.

  • It is only meant to be used for support and does not involve tracking of you or your users in any form.

Value: An identifier for the request.

Accept

Specifies the response format of the API request, one of the following values:

  • application/json Default if the header is not provided.
  • application/xml
Accept-Language

Should be one of the TomTom supported IETF language tags, case insensitive. When data in the specified language is not available for a specific field or the language is not specified, the NGT (NeutralGroundTruth) of the POI will be used.

JMESPath

This header can be used to execute a JMESPath query on the API response. For more information refer to JMESPath examples.
Default value: If no header is provided, all response fields are included.
Note: The header value has to be URL encoded.
Example: results[*].{id:id,position:position} will only return the id and position fields of the results.

Response data

Response body

If the Accept header value is set to application/json, the response will be a JSON object with the following structure:

Json Response body
1{
2    "summary": {
3        "numResults": 2,
4        "totalResults": 191
5    },
6    "results": [
7        {
8            "id": "939d44d0-cf00-42e9-b9f3-bf4d2de125b5",
9            "name": "TotalEnergies",
10            "position": {
11                "lat": 52.364941,
12                "lon": 4.8935986
13            },
14            "chargingStations": [
15                {
16                    "id": "e0bead1c-6884-11ee-9f49-42010aa40fc0",
17                    "chargingPoints": [
18                        {
19                            "capabilities": [
20                                "CreditCardPayable",
21                                "RemoteStartStopCapable",
22                                "RfidReader"
23                            ],
24                            "connectors": [
25                                {
26                                    "id": "1",
27                                    "currentA": 25,
28                                    "currentType": "AC3",
29                                    "ratedPowerKW": 17.0,
30                                    "type": "IEC62196Type2Outlet",
31                                    "voltageV": 230
32                                }
33                            ],
34                            "evseId": "NL-GFX-ETNLP011512-1",
35                            "physicalReference": "TNLP011512",
36                            "status": "Available"
37                        },
38                        {
39                            "capabilities": [
40                                "CreditCardPayable",
41                                "RemoteStartStopCapable",
42                                "RfidReader"
43                            ],
44                            "connectors": [
45                                {
46                                    "id": "2",
47                                    "currentA": 25,
48                                    "currentType": "AC3",
49                                    "ratedPowerKW": 17.0,
50                                    "type": "IEC62196Type2Outlet",
51                                    "voltageV": 230
52                                }
53                            ],
54                            "evseId": "NL-GFX-ETNLP011512-2",
55                            "physicalReference": "TNLP011512",
56                            "status": "Occupied"
57                        }
58                    ]
59                }
60            ],
61            "address": {
62                "countryCode": "NL",
63                "countryCodeISO3": "NLD",
64                "country": "Netherlands",
65                "countrySubdivision": "North Holland",
66                "countrySubdivisionName": "North Holland",
67                "countrySubdivisionCode": "NH",
68                "freeformAddress": "Oudezijds Voorburgwal 99F, 1012 EM Amsterdam",
69                "localName": "Amsterdam",
70                "municipality": "Amsterdam",
71                "postalCode": "1012 EM",
72                "streetNumber": "99F",
73                "streetName": "Oudezijds Voorburgwal"
74            },
75            "openingHours": {
76                "mode": "nextSevenDays",
77                "timeRanges": [
78                    {
79                        "startTime": {
80                            "date": "2024-05-02",
81                            "hour": 0,
82                            "minute": 0
83                        },
84                        "endTime": {
85                            "date": "2024-05-09",
86                            "hour": 0,
87                            "minute": 0
88                        }
89                    }
90                ]
91            },
92            "timeZone": {
93                "ianaId": "Europe/Amsterdam"
94            },
95            "paymentOptions": [
96                {
97                    "brands": [
98                        {
99                            "name": "Plugsurfing"
100                        },
101                        {
102                            "name": "Eneco"
103                        },
104                        {
105                            "name": "Vattenfall InCharge - Incharge"
106                        },
107                        {
108                            "name": "EVBox Charge"
109                        },
110                        {
111                            "name": "Shell Recharge"
112                        },
113                        {
114                            "name": "Vandebron"
115                        }
116                    ]
117                }
118            ],
119            "accessType": "Public"
120        },
121        {
122            "id": "c31bc9fb-8935-4df5-97c6-51acbaccc601",
123            "name": "EQUANS",
124            "position": {
125                "lat": 52.3653884,
126                "lon": 4.8922383
127            },
128            "chargingStations": [
129                {
130                    "id": "67335c40-4e72-11e8-8f53-42010a840002",
131                    "chargingPoints": [
132                        {
133                            "capabilities": [
134                                "RemoteStartStopCapable",
135                                "RfidReader"
136                            ],
137                            "connectors": [
138                                {
139                                    "id": "1",
140                                    "currentA": 16,
141                                    "currentType": "AC3",
142                                    "ratedPowerKW": 11.0,
143                                    "type": "IEC62196Type2Outlet",
144                                    "voltageV": 230
145                                }
146                            ],
147                            "evseId": "NL-GFX-EEVB-P1552388-1",
148                            "physicalReference": "1552388",
149                            "status": "Occupied"
150                        },
151                        {
152                            "capabilities": [
153                                "RemoteStartStopCapable",
154                                "RfidReader"
155                            ],
156                            "connectors": [
157                                {
158                                    "id": "2",
159                                    "currentA": 16,
160                                    "currentType": "AC3",
161                                    "ratedPowerKW": 11.0,
162                                    "type": "IEC62196Type2Outlet",
163                                    "voltageV": 230
164                                }
165                            ],
166                            "evseId": "NL-GFX-EEVB-P1552388-2",
167                            "physicalReference": "1552388",
168                            "status": "OutOfService"
169                        }
170                    ]
171                }
172            ],
173            "address": {
174                "countryCode": "NL",
175                "countryCodeISO3": "NLD",
176                "country": "Netherlands",
177                "countrySubdivision": "North Holland",
178                "countrySubdivisionName": "North Holland",
179                "countrySubdivisionCode": "NH",
180                "freeformAddress": "Herengracht 505, 1017 BV Amsterdam",
181                "localName": "Amsterdam",
182                "municipality": "Amsterdam",
183                "postalCode": "1017 BV",
184                "streetNumber": "505",
185                "streetName": "Herengracht"
186            },
187            "openingHours": {
188                "mode": "nextSevenDays",
189                "timeRanges": [
190                    {
191                        "startTime": {
192                            "date": "2024-05-02",
193                            "hour": 0,
194                            "minute": 0
195                        },
196                        "endTime": {
197                            "date": "2024-05-09",
198                            "hour": 0,
199                            "minute": 0
200                        }
201                    }
202                ]
203            },
204            "timeZone": {
205                "ianaId": "Europe/Amsterdam"
206            },
207            "paymentOptions": [
208                {
209                    "brands": [
210                        {
211                            "name": "Plugsurfing"
212                        },
213                        {
214                            "name": "Vattenfall InCharge - Incharge"
215                        },
216                        {
217                            "name": "EVBox Charge"
218                        },
219                        {
220                            "name": "Shell Recharge"
221                        },
222                        {
223                            "name": "Vandebron"
224                        }
225                    ]
226                }
227            ],
228            "accessType": "Public"
229        }
230    ]
231}

If the Accept header value is set to application/xml, the response will be a XML object with the following structure:

XML Response body
1<response>
2    <summary>
3        <numResults>2</numResults>
4        <totalResults>191</totalResults>
5    </summary>
6    <results>
7        <item>
8            <id>939d44d0-cf00-42e9-b9f3-bf4d2de125b5</id>
9            <name>TotalEnergies</name>
10            <position>
11                <lat>52.364941</lat>
12                <lon>4.8935986</lon>
13            </position>
14            <address>
15                <countryCode>NL</countryCode>
16                <countryCodeISO3>NLD</countryCodeISO3>
17                <country>Netherlands</country>
18                <countrySubdivision>North Holland</countrySubdivision>
19                <countrySubdivisionName>North Holland</countrySubdivisionName>
20                <countrySubdivisionCode>NH</countrySubdivisionCode>
21                <freeformAddress>Oudezijds Voorburgwal 99F, 1012 EM Amsterdam</freeformAddress>
22                <localName>Amsterdam</localName>
23                <municipality>Amsterdam</municipality>
24                <postalCode>1012 EM</postalCode>
25                <streetNumber>99F</streetNumber>
26                <streetName>Oudezijds Voorburgwal</streetName>
27            </address>
28            <openingHours>
29                <mode>nextSevenDays</mode>
30                <timeRanges>
31                    <timeRange>
32                        <startTime>
33                            <date>2024-05-02</date>
34                            <hour>0</hour>
35                            <minute>0</minute>
36                        </startTime>
37                        <endTime>
38                            <date>2024-05-09</date>
39                            <hour>0</hour>
40                            <minute>0</minute>
41                        </endTime>
42                    </timeRange>
43                </timeRanges>
44            </openingHours>
45            <timeZone>
46                <ianaId>Europe/Amsterdam</ianaId>
47            </timeZone>
48            <accessType>Public</accessType>
49            <chargingStations>
50                <chargingStation>
51                    <id>e0bead1c-6884-11ee-9f49-42010aa40fc0</id>
52                    <chargingPoints>
53                        <chargingPoint>
54                            <evseId>NL-GFX-ETNLP011512-1</evseId>
55                            <physicalReference>TNLP011512</physicalReference>
56                            <status>Available</status>
57                            <capabilities>
58                                <capability>CreditCardPayable</capability>
59                                <capability>RemoteStartStopCapable</capability>
60                                <capability>RfidReader</capability>
61                            </capabilities>
62                            <connectors>
63                                <connector>
64                                    <id>1</id>
65                                    <currentA>25</currentA>
66                                    <currentType>AC3</currentType>
67                                    <ratedPowerKW>17.0</ratedPowerKW>
68                                    <type>IEC62196Type2Outlet</type>
69                                    <voltageV>230</voltageV>
70                                </connector>
71                            </connectors>
72                        </chargingPoint>
73                        <chargingPoint>
74                            <evseId>NL-GFX-ETNLP011512-2</evseId>
75                            <physicalReference>TNLP011512</physicalReference>
76                            <status>Occupied</status>
77                            <capabilities>
78                                <capability>CreditCardPayable</capability>
79                                <capability>RemoteStartStopCapable</capability>
80                                <capability>RfidReader</capability>
81                            </capabilities>
82                            <connectors>
83                                <connector>
84                                    <id>2</id>
85                                    <currentA>25</currentA>
86                                    <currentType>AC3</currentType>
87                                    <ratedPowerKW>17.0</ratedPowerKW>
88                                    <type>IEC62196Type2Outlet</type>
89                                    <voltageV>230</voltageV>
90                                </connector>
91                            </connectors>
92                        </chargingPoint>
93                    </chargingPoints>
94                </chargingStation>
95            </chargingStations>
96            <paymentOptions>
97                <paymentOption>
98                    <brands>
99                        <brand>
100                            <name>Plugsurfing</name>
101                        </brand>
102                        <brand>
103                            <name>Eneco</name>
104                        </brand>
105                        <brand>
106                            <name>Vattenfall InCharge - Incharge</name>
107                        </brand>
108                        <brand>
109                            <name>EVBox Charge</name>
110                        </brand>
111                        <brand>
112                            <name>Shell Recharge</name>
113                        </brand>
114                        <brand>
115                            <name>Vandebron</name>
116                        </brand>
117                    </brands>
118                </paymentOption>
119            </paymentOptions>
120        </item>
121        <item>
122            <id>c31bc9fb-8935-4df5-97c6-51acbaccc601</id>
123            <name>EQUANS</name>
124            <position>
125                <lat>52.3653884</lat>
126                <lon>4.8922383</lon>
127            </position>
128            <address>
129                <countryCode>NL</countryCode>
130                <countryCodeISO3>NLD</countryCodeISO3>
131                <country>Netherlands</country>
132                <countrySubdivision>North Holland</countrySubdivision>
133                <countrySubdivisionName>North Holland</countrySubdivisionName>
134                <countrySubdivisionCode>NH</countrySubdivisionCode>
135                <freeformAddress>Herengracht 505, 1017 BV Amsterdam</freeformAddress>
136                <localName>Amsterdam</localName>
137                <municipality>Amsterdam</municipality>
138                <postalCode>1017 BV</postalCode>
139                <streetNumber>505</streetNumber>
140                <streetName>Herengracht</streetName>
141            </address>
142            <openingHours>
143                <mode>nextSevenDays</mode>
144                <timeRanges>
145                    <timeRange>
146                        <startTime>
147                            <date>2024-05-02</date>
148                            <hour>0</hour>
149                            <minute>0</minute>
150                        </startTime>
151                        <endTime>
152                            <date>2024-05-09</date>
153                            <hour>0</hour>
154                            <minute>0</minute>
155                        </endTime>
156                    </timeRange>
157                </timeRanges>
158            </openingHours>
159            <timeZone>
160                <ianaId>Europe/Amsterdam</ianaId>
161            </timeZone>
162            <accessType>Public</accessType>
163            <chargingStations>
164                <chargingStation>
165                    <id>67335c40-4e72-11e8-8f53-42010a840002</id>
166                    <chargingPoints>
167                        <chargingPoint>
168                            <evseId>NL-GFX-EEVB-P1552388-1</evseId>
169                            <physicalReference>1552388</physicalReference>
170                            <status>Occupied</status>
171                            <capabilities>
172                                <capability>RemoteStartStopCapable</capability>
173                                <capability>RfidReader</capability>
174                            </capabilities>
175                            <connectors>
176                                <connector>
177                                    <id>1</id>
178                                    <currentA>16</currentA>
179                                    <currentType>AC3</currentType>
180                                    <ratedPowerKW>11.0</ratedPowerKW>
181                                    <type>IEC62196Type2Outlet</type>
182                                    <voltageV>230</voltageV>
183                                </connector>
184                            </connectors>
185                        </chargingPoint>
186                        <chargingPoint>
187                            <evseId>NL-GFX-EEVB-P1552388-2</evseId>
188                            <physicalReference>1552388</physicalReference>
189                            <status>OutOfService</status>
190                            <capabilities>
191                                <capability>RemoteStartStopCapable</capability>
192                                <capability>RfidReader</capability>
193                            </capabilities>
194                            <connectors>
195                                <connector>
196                                    <id>2</id>
197                                    <currentA>16</currentA>
198                                    <currentType>AC3</currentType>
199                                    <ratedPowerKW>11.0</ratedPowerKW>
200                                    <type>IEC62196Type2Outlet</type>
201                                    <voltageV>230</voltageV>
202                                </connector>
203                            </connectors>
204                        </chargingPoint>
205                    </chargingPoints>
206                </chargingStation>
207            </chargingStations>
208            <paymentOptions>
209                <paymentOption>
210                    <brands>
211                        <brand>
212                            <name>Plugsurfing</name>
213                        </brand>
214                        <brand>
215                            <name>Vattenfall InCharge - Incharge</name>
216                        </brand>
217                        <brand>
218                            <name>EVBox Charge</name>
219                        </brand>
220                        <brand>
221                            <name>Shell Recharge</name>
222                        </brand>
223                        <brand>
224                            <name>Vandebron</name>
225                        </brand>
226                    </brands>
227                </paymentOption>
228            </paymentOptions>
229        </item>
230    </results>
231</response>

Response fields

The following table describes all of the fields that can appear in a response. Fields are listed by the response section they belong to and in the order that they appear in the response.

Primary fields
FieldDescription

summary
string

Summary information about the search that was performed.

results
array

Array of result objects.

summary
FieldDescription

numResults
integer

Number of results in the response.

totalResults
integer

Total number of results found.

result
FieldDescription

id
string

EV POI Id.

name
string

Name of the POI.

phone
string

Phone number of the POI.

address
object

Structured address for the result.

chargingStations
array

Array of chargingStation objects.

openingHours
object

Opening hours for the POI.

timeZone
object

Time zone for the POI.

brands
array

Array of brand objects.

paymentOptions
array

Array of paymentOption objects.

accessType
string

Access type of the EV POI station.
Enum:

  • Public
    No restriction, poi is open for public use.

  • Authorized
    Restriction applies, often requires a permit or registration, i.e. EmployeesOnly.

  • Restricted
    Restricted POIs are public locations with the intention to be used by a certain member of the public, i.e., ResidentsOnly.

  • Private
    Private POIs are locations that are not open to the public.

position
object

Position of the EV POI.
Address
FieldDescription

streetNumber
string

The building number on the street.

streetName
string

The street name.

municipality Subdivision
string

Sub / Super City.

municipality
string

City / Town.

countrySecondary Subdivision
string

Country.

countryTertiary Subdivision
string

Named area.

countrySubdivision
string

State or Province. For regions like USA, CAN, & GB, this will be the province code, and for the rest
the subdivision name.

countrySubdivisionName
string

State or Province name.

countrySubdivisionCode
string

State or Province code. Only for regions like USA, CAN, GB.

postalCode
string

Postal code / Zip code.

extendedPostalCode
string

Extended postal code (availability dependent on region).

countryCode
string

The two-letter code of the country.

country
string

The country name.

countryCodeISO3
string

ISO alpha-3 country code.

freeformAddress
string

An address line formatted according to the formatting rules of the result's country of origin.

countrySubdivisionName
string

The full name of the first level of a country's administrative hierarchy.

  • This field appears only in case countrySubdivision is presented in an abbreviated form.
  • Supported only for USA, Canada, and Great Britain.

localName
string

An address component which represents the name of a geographic area or locality that groups a number of addressable objects for addressing purposes, without being an administrative unit.
chargingStation
FieldDescription

id
string

Charging station Id.

chargingPoints
object

Array of chargingPoint objects.
chargingPoint
FieldDescription

evseId
string

Charging point Id with definition.

capabilities
list <string>

List of capabilities.
Enum:

  • ChargingProfileCapable
    The charging point supports charging profiles.

  • ChargingPreferencesCapable
    The charging point supports charging preferences.

  • ChipCardSupport
    The charging point has a payment terminal that supports chip cards.

  • ContactlessCardSupport
    The charging point has a payment terminal that supports contactless cards.

  • CreditCardPayable
    The charging point has a payment terminal that supports credit cards.

  • DebitCardPayable
    The charging point has a payment terminal that supports debit cards.

  • PedTerminal
    The charging point has a payment terminal with a pin-code entry device.

  • RemoteStartStopCapable
    The charging point supports remote start and stop functionality.

  • Reservable
    The charging point can be reserved.

  • RfidReader   Charging at this point can be authorized with an RFID token.

  • StartSessionConnector Required   When a StartSession is sent to the charging point, the MSP must add the optional connector id field in the StartSession object.

  • TokenGroupCapable
    The charging point supports token groups. Two or more tokens work as one so that a session can be started with one token and stopped with another (handy when a card and key-fob are given to the EV-driver).

  • UnlockCapable
    The connectors of the charging point have a mechanical lock that the eMSP can request to be unlocked.

  • PlugAndCharge
    The charging point is compliant with ISO-15118 Plug and Charge functionality.

restrictions
list <string>

List of parking restrictions.
Enum:

  • evOnly
    Reserved parking spot for electric vehicles.

  • plugged
    Parking is only allowed while plugged in (charging).

  • disabled
    Reserved parking spot for disabled people with valid ID.

  • customers
    Parking spot for customers/guests only, for example in case of a hotel or shop.

  • motorcycles
    Parking spot only suitable for (electric) motorcycles or scooters.

status
string

Dynamic availability status of charging point.

physicalReference
string

Physical identification of the charging station printed on the station and visible to the driver. One of the parameters that can be used for booking or charging purposes to locate the physical station. No standard format is available.

connectors
array

Array of connector objects.
connector
FieldDescription

id
string

Id of the connector.

type
string

The connector type which is one of the supported types.

ratedPowerKW
double

Rated charging power in kilowatts[KW].

voltageV
integer

Voltage in volts[V].

currentA
integer

Amperage in amperes[A].

currentType
string

The current type of the connector.
Enum:

  • AC1
  • AC3
  • DC
position
FieldDescription

lat
double

Latitude of the result.

lon
double

Longitude of the result.
timeZone
FieldDescription

ianaId
string

ID from the IANA Time Zone Database.
paymentOption
FieldDescription

brands
array

Array of brand objects.
brand
FieldDescription

name
string

Name of the brand. Can be controlled by using 'Accept-Language' optional header. Currently only subscription brands (eMSPs: e-Mobility Service Providers) are available.
openingHours
FieldDescription

mode
string

Requested mode for opening hours.
Value: nextSevenDays

timeRanges
array

List of time ranges for the next 7 days. Array of timeRange.
timeRange
FieldDescription

startTime
object

Start of the timeRange in the form of dateHourMinute.

endTime
object

End of the timeRange in the form of dateHourMinute.
dateHourMinute
FieldDescription

date
string

The date in the calendar year in the local time zone.

hour
integer

Possible values: 0 - 23

minute
integer

Possible values: 0 - 59

Response codes

CodeMeaning & possible causes
200

OK: If any matching charging station was found, the body of the response will contain the data. Otherwise, an empty response will be returned:

Empty response example - JSON
1{
2    "summary": {
3        "numResults": 0,
4        "totalResults": 0
5    }
6}
400

Bad request : One or more parameters were incorrectly specified or are out of range.

403

Forbidden : Possible causes include:

  • Forbidden
  • Not authorized
  • Account inactive
  • Account over queries per second limit
  • Rate limit exceeded
404

Not Found : The requested resource could not be found, the HTTP request method or path is incorrect.

405

Method Not Allowed : The client used an HTTP method other than GET.

406

Media Type Not Acceptable

414

The requested URI is too long

429

Too Many Requests: The API Key is over QPS (Queries per second).

5xx

Server Error: The service was unable to process your request. Contact support to resolve the issue.

Response headers

The following table lists HTTP response headers of particular interest to EV Charging Stations Availability service clients.

HeaderDescription
Access-Control-Allow-Origin

The EV Search service allows cross-origin resource sharing.
Value: * This asterisk signifies access to the TomTom API using the Access-Control-Allow-Origin (ACAO) header in its response, indicating which origin sites are allowed.

Content-Encoding

The EV Search service supports HTTP compression if requested by the client.


Value: gzip

Cache-Control

The Cache-Control general-header field is used to specify directives that must be obeyed by all caching mechanisms along the request/response chain.

  • Supported by HTTP/1.1 clients.
  • May not be supported by HTTP/1.0 clients.

Value: no-cache

Content-Type

Indicates the format of the response as chosen by the client.
Format: type/subtype; charset=utf-8
Value: type/subtype: application/json

Tracking-ID

An identifier for the request. If the Tracking-ID header was specified, it is replicated in the response. Otherwise, it is generated automatically by the service. It is only meant to be used for support and does not involve tracking of you or your users in any form.
Value: An identifier for the request.

Error response

The error response content type depends on the ext parameter.

Error response example - JSON
1{
2  "message": "Missing parameter 'parameterName'",
3  "detailedError": {
4    "code": "MissingParameter",
5    "message": "Missing required parameter 'parameterName'."
6  },
7  "httpStatusCode": "400"
8}
Error response example - XML
1<ErrorEvResponse>
2  <message>Missing parameter 'parameterName'</message>
3  <detailedError>
4    <code>MissingParameter</code>
5    <message>Missing required parameter 'parameterName'.</message>
6  </detailedError>
7</ErrorEvResponse>

Error response fields

Primary fieldsDescription

message
string

A human-readable description of the error.

detailedError
object

Detailed information about the error.
detailedError object

detailedError object
FieldDescription

code
string

One of a server-defined set of error codes.

message
string

A human-readable description of the error code.
It is intended as an aid to developers and is not suitable for exposure to end users.