Developer

EV Search by Id

Request Access
Last edit: 2024.11.18
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 Request Access 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 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}/maps/orbis/places/ev/id?key={Your_API_Key}&id={poiId}

URL example

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

curl command example

get
Request curl command example
curl 'https://api.tomtom.com/maps/orbis/places/ev/id?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 parametersDescription

baseURL
string

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

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.

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 one of the following values as the response format of an API request:

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

municipalitySubdivision
string

Sub / Super City.

municipality
string

City / Town.

countrySecondary Subdivision
string

Country.

countryTertiary Subdivision
string

Named area.

country Subdivision
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.

country SubdivisionCode
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.

country SubdivisionName
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
string (list)

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
string (list)

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

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