openapi: 3.2.0
info:
  title: Open Charge Map 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.
servers:
- url: https://api.openchargemap.io/v3
  description: API Base URL
security:
- APIKeyQueryString: []
- APIKeyHeader: []
tags:
- name: Reference Data
paths:
  /referencedata:
    parameters: []
    get:
      summary: Core Reference Data
      tags:
      - Reference Data
      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.


        This 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:
    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
    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
    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
    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
    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
    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)
    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
    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)
    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
    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
  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