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