The Open Charge Map API

Use of the OCM API is subject to terms and conditions. By using the API you indicate acceptance of these terms.

If you wish to export charging location data into your own systems or applications the most flexible way is to use our API, which provides an export in a variety of formats.

API V3 (documentation last updated Nov 2019)

Service Base URL:

https://api.openchargemap.io/v3/

Uptime last 7 days: last 30 days:

Fair Usage Policy

The basic API is provided as a free service with no warranty or service level agreement. Providing this API to you costs us actual money for server resources and data transfer fees. See funding: https://opencollective.com/openchargemap

If you will be calling the API regularly (from an app or server) you should set your http User-Agent header to a custom value identifying your app (or provide the client=YourAppName url parameter) and you will need to provide your API key as an X-API-Key header (case sensitive) or set the key=YourAPIKey url parameter.

To obtain a free API key Sign In and choose 'my apps' from the profile menu. Do not 'crawl' the API, examples including systematically querying along a grid or along a route, downloading for each country or network operator individually. If you are unsure who to get teh results you need please post a question to our community forum: https://community.openchargemap.org/

Retrieving POI Data

https://api.openchargemap.io/v3/poi/

Example API Calls:

Return charging location information for the US in JSON format, limited to the first 10 results: https://api.openchargemap.io/v3/poi/?output=json&countrycode=US&maxresults=10

The default output contains a lot of information. Here is the same call as above, but with the most compact output (formatting removed, reference data as IDs instead of full objects, null fields skipped): https://api.openchargemap.io/v3/poi/?output=json&countrycode=US&maxresults=100&compact=true&verbose=false

Return KML format results suitable for viewing in google earth/maps etc (UK, max 500 locations): https://api.openchargemap.io/v3/poi/?output=kml&countrycode=GB&maxresults=500

Data returned by the API has mixed licensing and applicable copyright attribution (included in results as "Data Provider"). If you require Open licensed data you currently must filter by opendata=true to return only original OCM data.

Service Parameters:

Parameter Description Default
key Your API Key. Required for apps/services which intend to make repeated calls to the API either as a key parameter in the call URL or as an X-API-Key http header (blank)
client Optional custom identifier for your app or service (if you can't set a custom http User Agent header) (blank)
output json, xml, csv JSON format is recommended as highest fidelity json
maxresults limit on max number of results returned 100
countrycode GB, US etc. Single ISO Country Code. (blank)
countryid exact match on a given numeric country id (comma separated list) (blank)
latitude latitude reference for distance calculation (blank)
longitude longitude reference for distance calculation (blank)
distance return results based on specified distance from specified latitude/longitude (blank)
distanceunit Miles or KM Miles
operatorid exact match on a given EVSE operator id (comma separated list) (blank)
connectiontypeid exact match on a given connection type id (comma separated list) (blank)
levelid exact match on a given charging level (1-3) id (comma separated list) (blank)
minpowerkw minimum output power in kW (this information is not known for many locations) (blank)
usagetypeid exact match on a given usage type id (comma separated list) (blank)
statustypeid exact match on a given status type id (comma separated list) (blank)
dataproviderid exact match on a given data provider id id (comma separated list). Use opendata=true for only OCM provided ("Open") data. (blank)
modifiedsince POIs modified since the given date (UTC) e.g. 2016-09-15T09:30 (blank)
opendata true or false. Set to true to include only Open Data licensed content, false to return only non-open licensed data. By default all available data is returned. You should refer to the license of the original data provider in each case. (blank)
includecomments true or false. Set to true to also include user comments and media items (photos) per charging location. false
verbose true or false. Set to false to get a smaller result set with null items removed. true
compact true or false. Set to true to remove reference data objects from output (just returns IDs for common reference data such as DataProvider etc). false
camelcase true or false. Set to true to get a property names in camelCase format. false
callback specify the name of the JSONP callback (if required), JSON response type only. (blank)
chargepointid exact match on a given POI id (comma separated list). (blank)

Additionally from v3 of the API onwards you can query using a bounding box, polygon or polyline (for a route etc). See here for more info on polyline encoding. :

Parameter Description Default
boundingbox specify top left and bottom right box corners as: (lat,lng),(lat2,lng2) (blank)
polygon Specify an encoded polyline for the polygon shape. Polygon will be automatically closed from the last point to the first point. (blank)
polyline encoded polyline, use with distance param to increase search distance along line. Polyline is expanded into a polygon to cover the search distance. (blank)

Retrieving Core Reference Data

Our core list of lookup values is termed Core Reference Data. This is the data you would require in order to present the user with Dropdown lists etc of possible values for Connection Type etc. This only returns content in JSON format.

https://api.openchargemap.io/v3/referencedata/

Example API Calls:

Return all reference data in JSON format: https://api.openchargemap.io/v3/referencedata/

Optional filter parameters:

countryid exact match on a given numeric country id (comma separated list) (blank)

Add New Comment/Check-In

To submit a new comment or check-in again a specific POI, use the following API endpoint to POST a JSON format comment

https://api.openchargemap.io/v3/?action=comment_submission&format=json

Your JSON submission should be in the body of your POST and contain the following (for example):

                
{
    "ChargePointID": 12345,
    "CommentTypeID": 10,
    "UserName": "A. Nickname",
    "Comment": "This place is awesome, free cake for EV owners!",
    "Rating": 5,
    "RelatedURL": "http://awesomevplace.com",
    "CheckinStatusTypeID": 0
}
            

ChargePointID is the numeric OCM-ID of the POI in location. Values for CommentTypeID and CheckinStatusTypeID can be found in core reference data.

ChargePointID, CommentTypeID and CheckinStatusTypeID are mandatory, all other fields are optional.

Comment Types

Check-In Status Types

Linking to OCM Content and Features

In addition to the API there are a number of standardised URLs which can be used to initiate certain actions, this can be useful to launch from within an app or for hyperlinking. The user can then sign in/register as required and proceed with the required action:

POI related actions

ActionURL
View POI Detailshttps://openchargemap.org/site/poi/details/{OCM-ID}
Add a New POIhttps://openchargemap.org/site/poi/add
Add a Comment/Check-In to an existing POIhttps://openchargemap.org/site/poi/addcomment/{OCM-ID} where {OCM-ID} is the numeric ID of the POI to add a comment to.
Add a Photo to an existing POIhttps://openchargemap.org/site/poi/addmediaitem/{OCM-ID}