Developer

EV Search Along the Route

Request Access
Last edit: 2024.12.09
TomTom Orbis Maps

Private Preview Notice

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.

Important notes:

  • This TomTom Orbis Maps EV Search API document collection is restricted to private viewing.
  • This API is powered by the TomTom Orbis Maps.
  • See the TomTom Orbis Maps documentation for more information.

Purpose

The EV Search Search Along the Route endpoint provides information about the EV POIs along a pre-calculated route. By providing optional request parameters, the API allows filtering of the response by connector type, availability status, etc. This feature is particularly useful for long-distance travel where the vehicle may need to be charged one or more times to complete the journey.

If the detour request parameter is set to true, the search response will include detour information (if calculable), which consists of:

  • Detour distance: The difference between the distances of the original route and the recalculated route going through the EV POI (as way-point).
  • Detour time: The additional time required to take the detour.
  • Detour offset: The distance between the start of the original route and the starting point of the detour to the POI.

Please note that with detour, the original route may be altered, and some of its points may be skipped. If the route that passes through the POI is faster than the original one, the detour distance/time value would be negative.

Request data

HTTPS method: POST

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

post
Request URL format
https://{baseURL}/maps/orbis/places/ev/alongRoute?key={Your_API_Key}&status={status}&connector={connector}&accessType={accessType}&restriction={restriction}&capability={capability}&minPowerKW={minPowerKW}&maxPowerKW={maxPowerKW}&limit={limit}&view={view}

URL example

post
Request URL example
https://api.tomtom.com/maps/orbis/places/ev/alongRoute?key={Your_API_Key}&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

post
Request curl command
1curl -XPOST -d '{
2  "route": {
3    "coordinates": [
4      [4.90415,52.36759],[4.90393,52.36774],[4.90386,52.36775],
5      [4.90355,52.36793],[4.90350,52.36796],[4.90344,52.36799],
6      [4.90342,52.36799],[4.90336,52.36800],[4.90332,52.36800],
7      [4.90327,52.36800],[4.90310,52.36796],[4.90299,52.36793]
8    ],
9    "type":"LineString"
10  },
11  "width":1000
12}' 'https://api.tomtom.com/maps/orbis/places/ev/alongRoute?key={Your_API_Key}&status=available,unknown&connector=IEC62196Type2Outlet&accessType=Public&restriction=evOnly&capability=ChargingProfileCapable&minPowerKW=22.2&maxPowerKW=43.2&limit=20&view=Unified'

Request body

The endpoint requires a request body in application/json format which includes the route and width of the route, within which the search will be conducted.

Request bodyDescription

width
integer

Search distance from the the route in meters. The default value is 500 meters.
Default: 500

route
object

The route to search along.
Value: A valid GeoJSON LineString geometry. Please refer to RFC 7946 for details.

route object
FieldDescription

type
string

The type of the GeoJSON object. Current supported value is LineString.

coordinates
array

Array of coordinates in the form of [longitude, latitude]

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

detour
boolean

This parameter enables the enrichment of search results with detour information.
Note: When querying with detour=true, the maximum number of results specified by limit, is capped at 20.
Default: false

limit
integer

Maximum number of search results that will be returned.
Value: An integer value between 1 and 100.
Note: The maximum number of results returned when the detour parameter is set to true is limited to 20.
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.

Required headersDescription
TomTom-Api-Version

The version of the API being called. Currently, only version 1 is supported. Example: 1

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.

Example
1{
2  "paymentBrands": {
3    "preferred" : [
4      {"name":"paymentBrand1"},
5      {"name":"paymentBrand2", "capabilities":["PlugAndCharge"]}
6    ]
7  }
8  "brands": {
9    "preferred" : [
10      {"name":"brand1"},
11      {"name":"brand2"}
12    ]
13  }
14}

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
object

Summary information about the search that was performed.

results
array

Array of result objects.

summary object
FieldDescription

numResults
integer

Number of results in the response.

totalResults
integer

Total number of results found.

result object
FieldDescription

id
string

EV POI Id.

name
string

Name of the POI.

phone
string

Phone number of the POI.

detourDistance
integer

Detour distance in meters.

detourTime
integer

Detour time in seconds.

detourOffset
integer

Detour offset in meters.

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 object
FieldDescription

streetNumber
string

The building number on the street.

streetName
string

The street name.

municipalitySubdivision
string

Sub / Super City.

municipality
string

City / Town.

countrySecondarySubdivision
string

Country.

countryTertiarySubdivision
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 object
FieldDescription

id
string

Charging station Id.

chargingPoints
object

Array of chargingPoint objects.
chargingPoint object
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.

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

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.