Developer

EV Search by Id

Request Access
Service version: 2
Last edit: 2024.05.28
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 by Id endpoint provides detailed information about a specific charging station, such as its location, availability status, and the attached connectors.

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}/evbyid?key={Your_API_Key}&id={poiId}

URL example

get
Request URL example
https://api.tomtom.com/search/2/evbyid?key={Your_API_Key}&id=0b903425-3f5a-4072-9d5d-070f6f0647b3

curl command example

get
Request curl command example
curl 'https://api.tomtom.com/search/2/evbyid?key={Your_API_Key}&id=0b903425-3f5a-4072-9d5d-070f6f0647b3'

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 parameters

Description

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.

id


string

Id of the EV POI to return.

Request headers

The following table describes HTTP request headers.

Optional headers

Description

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 default language is used (English).

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": 1,
4        "totalResults": 1
5    },
6    "results": [
7        {
8            "id": "0b903425-3f5a-4072-9d5d-070f6f0647b3",
9            "name": "Mega M d.o.o.",
10            "position": {
11                "lat": 44.810263,
12                "lon": 20.4354
13            },
14            "chargingStations": [
15                {
16                    "id": "RS*ORI*E1161",
17                    "chargingPoints": [
18                        {
19                            "capabilities": [
20                                "RemoteStartStopCapable"
21                            ],
22                            "connectors": [
23                                {
24                                    "id": "1",
25                                    "currentA": 32,
26                                    "currentType": "AC3",
27                                    "ratedPowerKW": 22.0,
28                                    "type": "IEC62196Type2Outlet",
29                                    "voltageV": 400
30                                }
31                            ],
32                            "evseId": "RS*ORI*E1167",
33                            "status": "Available"
34                        },
35                        {
36                            "capabilities": [
37                                "RemoteStartStopCapable"
38                            ],
39                            "connectors": [
40                                {
41                                    "id": "1",
42                                    "currentType": "DC",
43                                    "ratedPowerKW": 50.0,
44                                    "type": "Chademo"
45                                }
46                            ],
47                            "evseId": "RS*ORI*E1166",
48                            "status": "Occupied"
49                        },
50                        {
51                            "capabilities": [
52                                "RemoteStartStopCapable"
53                            ],
54                            "connectors": [
55                                {
56                                    "id": "1",
57                                    "currentA": 16,
58                                    "currentType": "AC3",
59                                    "ratedPowerKW": 11.0,
60                                    "type": "IEC62196Type2Outlet",
61                                    "voltageV": 400
62                                }
63                            ],
64                            "evseId": "RS*ORI*E1163",
65                            "status": "Unknown"
66                        },
67                        {
68                            "capabilities": [
69                                "RemoteStartStopCapable"
70                            ],
71                            "connectors": [
72                                {
73                                    "id": "1",
74                                    "currentA": 16,
75                                    "currentType": "AC3",
76                                    "ratedPowerKW": 11.0,
77                                    "type": "IEC62196Type2Outlet",
78                                    "voltageV": 400
79                                }
80                            ],
81                            "evseId": "RS*ORI*E1162",
82                            "status": "Available"
83                        },
84                        {
85                            "capabilities": [
86                                "RemoteStartStopCapable"
87                            ],
88                            "connectors": [
89                                {
90                                    "id": "1",
91                                    "currentType": "DC",
92                                    "ratedPowerKW": 75.0,
93                                    "type": "IEC62196Type2CCS"
94                                }
95                            ],
96                            "evseId": "RS*ORI*E1165",
97                            "status": "OutOfService"
98                        },
99                        {
100                            "capabilities": [
101                                "RemoteStartStopCapable"
102                            ],
103                            "connectors": [
104                                {
105                                    "id": "1",
106                                    "currentA": 16,
107                                    "currentType": "AC3",
108                                    "ratedPowerKW": 11.0,
109                                    "type": "IEC62196Type2Outlet",
110                                    "voltageV": 400
111                                }
112                            ],
113                            "evseId": "RS*ORI*E1164",
114                            "status": "Available"
115                        }
116                    ]
117                }
118            ],
119            "address": {
120                "countryCode": "RS",
121                "countryCodeISO3": "SRB",
122                "country": "Serbia",
123                "countrySubdivision": "Central Serbia",
124                "countrySubdivisionName": "Central Serbia",
125                "countrySecondarySubdivision": "Belgrade City",
126                "freeformAddress": "Улица Владимира Поповића 8, 11070 Belgrade",
127                "localName": "Belgrade",
128                "municipality": "Belgrade",
129                "municipalitySubdivision": "Нови Београд",
130                "postalCode": "11070",
131                "streetNumber": "8",
132                "streetName": "Улица Владимира Поповића"
133            },
134            "phone": "+386 3 777 77 77",
135            "openingHours": {
136                "mode": "nextSevenDays",
137                "timeRanges": [
138                    {
139                        "startTime": {
140                            "date": "2024-05-02",
141                            "hour": 0,
142                            "minute": 0
143                        },
144                        "endTime": {
145                            "date": "2024-05-09",
146                            "hour": 0,
147                            "minute": 0
148                        }
149                    }
150                ]
151            },
152            "timeZone": {
153                "ianaId": "Europe/Belgrade"
154            },
155            "paymentOptions": [
156                {
157                    "brands": [
158                        {
159                            "name": "Shell Recharge"
160                        },
161                        {
162                            "name": "Eneco"
163                        }
164                    ]
165                }
166            ],
167            "accessType": "Public"
168        }
169    ]
170}

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>1</numResults>
4        <totalResults>1</totalResults>
5    </summary>
6    <results>
7        <item>
8            <id>0b903425-3f5a-4072-9d5d-070f6f0647b3</id>
9            <name>Mega M d.o.o.</name>
10            <position>
11                <lat>44.810263</lat>
12                <lon>20.4354</lon>
13            </position>
14            <address>
15                <countryCode>RS</countryCode>
16                <countryCodeISO3>SRB</countryCodeISO3>
17                <country>Serbia</country>
18                <countrySubdivision>Central Serbia</countrySubdivision>
19                <countrySubdivisionName>Central Serbia</countrySubdivisionName>
20                <countrySecondarySubdivision>Belgrade City</countrySecondarySubdivision>
21                <freeformAddress>Улица Владимира Поповића 8, 11070 Belgrade</freeformAddress>
22                <localName>Belgrade</localName>
23                <municipality>Belgrade</municipality>
24                <municipalitySubdivision>Нови Београд</municipalitySubdivision>
25                <postalCode>11070</postalCode>
26                <streetNumber>8</streetNumber>
27                <streetName>Улица Владимира Поповића</streetName>
28            </address>
29            <phone>+386 3 777 77 77</phone>
30            <openingHours>
31                <mode>nextSevenDays</mode>
32                <timeRanges>
33                    <timeRange>
34                        <startTime>
35                            <date>2024-05-02</date>
36                            <hour>0</hour>
37                            <minute>0</minute>
38                        </startTime>
39                        <endTime>
40                            <date>2024-05-09</date>
41                            <hour>0</hour>
42                            <minute>0</minute>
43                        </endTime>
44                    </timeRange>
45                </timeRanges>
46            </openingHours>
47            <timeZone>
48                <ianaId>Europe/Belgrade</ianaId>
49            </timeZone>
50            <accessType>Public</accessType>
51            <chargingStations>
52                <chargingStation>
53                    <id>RS*ORI*E1161</id>
54                    <chargingPoints>
55                        <chargingPoint>
56                            <evseId>RS*ORI*E1167</evseId>
57                            <status>Available</status>
58                            <capabilities>
59                                <capability>RemoteStartStopCapable</capability>
60                            </capabilities>
61                            <connectors>
62                                <connector>
63                                    <id>1</id>
64                                    <currentA>32</currentA>
65                                    <currentType>AC3</currentType>
66                                    <ratedPowerKW>22.0</ratedPowerKW>
67                                    <type>IEC62196Type2Outlet</type>
68                                    <voltageV>400</voltageV>
69                                </connector>
70                            </connectors>
71                        </chargingPoint>
72                        <chargingPoint>
73                            <evseId>RS*ORI*E1166</evseId>
74                            <status>Occupied</status>
75                            <capabilities>
76                                <capability>RemoteStartStopCapable</capability>
77                            </capabilities>
78                            <connectors>
79                                <connector>
80                                    <id>1</id>
81                                    <currentType>DC</currentType>
82                                    <ratedPowerKW>50.0</ratedPowerKW>
83                                    <type>Chademo</type>
84                                </connector>
85                            </connectors>
86                        </chargingPoint>
87                        <chargingPoint>
88                            <evseId>RS*ORI*E1163</evseId>
89                            <status>Unknown</status>
90                            <capabilities>
91                                <capability>RemoteStartStopCapable</capability>
92                            </capabilities>
93                            <connectors>
94                                <connector>
95                                    <id>1</id>
96                                    <currentA>16</currentA>
97                                    <currentType>AC3</currentType>
98                                    <ratedPowerKW>11.0</ratedPowerKW>
99                                    <type>IEC62196Type2Outlet</type>
100                                    <voltageV>400</voltageV>
101                                </connector>
102                            </connectors>
103                        </chargingPoint>
104                        <chargingPoint>
105                            <evseId>RS*ORI*E1162</evseId>
106                            <status>Available</status>
107                            <capabilities>
108                                <capability>RemoteStartStopCapable</capability>
109                            </capabilities>
110                            <connectors>
111                                <connector>
112                                    <id>1</id>
113                                    <currentA>16</currentA>
114                                    <currentType>AC3</currentType>
115                                    <ratedPowerKW>11.0</ratedPowerKW>
116                                    <type>IEC62196Type2Outlet</type>
117                                    <voltageV>400</voltageV>
118                                </connector>
119                            </connectors>
120                        </chargingPoint>
121                        <chargingPoint>
122                            <evseId>RS*ORI*E1165</evseId>
123                            <status>OutOfService</status>
124                            <capabilities>
125                                <capability>RemoteStartStopCapable</capability>
126                            </capabilities>
127                            <connectors>
128                                <connector>
129                                    <id>1</id>
130                                    <currentType>DC</currentType>
131                                    <ratedPowerKW>75.0</ratedPowerKW>
132                                    <type>IEC62196Type2CCS</type>
133                                </connector>
134                            </connectors>
135                        </chargingPoint>
136                        <chargingPoint>
137                            <evseId>RS*ORI*E1164</evseId>
138                            <status>Available</status>
139                            <capabilities>
140                                <capability>RemoteStartStopCapable</capability>
141                            </capabilities>
142                            <connectors>
143                                <connector>
144                                    <id>1</id>
145                                    <currentA>16</currentA>
146                                    <currentType>AC3</currentType>
147                                    <ratedPowerKW>11.0</ratedPowerKW>
148                                    <type>IEC62196Type2Outlet</type>
149                                    <voltageV>400</voltageV>
150                                </connector>
151                            </connectors>
152                        </chargingPoint>
153                    </chargingPoints>
154                </chargingStation>
155            </chargingStations>
156            <paymentOptions>
157                <paymentOption>
158                    <brands>
159                        <brand>
160                            <name>Shell Recharge</name>
161                        </brand>
162                        <brand>
163                            <name>Eneco</name>
164                        </brand>
165                    </brands>
166                </paymentOption>
167            </paymentOptions>
168        </item>
169    </results>
170</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

Field

Description

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.

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

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.

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

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

Code

Meaning & 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 Search API service clients.

Header

Description

Access-Control-Allow-Origin

The Charging Availability 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 Charging Availability 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 fields

Description

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.