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 V2 (documentation last updated March 2017) - Please join the discussion forum to discuss development.

Service Base URL:

https://api.openchargemap.io/v2/

Retrieving POI Data

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

Example API Calls:

Return charging location information for the US in JSON format, limited to the first 10 results: https://api.openchargemap.io/v2/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/v2/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/v2/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
output json, xml, kml JSON format is recommended as highest fidelity json
maxresults limit on max number of results returned 100
countrycode GB, US etc ISO Country Code. (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)
countryid exact match on a given country 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)

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/v2/referencedata/

Example API Calls:

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

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/v2/?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}