Open Charge Map Referencedata API
The Referencedata API from Open Charge Map — 1 operation(s) for referencedata.
OpenAPI Specification
openapi: 3.1.0
info:
title: Open Charge Map Comment Referencedata API
version: '3.1'
termsOfService: https://openchargemap.org/site/about/terms
contact:
name: Contact
url: https://openchargemap.org/site/about
description: "The Open Charge Map API provides access to the worlds largest registry of charging locations as Open Data. You can integrate this API into your own apps or services and export charging location data into your own systems. \n\n**To obtain a free API key Sign In to https://openchargemap.org and choose 'my apps' from the `my profile` menu, then select `Register An Application` to get your API key.**\n\nTo retrieve site (POI) data, see the `/poi` endpoint. To fetch general lookup information such as connector types, network operators etc, use the `/referencedata` endpoint.\n\n**Use of the OCM API is subject to terms and conditions. By using the API you indicate acceptance of these terms.**\n\nIf 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. If you wish to regularly refresh the entire dataset, please clone our data from GitHub. You can also opt to run your own private API mirror.\n\n### Fair Usage Policy\nThe 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.\n\nYou must provide your API key as an `X-API-Key header` (case sensitive) or set the `key=YourAPIKey` url parameter. You should also set your http user-agent to a custom value to help identify your app.\n\n\n\n*Do not repeatedly call the API with duplicate queries. Debounce/throttle your API requests to minimise the work our API has to do. The API administrator (Open Charge Map) reserves the right to ban API callers (including automated banning) if callers make excessive/indescriminate use of the API, at the discretion of the OCM administrator.*\n\nIf you need to make a high volume of queries against the API please host your own API mirror or import the data into your own API.\n\n### Example API Calls\nReturn 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?key=<your key>`\n\nThe 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): \n`https://api.openchargemap.io/v3/poi/?output=json&countrycode=US&maxresults=100&compact=true&verbose=false&key=<your key>`\n\nReturn 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&key=<your key>`\n\nData 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 data marked specifically with Open Data licenses.\n\n### Linking to OCM\nIn addition to using our API you can link directly to specific Open Charge Map URLs in order to perform specific actions, with {OCM-ID} is the numeric ID of the POI to add work with.\n\n* Add a New POI:\t`https://openchargemap.org/site/poi/add`\n* View POI Details: `https://openchargemap.org/site/poi/details/{OCM-ID}`\n* Add a Comment/Check-In to an existing POI: \t`https://openchargemap.org/site/poi/addcomment/{OCM-ID}` \n* Add a Photo to an existing POI:\t`https://openchargemap.org/site/poi/addmediaitem/{OCM-ID}`"
servers:
- url: https://api.openchargemap.io/v3
description: API Base URL
security:
- APIKeyQueryString: []
- APIKeyHeader: []
tags:
- name: Referencedata
paths:
/referencedata:
parameters: []
get:
summary: Core Reference Data
tags:
- Referencedata
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CoreReferenceData'
operationId: get-referencedata
description: "Returns the core reference data used for looking up IDs such as Connection Types, Operators, Countries etc. \n\nThis information is useful for UIs such as editing systems or for fetching results in the lighter non-verbose mode, then hydrating POI results back into complex objects."
parameters:
- schema:
type: array
in: query
description: Optional filter on countryid, exact match on a given numeric country id (comma separated list)
name: countryid
components:
schemas:
CoreReferenceData:
type: object
description: Set of core reference data used for other API results and UI
properties:
ChargerTypes:
type: array
items:
$ref: '#/components/schemas/LevelType'
ConnectionTypes:
type: array
items:
$ref: '#/components/schemas/ConnectionType'
CheckinStatusTypes:
type: array
items:
$ref: '#/components/schemas/CheckinStatusType'
Countries:
type: array
items:
$ref: '#/components/schemas/Country'
CurrentTypes:
type: array
items:
$ref: '#/components/schemas/SupplyType'
DataProviders:
type: array
items:
$ref: '#/components/schemas/DataProvider'
DataTypes: {}
MetadataGroups:
type: string
Operators:
type: array
items:
$ref: '#/components/schemas/OperatorInfo'
StatusTypes:
type: array
items:
$ref: '#/components/schemas/StatusType'
SubmissionStatusTypes:
type: array
items:
$ref: '#/components/schemas/SubmissionStatusType'
UsageTypes:
type: array
items:
$ref: '#/components/schemas/UsageType'
UserCommentTypes:
type: array
items:
$ref: '#/components/schemas/UserCommentType'
x-examples:
example-1:
ChargerTypes:
- ID: 2
description: 'Level 2 : Medium (Over 2kW)'
Comments: Over 2 kW, usually non-domestic socket type
IsFastChargeCapable: false
ConnectionTypes:
- FormalName: IEC 62196-2 Type 2
IsDiscontinued: false
IsObsolete: false
ID: 25
description: Type 2 (Socket Only)
CheckinStatusTypes:
- ID: 0
description: string
IsAutomatedCheckin: true
IsPositive: true
Countries:
- ISOCode: GB
ContinentCode: EU
ID: 1
description: United Kingdom
CurrentTypes:
- Description: Alternating Current - Single Phase
ID: 10
description: AC (Single-Phase)
DataProviders:
- WebsiteURL: https://openchargemap.org
Comments: string
DataProviderStatusType:
IsProviderEnabled: true
ID:
- 1
description:
- Manual Data Entry
IsRestrictedEdit: false
IsOpenDataLicensed: null - true
IsApprovedImport: null - true
License: Licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
DateLastImported: null - '2020-02-04T23:09:00Z'
ID: 1
description: Open Charge Map Contributors
DataTypes: null
MetadataGroups: string
Operators:
- WebsiteURL: http://www.pod-point.com/
Comments: null
PhonePrimaryContact: null
PhoneSecondaryContact: null
IsPrivateIndividual: false
AddressInfo:
ID: 148879
description: Coneygear Centre
AddressLine1: Buttsgrove Way
AddressLine2: null
Town: Huntingdon
StateOrProvince: string
Postcode: PE29 1PE
CountryID: 1
Country:
ISOCode: GB
ContinentCode: EU
ID: 1
description: United Kingdom
Latitude: 52.343197
Longitude: -0.170632
ContactTelephone1: null
ContactTelephone2: null
ContactEmail: string
AccessComments: string
RelatedURL: null
Distance: null
DistanceUnit: 1
BookingURL: string
ContactEmail: enquiries@pod-point.com
FaultReportEmail: enquiries@pod-point.com
IsRestrictedEdit: true
ID: 0
description: POD Point (UK)
StatusTypes:
- IsOperational: true
IsUserSelectable: true
ID: 50
description: Operational
SubmissionStatusTypes:
- IsLive: true
ID: 200
description: Submission Published
UsageTypes:
- IsPayAtLocation: true
IsMembershipRequired: true
IsAccessKeyRequired: true
ID: 0
description: Public - Membership Required
UserCommentTypes:
- ID: 0
Title: string
CheckinStatusType:
type: object
description: Classification for the users comment or experience using a specific charging location.
properties:
ID:
type: integer
Title:
type: string
IsAutomatedCheckin:
type: boolean
description: If true, checkin or comment was provided by an automated system.
IsPositive:
type: boolean
description: If true, this type of checkin/comment is considered positive.
required:
- ID
- IsAutomatedCheckin
Country:
type: object
description: Country details
properties:
ID:
type: integer
description: The Id Schema
default: 0
example: 1
ISOCode:
type: string
description: The Isocode Schema
default: ''
example: GB
pattern: ^(.*)$
ContinentCode:
type: string
description: The Continentcode Schema
default: ''
example: EU
pattern: ^(.*)$
Title:
type: string
description: The Title Schema
default: ''
example: United Kingdom
pattern: ^(.*)$
required:
- ID
- ISOCode
- ContinentCode
OperatorInfo:
type: object
description: An Operator is the public organisation which controls a network of charging points.
properties:
WebsiteURL:
type: string
description: Website for more information about this network
example: http://www.pod-point.com/
pattern: ^(.*)$
Comments:
type: string
example: null
PhonePrimaryContact:
type: string
description: Primary contact number for network users
default: null
PhoneSecondaryContact:
type: string
description: Secondary contact number
default: null
pattern: ^(.*)$
IsPrivateIndividual:
type: boolean
description: If true, this operator represents a private individual
deprecated: true
default: false
example: false
AddressInfo:
$ref: '#/components/schemas/AddressInfo'
BookingURL:
type: string
ContactEmail:
type: string
default: ''
example: enquiries@pod-point.com
pattern: ^(.*)$
FaultReportEmail:
type: string
description: Used to send automated notification to network operator if a user submits a fault report comment/check-in
example: enquiries@pod-point.com
pattern: ^(.*)$
IsRestrictedEdit:
type: boolean
description: If true, this network restricts community edits for OCM data
ID:
type: integer
description: Id
Title:
type: string
description: Title
example: POD Point (UK)
pattern: ^(.*)$
required:
- ID
UsageType:
type: object
description: The Usage Type of a site indicates the general restrictions on usage.
properties:
IsPayAtLocation:
type: boolean
description: If true, usage requires paying at location
IsMembershipRequired:
type: boolean
description: If true, this usage type requires registration or membership with a service.
IsAccessKeyRequired:
type: boolean
description: If true this usage required a physical access key
deprecated: true
ID:
type: integer
Title:
type: string
example: Public - Membership Required
pattern: ^(.*)$
required:
- IsPayAtLocation
- IsMembershipRequired
- IsAccessKeyRequired
- ID
StatusType:
type: object
description: The Status Type of a site or equipment item indicates whether it is generally operational.
properties:
IsOperational:
type: boolean
default: false
example: true
IsUserSelectable:
type: boolean
default: false
example: true
ID:
type: integer
example: 50
Title:
type: string
example: Operational
required:
- IsOperational
- IsUserSelectable
- ID
LevelType:
type: object
description: A general category for equipment power capability. Deprecated for general use. Currently computed automatically based on equipment power.
properties:
ID:
type: integer
example: 2
Title:
type: string
example: 'Level 2 : Medium (Over 2kW)'
Comments:
type: string
example: Over 2 kW, usually non-domestic socket type
IsFastChargeCapable:
type: boolean
description: If true, this level is considered 'fast' charging, relative to other levels.
required:
- ID
- Comments
- IsFastChargeCapable
ConnectionType:
type: object
description: The type of end-user connection an EVSE supports.
properties:
FormalName:
type: string
description: Formal (standard) name for this connection type
default: ''
example: IEC 62196-2 Type 2
pattern: ^(.*)$
IsDiscontinued:
type: boolean
description: If true, this is an discontinued but used connection type
default: false
example: false
IsObsolete:
type: boolean
description: If true, this is an obsolete connection type and is unlikely top be present in modern infrastructure
default: false
example: false
ID:
type: integer
example: 25
Title:
type: string
example: Type 2 (Socket Only)
DataProvider:
type: object
description: A Data Provider is the controller of the source data set used to construct the details for this POI. Data has been transformed and interpreted from it's original form. Each Data Provider provides data either by an explicit license or agreement.
properties:
WebsiteURL:
type: string
description: Website URL for this data provider
example: https://openchargemap.org
pattern: ^(.*)$
Comments:
type: string
description: General public comments with information about this Data Provider.
DataProviderStatusType:
type: object
description: Status object describing whether this data provider is currently enabled and the type of source (manual entry, imported etc)
properties:
IsProviderEnabled:
type: boolean
description: If false, results from this data provider are not currently enabled
default: false
example: true
ID:
type: integer
description: The reference ID for this provider status type
default: 0
example:
- 1
description:
type: string
description: The Title of this status type
example:
- Manual Data Entry
pattern: ^(.*)$
required:
- IsProviderEnabled
- ID
IsRestrictedEdit:
type: boolean
description: Currently not implemented. Indicates a potential editing restriction.
default: false
example: false
IsOpenDataLicensed:
type: boolean
description: If true, data provider uses an Open Data license
example: true
IsApprovedImport:
type: boolean
description: If false, data may not be imported for this provider.
example: true
License:
type: string
description: Summary of the licensing which applies for this Data Provider. Each Data Provider has one specific license or agreement. Usage of the data requires acceptance of the given license.
example: Licensed under Creative Commons Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)
pattern: ^(.*)$
DateLastImported:
type: string
format: date-time
description: Date and time (UTC) the last import was performed for this data provider (if an import).
example: '2020-02-04T23:09:00Z'
ID:
type: integer
description: The reference ID for this Data Provider
example: 1
Title:
type: string
description: The Title for this Data Provider
example: Open Charge Map Contributors
pattern: ^(.*)$
required:
- IsRestrictedEdit
- ID
SupplyType:
type: object
description: Indicates the EVSE power supply type e.g. DC (Direct Current), AC (Single Phase), AC (3 Phase).
properties:
ID:
type: integer
example: 10
Title:
type: string
example: AC (Single-Phase)
required:
- ID
SubmissionStatusType:
type: object
description: Submission Status object, detailing the POI listing status
properties:
ID:
type: integer
description: Submission Status Type reference ID
default: 0
example: 200
Title:
type: string
IsLive:
type: boolean
description: If true, POI listing is live (not draft or de-listed)
default: false
required:
- ID
- IsLive
AddressInfo:
type: object
description: Geographic position for site and (nearest) address component information.
properties:
ID:
type: integer
description: ID
default: 0
example: 148879
AddressLine1:
type: string
description: First line of nearby street address
default: ''
example: Buttsgrove Way
pattern: ^(.*)$
AddressLine2:
type: string
description: Second line of nearby street address
default: null
Town:
type: string
description: Town or City
example: Huntingdon
pattern: ^(.*)$
StateOrProvince:
type: string
description: State or Province
Postcode:
type: string
description: Postal code or Zipcode
example: PE29 1PE
pattern: ^(.*)$
CountryID:
type: integer
description: The reference ID for the Country
example: 1
Country:
$ref: '#/components/schemas/Country'
Latitude:
type: number
description: Site latitude coordinate in decimal degrees
default: 0
example: 52.343197
Longitude:
type: number
description: Site longitude coordinate in decimal degrees
default: 0
example: -0.170632
ContactTelephone1:
type: string
description: Primary contact number
default: null
ContactTelephone2:
type: string
description: Secondary contact number
default: null
ContactEmail:
type: string
description: Primary contact email
AccessComments:
type: string
description: Guidance for users to use or find the equipment
RelatedURL:
type: string
description: Optional website for more information
default: null
Distance:
type: number
description: Distance from search location, if search is around a point
default: null
DistanceUnit:
type: integer
description: Unit used for distance, 1= Miles, 2 = KM
default: 1
Title:
type: string
description: General title for this location to aid user
required:
- ID
- CountryID
- Latitude
- Longitude
UserCommentType:
title: UserCommentType
type: object
properties:
ID:
type: integer
Title:
type: string
description: Category for a user comment, e.g. General Comment, Fault Report (Notice To Users And Operator)
securitySchemes:
APIKeyQueryString:
name: key
type: apiKey
in: query
description: API Key supplied as query string parameter
APIKeyHeader:
name: X-API-Key
type: apiKey
in: header
UserAuthentication:
type: http
scheme: bearer