Sorry, you need to enable JavaScript to visit this website.

EV Charging Stations Availability

 

Service version: 2
Last edit: 2020.10.14

On this page

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

Request data

HTTPS method: GET

URL format

For ease of viewing and identification:

  • Constants and parameters enclosed in angle brackets (< >) must be replaced with their values.
  • See the following Request parameters section with the Required and Optional parameters tables for these values.
https://<baseURL>/search/<versionNumber>/chargingAvailability.<ext>?key=<Your_API_Key>&chargingAvailability=<chargingAvailabilityId>[&connectorSet=<connectorSet>][&minPowerKW=<minPowerKW>][&maxPowerKW=<maxPowerKW>]

curl command format

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.
  • If there is a default value that will be assumed when an optional parameter is not used, it is shown in the table.
Required parameters
Parameter 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.
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 a Search Request.
Value: Example: 00112233-4455-6677-8899-aabbccddeeff
Optional parameters
Parameter Description
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: 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 IEC62196Type2Outlet)
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].

▲ Return to top

HTTP Request headers

The following table describes HTTP Request headers.

Optional headers
Header Description
Tracking-ID
string
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.

▲ Return to top

Response data

Response body

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

{
  "connectors": [
    {
      "type": "IEC62196Type2Outlet",
      "total": 2,
      "availability": {
        "current": {
          "available": 1,
          "occupied": 1,
          "reserved": 0,
          "unknown": 0,
          "outOfService": 0
        },
        "perPowerLevel": [
          {
            "powerKW": 22.2,
            "available": 1,
            "occupied": 0,
            "reserved": 0,
            "unknown": 0,
            "outOfService": 0
          },
          {
            "powerKW": 50.0,
            "available": 0,
            "occupied": 1,
            "reserved": 0,
            "unknown": 0,
            "outOfService": 0
          }
        ]
      }
    }
  ],
  "chargingAvailability": "75502858-a491-36fe-7128-23d400153b86"
}

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

<?xml version="1.0" encoding="UTF-8"?>
<response>
   <chargingAvailability>75502858-a491-36fe-7128-23d400153b86</chargingAvailability>
   <connectors>
      <item>
         <type>IEC62196Type2Outlet</type>
         <total>2</total>
         <availability>
            <current>
               <available>1</available>
               <occupied>1</occupied>
               <reserved>0</reserved>
               <unknown>0</unknown>
               <outOfService>0</outOfService>
            </current>
            <perPowerLevel>
               <power>
                  <powerKW>22.2</powerKW>
                  <available>1</available>
                  <occupied>0</occupied>
                  <reserved>0</reserved>
                  <unknown>0</unknown>
                  <outOfService>0</outOfService>
               </power>
            </perPowerLevel>
            <perPowerLevel>
               <power>
                  <powerKW>50.0</powerKW>
                  <available>0</available>
                  <occupied>1</occupied>
                  <reserved>0</reserved>
                  <unknown>0</unknown>
                  <outOfService>0</outOfService>
               </power>
            </perPowerLevel>
         </availability>
      </item>
   </connectors>
</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.

Response
Field Description
chargingAvailability
string
The ID of the returned entity.
connectors[]
array
The charging connector data. array of item{} objects
item{} object
Field Description
type
string
The charging connector type. 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
Field Description
current
object
Contains the current availability data. current{} object
perPowerLevel
object
Contains connector availability per power level. array of perPowerLevel{} objects
current{} object
Field Description
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
Field Description
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.

HTTP Response codes

Code Meaning and Possible Causes
200 OK: 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:
{
  "connectors":[],
  "chargingAvailability":"1"
}
400 Bad request: One or more parameters (e.g., chargingAvailability, ext) were incorrectly specified or are out of range.
403 Forbidden: Possible causes include:
  • Service requires SSL
  • Not authorized
  • Rate or volume limit exceeded
  • Unknown referer
404 Not Found: The requested resource could not be found, but it may be available again in the future.
405 Method Not Allowed: The client used a HTTP method other than GET.
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.

▲ Return to top

Response headers

The following table lists HTTP Response headers of particular interest to EV Charging Stations Availability 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.

▲ Return to top

Error Response

The error Response content type depends on the ext parameter.

Error Response example (JSON)

{
  "message":"Missing parameter 'parameterName'",
  "detailedError":{
    "code":"MissingParameter",
    "message":"Missing required parameter 'parameterName'.",
    },
  "httpStatusCode":"400"
}

Error Response example (XML)


<ErrorEvResponse>
  <message>Missing parameter 'parameterName'</message>
  <detailedError>
    <code>MissingParameter</code>
    <message>Missing required parameter 'parameterName'.</message>
  </detailedError>
</ErrorEvResponse>

▲ Return to top

Error Response fields

Primary fields
Field Description
message
string
A human-readable description of the error.
detailedError
object
Detailed information about the error.
detailedError{} object
detailedError{} object
Field Description
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.

▲ Return to top