EV Search Nearby
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 Nearby endpoint provides information about the nearest charging stations based on a given coordinate system and radius. If provided (using optional request parameters), the response can be filtered by connector type, availability status, etc.
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
https://{baseURL}/search/{versionNumber}/evsearch?key={Your_API_Key}&lat={latitude}&lon={longitude}&radius={radius}&status={status}&connector={connector}&accessType={accessType}&restriction={restriction}&capability={capability}&minPowerKW={minPowerKW}&maxPowerKW={maxPowerKW}&limit={limit}
URL example
https://api.tomtom.com/search/2/evsearch?key={Your_API_Key}&lat=52.36&lon=4.89&radius=1000&status=Available&connector=IEC62196Type2Outlet&accessType=Public,Authorized&restriction=evOnly&capability=ChargingProfileCapable&minPowerKW=22.2&maxPowerKW=43.2&limit=20
Request curl command example
curl 'https://api.tomtom.com/search/2/evsearch?key={Your_API_Key}&lat=52.36&lon=4.89&radius=1000&status=available,unknown&connector=IEC62196Type2Outlet&accessType=Public&restriction=evOnly&capability=ChargingProfileCapable&minPowerKW=22.2&maxPowerKW=43.2&limit=20'
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 |
---|---|
string | The base URL for calling the API. Value: |
string | The service version. Value: The current value is |
string | An API Key valid for the requested service. Value: Your valid |
double | Latitude of the location to search for. Value: A double value between -90 and 90.
Example: |
double | Longitude of the location to search for. Value: A double value between -180 and 180.
Example: |
integer | Radius in meters to search within. Value: An integer value between 1 and 100000 representing the radius in meters. Example: |
Optional parameters | Description |
---|---|
integer | Maximum number of search results that will be returned. Value: An integer value between 1 and 100. Default: |
string | The comma separated status values of charging points to be filtered. Enum:
|
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. Example: |
string | The comma separated access types, which could be used to restrict the results to EV POIs with specific access types. Enum:
|
string | The comma separated restrictions, which could be used to restrict the results to EV POIs with specific restrictions. Enum:
|
string | The comma separated capabilities, which could be used to restrict the results to EV POIs with specific capabilities. Enum:
|
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). Example: This parameter might be used together with |
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: This parameter might be used together with |
Request headers
The following table describes HTTP request headers.
Optional headers | Description |
---|---|
Tracking-ID | Specifies an identifier for the request.
Value: An |
Accept | Specifies the response format of the API request, one of the following values:
|
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. |
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:
1{2 "summary": {3 "numResults": 2,4 "totalResults": 1915 },6 "results": [7 {8 "id": "939d44d0-cf00-42e9-b9f3-bf4d2de125b5",9 "name": "TotalEnergies",10 "position": {11 "lat": 52.364941,12 "lon": 4.893598613 },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": 23032 }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": 23052 }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": 083 },84 "endTime": {85 "date": "2024-05-09",86 "hour": 0,87 "minute": 088 }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.8922383127 },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": 230145 }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": 230164 }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": 0195 },196 "endTime": {197 "date": "2024-05-09",198 "hour": 0,199 "minute": 0200 }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:
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 | |
---|---|
Field | Description |
string | Summary information about the search that was performed. |
array | Array of result objects. |
summary | |
Field | Description |
integer | Number of results in the response. |
integer | Total number of results found. |
result | |
Field | Description |
string | EV POI Id. |
string | Name of the POI. |
string | Phone number of the POI. |
object | Structured address for the result. |
array | Array of chargingStation objects. |
object | Opening hours for the POI. |
object | Time zone for the POI. |
array | Array of brand objects. |
array | Array of paymentOption objects. |
string | Access type of the EV POI station.
|
object | Position of the EV POI. |
Address | |
Field | Description |
string | The building number on the street. |
string | The street name. |
string | Sub / Super City. |
string | City / Town. |
string | Country. |
string | Named area. |
string | State or Province. For regions like USA, CAN, & GB, this will be the province code, and for the rest the subdivision name. |
string | State or Province name. |
string | State or Province code. Only for regions like USA, CAN, GB. |
string | Postal code / Zip code. |
string | Extended postal code (availability dependent on region). |
string | The two-letter code of the country. |
string | The country name. |
string | ISO alpha-3 country code. |
string | An address line formatted according to the formatting rules of the result's country of origin. |
string | The full name of the first level of a country's administrative hierarchy.
|
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 | |
Field | Description |
string | Charging station Id. |
object | Array of chargingPoint objects. |
chargingPoint | |
Field | Description |
string | Charging point Id with definition. |
List<String> | List of capabilities.
|
List<String> | List of parking restrictions.
|
string | Dynamic availability status of charging point. |
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. |
array | Array of connector objects. |
connector | |
Field | Description |
string | Id of the connector. |
string | The connector type which is one of the supported types. |
double | Rated charging power in kilowatts[KW]. |
integer | Voltage in volts[V]. |
integer | Amperage in amperes[A]. |
string | The current type of the connector. Enum:
|
position | |
Field | Description |
double | Latitude of the result. |
double | Longitude of the result. |
timeZone | |
Field | Description |
string | ID from the IANA Time Zone Database. |
paymentOption | |
Field | Description |
array | Array of brand objects. |
brand | |
Field | Description |
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 | |
Field | Description |
string | Requested mode for opening hours. |
array | List of time ranges for the next 7 days. Array of timeRange. |
timeRange | |
Field | Description |
object | Start of the timeRange in the form of dateHourMinute. |
object | End of the timeRange in the form of dateHourMinute. |
dateHourMinute | |
Field | Description |
string | The date in the calendar year in the local time zone. |
integer | Possible values: 0 - 23 |
integer | Possible values: 0 - 59 |
Response codes
Code | Meaning & possible causes |
---|---|
| 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
|
| Bad request : One or more parameters were incorrectly specified or are out of range. |
| Forbidden : Possible causes include:
|
| Not Found : The requested resource could not be found, the HTTP request method or path is incorrect. |
| Method Not Allowed : The client used an HTTP method other than |
| Media Type Not Acceptable |
| The requested URI is too long |
| Too Many Requests : The API Key is over QPS (Queries per second). |
| 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.
Header | Description |
---|---|
The Charging Availability service allows cross-origin resource sharing. Value: | |
The Charging Availability service supports HTTP compression if requested by the client. Value: | |
The Cache-Control general-header field is used to specify directives that must be obeyed by all caching mechanisms along the request/response chain.
Value: | |
Indicates the format of the response as chosen by the client. Format:
Value: | |
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 |
Error response
The error response content type depends on the ext
parameter.
1{2 "message": "Missing parameter 'parameterName'",3 "detailedError": {4 "code": "MissingParameter",5 "message": "Missing required parameter 'parameterName'."6 },7 "httpStatusCode": "400"8}
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 |
---|---|
string | A human-readable description of the error. |
object | Detailed information about the error. detailedError object |
detailedError object | |
Field | Description |
string | One of a server-defined set of error codes. |
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. |