openapi: 3.1.0
info:
  title: Open Charge Map Comment 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: Comment
paths:
  /comment:
    post:
      summary: Submit Comment or Checkin
      operationId: post-comment
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                description: ''
                type: object
                properties:
                  status:
                    type: string
                    minLength: 1
                  description:
                    type: string
                    minLength: 1
                required:
                - status
                - description
                x-examples:
                  example-1:
                    status: OK
                    description: OK
              examples:
                example-response:
                  value:
                    status: OK
                    description: OK
        '400':
          description: Bad Request
      description: Submit a user comment or checkin for a specific charging location
      security:
      - UserAuthentication: []
      requestBody:
        content:
          application/json:
            schema:
              description: ''
              type: object
              x-examples:
                example-1:
                  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
              properties:
                chargePointID:
                  type: integer
                  description: This must be a valid POI ID
                commentTypeID:
                  type: integer
                  description: This must be a valid Comment Type ID as per UserCommentTypes found in Core Reference Data. If left as null then General Comment will be used.
                userName:
                  type: string
                  minLength: 1
                  description: This is an optional name to associate with the submission, for authenticated users their profile username is used.
                  maxLength: 100
                comment:
                  type: string
                  minLength: 1
                  maxLength: 4000
                  description: This is an optional comment to describe the charging experience, may include guidance for future users.
                rating:
                  type: integer
                  example: 3
                  description: Optional integer rating between 1 = Worst, 5 = Best.
                relatedURL:
                  type: string
                  minLength: 1
                  description: Optional website URL for related information
                  maxLength: 500
                checkinStatusTypeID:
                  type: integer
                  description: Optional valid CheckStatusTypeID to indicate overall catgeory and success/failure to use equipment e.g. 10 = Charged Successfully.
              required:
              - chargePointID
            examples:
              example-1:
                value:
                  chargePointID: 0
                  commentTypeID: 0
                  userName: string
                  comment: string
                  rating: 3
                  relatedURL: string
                  checkinStatusTypeID: 0
      tags:
      - Comment
components:
  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