EV Charging Stations Availability

Service version: 2
Last edit: 2022.08.15

Purpose

The EV Charging Stations Availability endpoint provides information about the current availability of charging points, grouped by connector type and then power level. The response can be filtered by connector type and a range of charging powers, if provided (using optional request parameters).

Run this endpoint

You can easily run this and other endpoints. Go to the TomTom API Explorer page and follow the directions.

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.

URL format

GET
Request URL
https://{baseURL}/search/{versionNumber}/chargingAvailability.{ext}?key={Your_API_Key}&chargingAvailability={chargingAvailabilityId}&connectorSet={connectorSet}&minPowerKW={minPowerKW}&maxPowerKW={maxPowerKW}

curl command format

GET
Request curl command
curl 'https://{baseURL}/search/{versionNumber}/chargingAvailability.{ext}?key={Your_API_Key}&chargingAvailability={chargingAvailabilityId}&connectorSet={connectorSet}&minPowerKW={minPowerKW}&maxPowerKW={maxPowerKW}'

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.
ext
string
The response format of the API request. The valid response format is JSON or XML.
Value: json or xml
key
string
An API Key valid for the requested service.
Value: Your valid API Key.
chargingAvailability
string
The chargingAvailability ID, previously retrieved from the dataSources section at the bottom of the Search response.
Value: Example: 00112233-4455-6677-8899-aabbccddeeff
Optional parametersDescription
connectorSet
string
A comma-separated list of connector types which could be used to restrict the result to the availability for the specific connector types. See the list of Supported Connector Types.
Value: A comma-separated list of connector types (in any order). When multiple connector types are provided, only connectors that support (at least) one of the connector types from the provided list will be returned.
Examples:
  • connectorSet=IEC62196Type2CableAttached (returns Electric Vehicle Station availability for connectors of type: IEC62196Type2CableAttached)
  • connectorSet=IEC62196Type2Outlet,IEC62196Type2CableAttached (returns Electric Vehicle Station availability for connectors of type: IEC62196Type2CableAttached or EC62196Type2Outlet)
minPowerKW
double
An optional parameter which could be used to restrict the result to the availability for connectors with a specific minimal value of power in kilowatts (closed interval - with that value).
Value: A double value representing the power rate in kilowatts.
Example:
  • minPowerKW=22.2 (returns Electric Vehicle Station availability for connectors with a power rate in the range from 22.2 kW)
This parameter might be used together with [maxPowerKW].
maxPowerKW
double
An optional parameter which could be used to restrict the result to the availability for connectors with a specific maximum value of power in kilowatts (closed interval - with that value).
Value: A double value representing the power rate in kilowatts.
Example:
  • maxPowerKW=43.2 (returns Electric Vehicle Station availability for connectors with a power rate in the range to 43.2 kW)
This parameter might be used together with [minPowerKW].

Request headers

The following table describes HTTP request headers.

Optional headersDescription
Tracking-IDSpecifies 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.

Response data

Response body

If the <ext> parameter value is set to .json, the response will be a JSON object with the following structure:

Response body with the request URL <ext> parameter value set to ".json"
1{
2 "connectors": [
3 {
4 "type": "IEC62196Type2Outlet",
5 "total": 2,
6 "availability": {
7 "current": {
8 "available": 1,
9 "occupied": 1,
10 "reserved": 0,
11 "unknown": 0,
12 "outOfService": 0
13 },
14 "perPowerLevel": [
15 {
16 "powerKW": 22.2,
17 "available": 1,
18 "occupied": 0,
19 "reserved": 0,
20 "unknown": 0,
21 "outOfService": 0
22 },
23 {
24 "powerKW": 50.0,
25 "available": 0,
26 "occupied": 1,
27 "reserved": 0,
28 "unknown": 0,
29 "outOfService": 0
30 }
31 ]
32 }
33 }
34 ],
35 "chargingAvailability": "75502858-a491-36fe-7128-23d400153b86"
36}

If the <ext> parameter value is set to .xml, the response will be an XML format with the following structure:

Response body with the request URL <ext> parameter value set to ".xml"
1<?xml version="1.0" encoding="UTF-8"?>
2<response>
3 <chargingAvailability>75502858-a491-36fe-7128-23d400153b86</chargingAvailability>
4 <connectors>
5 <item>
6 <type>IEC62196Type2Outlet</type>
7 <total>2</total>
8 <availability>
9 <current>
10 <available>1</available>
11 <occupied>1</occupied>
12 <reserved>0</reserved>
13 <unknown>0</unknown>
14 <outOfService>0</outOfService>
15 </current>
16 <perPowerLevel>
17 <power>
18 <powerKW>22.2</powerKW>
19 <available>1</available>
20 <occupied>0</occupied>
21 <reserved>0</reserved>
22 <unknown>0</unknown>
23 <outOfService>0</outOfService>
24 </power>
25 </perPowerLevel>
26 <perPowerLevel>
27 <power>
28 <powerKW>50.0</powerKW>
29 <available>0</available>
30 <occupied>1</occupied>
31 <reserved>0</reserved>
32 <unknown>0</unknown>
33 <outOfService>0</outOfService>
34 </power>
35 </perPowerLevel>
36 </availability>
37 </item>
38 </connectors>
39</response>

Usage and freshness of EV Charging Stations Availability data

Updates are provided regularly, typically within minutes.

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
chargingAvailability
string
The ID of the returned entity.
connectors
array
The charging connector data. array of item objects
item object
FieldDescription
type
string
The charging connector type. See the list of Supported Connector Types.
total
integer
The total number of charging points of the type type in chargingAvailability.
availability
object
The availability data. array of item objects
item object
FieldDescription
current
object
Contains the current availability data.current object
perPowerLevel
object
Contains connector availability per power level. array of perPowerLevel objects
current object
FieldDescription
available
integer
The number of charging points that are available.
occupied
integer
The number of charging points that are occupied.
reserved
integer
The number of charging points that are reserved.
unknown
integer
The number of charging points whose availability data is not known.
outOfService
integer
The number of charging points that are out of service.
perPowerLevel object
FieldDescription
powerKW
double
Power value in kW.
available
integer
The number of charging points that are available with this power.
occupied
integer
The number of charging points that are occupied with this power.
reserved
integer
The number of charging points that are reserved with this power.
unknown
integer
The number of charging points whose availability data is not known with this power.
outOfService
integer
The number of charging points that are out of service with this power.

Response codes

CodeMeaning & possible causes
200OK: If the given chargingAvailability was found, the body of the response will contain the data. Otherwise, the response will contain an empty connectors array in the response body. For example:
Error response example - JSON
1{
2 "connectors":[],
3 "chargingAvailability":"1"
4}
400Bad request: One or more parameters (e.g., chargingAvailability, ext) were incorrectly specified or are out of range.
403Forbidden: Possible causes include:
  • Service requires SSL
  • Not authorized
  • Rate or volume limit exceeded
  • Unknown referer
404Not Found: The requested resource could not be found, but it may be available again in the future.
405Method Not Allowed: The client used an HTTP method other than GET.
429Too Many Requests: The API Key is over QPS (Queries per second).
5xxServer 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-OriginThe 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-EncodingThe Charging Availability service supports HTTP compression if requested by the client.
Value: gzip
Cache-ControlThe 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-TypeIndicates the format of the response as chosen by the client. Format: type/subtype; charset=utf-8
Value: type/subtype: application/json
Tracking-IDAn 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.