swagger: "2.0"
schemes:
  - https
host: api.opencagedata.com
basePath: /geocode
info:
  contact:
    name: OpenCage GmbH
    url: https://opencagedata.com/contact
  description: Worldwide forward and reverse geocoding
  termsOfService: https://opencagedata.com/terms
  title: OpenCage Geocoder
  version: "1"
  x-apisguru-categories:
    - location
  x-logo:
    url: https://opencagedata.com/opencagelogo-green.png
  x-origin:
    - format: swagger
      url: https://opencagedata.com/swagger.yaml
      version: "2.0"
    - format: swagger
      url: https://geocoder.opencagedata.com/swagger.yaml
      version: "2.0"
  x-providerName: opencagedata.com
externalDocs:
  description: OpenCage Geocoder Website
  url: https://opencagedata.com/api
consumes:
  - text/plain
produces:
  - application/json
  - application/xml
  - text/html
paths:
  "/v{version}/{format}":
    get:
      description: geocode a query
      parameters:
        - description: API version.
          in: path
          name: version
          required: true
          type: integer
        - description: format of the response. One of 'json', 'xml' or 'map'.
          in: path
          name: format
          required: true
          type: string
        - description: string or lat,lng to be geocoded.
          in: query
          name: q
          required: true
          type: string
        - description: an application key.
          in: query
          name: key
          required: true
          type: string
        - description: when true we attempt to abbreviate the formatted field of results.
          in: query
          name: abbrv
          type: boolean
        - description: when true we include only address details in the formatted field of results.
          in: query
          name: address_only
          type: boolean
        - description: if true the request is included in the response.
          in: query
          name: add_request
          type: boolean
        - description: four coordinate points forming the south-west and north-east corners of a bounding box (min long, min lat, max long, max lat).
          in: query
          name: bounds
          type: string
        - description: two letter code ISO 3166-1 Alpha 2 code to limit results to that country.
          in: query
          name: countrycode
          type: string
        - description: wraps the returned JSON with a function name.
          in: query
          name: jsonp
          type: string
        - description: "an IETF format language code (ex: 'es' or 'pt-BR')."
          in: query
          name: language
          type: string
        - description: maximum number of results to return. Default is 10. Maximum is 100.
          in: query
          name: limit
          type: integer
        - description: integer from 1-10. Only results with at least this confidence are returned.
          in: query
          name: min_confidence
          type: integer
        - description: when true annotations are not added to results.
          in: query
          name: no_annotations
          type: boolean
        - description: when true results are not deduplicated.
          in: query
          name: no_dedupe
          type: boolean
        - description: when true query content is not logged.
          in: query
          name: no_record
          type: boolean
        - description: when true results are pretty printed. Useful for debugging.
          in: query
          name: pretty
          type: boolean
        - description: lat,lng to bias results.
          in: query
          name: proximity
          type: string
        - description: match nearest road, include roadinfo annotation
          in: query
          name: roadinfo
          type: boolean
      responses:
        "200":
          description: Successful response
          schema:
            $ref: "#/definitions/Response"
        "400":
          description: Invalid request
          schema:
            $ref: "#/definitions/Response"
        "401":
          description: Unable to authenticate
          schema:
            $ref: "#/definitions/Response"
        "402":
          description: Valid request but quota exceeded
          schema:
            $ref: "#/definitions/Response"
        "403":
          description: Forbidden
          schema:
            $ref: "#/definitions/Response"
        "404":
          description: Invalid API endpoint
          schema:
            $ref: "#/definitions/Response"
        "405":
          description: Method not allowed
          schema:
            $ref: "#/definitions/Response"
        "408":
          description: Timeout; you can try again
          schema:
            $ref: "#/definitions/Response"
        "410":
          description: Request too long
          schema:
            $ref: "#/definitions/Response"
        "426":
          description: Upgrade required
          schema:
            $ref: "#/definitions/Response"
        "429":
          description: Too many requests
          schema:
            $ref: "#/definitions/Response"
        "503":
          description: Internal server error
          schema:
            $ref: "#/definitions/Response"
definitions:
  LatLng:
    properties:
      lat:
        format: float
        type: number
      lng:
        format: float
        type: number
    type: object
  Response:
    properties:
      documentation:
        type: string
      licenses:
        items:
          properties:
            name:
              type: string
            url:
              type: string
          type: object
        type: array
      rate:
        properties:
          limit:
            type: integer
          remaining:
            type: integer
          reset:
            type: integer
        type: object
      results:
        items:
          properties:
            annotations:
              type: object
            bounds:
              properties:
                northeast:
                  $ref: "#/definitions/LatLng"
                southwest:
                  $ref: "#/definitions/LatLng"
              type: object
            components:
              type: object
            confidence:
              type: integer
            formatted:
              type: string
            geometry:
              $ref: "#/definitions/LatLng"
          type: object
        type: array
      status:
        properties:
          code:
            type: integer
          message:
            type: string
        type: object
      stay_informed:
        properties:
          blog:
            type: string
          twitter:
            type: string
        type: object
      thanks:
        type: string
      timestamp:
        properties:
          created_http:
            type: string
          created_unix:
            type: integer
        type: object
      total_results:
        type: integer
