openapi: 3.2.0
info:
  contact:
    email: support@opencagedata.com
    name: OpenCage GmbH
    url: https://opencagedata.com/contact
  version: 1.1.0
  termsOfService: https://opencagedata.com/terms
  title: OpenCage Geocoding API
  description: |
    Worldwide forward and reverse geocoding with open data.
    # Rate Limiting
    Responses to subscription customers do NOT contain the `rate` element of the response body or `X-Ratelimit` HTTP headers, because they do not face hard limits. 
  x-origin:
    format: openapi
    url: https://opencagedata.com/openapi.yaml
    version: 3.2.0
  x-logo:
    url: https://opencagedata.com/opencagelogo-green.png
servers:
  - url: https://api.opencagedata.com/geocode/v1
    name: OpenCage geocoding API
security:
  - ApiKeyAuth: []
tags:
  - name: Geocoding
    description: Convert address into coordinates (latitude, longitude) and relevant location information
    summary: forward geocoding
  - name: Reverse Geocoding
    description: Convert coordinates (latitude, longitude) into addresses and relevant location information
    summary: reverse geocoding
  - name: Health
    description: API connectivity test
    summary: connectivity check
externalDocs:
  description: OpenCage Geocoding API documentation
  url: https://opencagedata.com/api
paths:
  /ping:
    get:
      description: Health check endpoint to verify API availability
      operationId: get-ping
      summary: check API health and connectivity
      tags:
        - Health
      security: []
      responses:
        '200':
          description: API is reachable
          content:
            text/plain:
              schema:
                type: string
                example: pong
  /json:
    get:
      description: Geocode (JSON)
      operationId: get-json
      summary: request a JSON geocoding response
      tags:
        - Geocoding
        - Reverse Geocoding
      parameters:
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/abbrv'
        - $ref: '#/components/parameters/address_only'
        - $ref: '#/components/parameters/add_request'
        - $ref: '#/components/parameters/bounds'
        - $ref: '#/components/parameters/countrycode'
        - $ref: '#/components/parameters/jsonp'
        - $ref: '#/components/parameters/language'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/no_annotations'
        - $ref: '#/components/parameters/no_dedupe'
        - $ref: '#/components/parameters/no_record'
        - $ref: '#/components/parameters/pretty'
        - $ref: '#/components/parameters/proximity'
        - $ref: '#/components/parameters/roadinfo'
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/ratelimit-remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/ratelimit-reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '401':
          description: Unable to authenticate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '402':
          description: Valid request but quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '404':
          description: Invalid API endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '408':
          description: Timeout; you can try again
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '410':
          description: Request too long
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '426':
          description: Upgrade required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '503':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
  /xml:
    get:
      description: Geocode (XML)
      operationId: get-xml
      summary: request an XML geocoding response
      tags:
        - Geocoding
        - Reverse Geocoding
      parameters:
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/abbrv'
        - $ref: '#/components/parameters/address_only'
        - $ref: '#/components/parameters/add_request'
        - $ref: '#/components/parameters/bounds'
        - $ref: '#/components/parameters/countrycode'
        - $ref: '#/components/parameters/jsonp'
        - $ref: '#/components/parameters/language'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/no_annotations'
        - $ref: '#/components/parameters/no_dedupe'
        - $ref: '#/components/parameters/no_record'
        - $ref: '#/components/parameters/pretty'
        - $ref: '#/components/parameters/proximity'
        - $ref: '#/components/parameters/roadinfo'
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/ratelimit-remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/ratelimit-reset'
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Invalid request
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '401':
          description: Unable to authenticate
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '402':
          description: Valid request but quota exceeded
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '403':
          description: Forbidden
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '404':
          description: Invalid API endpoint
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '405':
          description: Method not allowed
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '408':
          description: Timeout; you can try again
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '410':
          description: Request too long
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '426':
          description: Upgrade required
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '429':
          description: Too many requests
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: Internal server error
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
        '503':
          description: Internal server error
          content:
            text/xml; charset=utf-8:
              schema:
                $ref: '#/components/schemas/Response'
  /geojson:
    get:
      description: Geocode (GeoJSON)
      operationId: get-geojson
      summary: request a GeoJSON geocoding response
      tags:
        - Geocoding
        - Reverse Geocoding
      parameters:
        - $ref: '#/components/parameters/query'
        - $ref: '#/components/parameters/address_only'
        - $ref: '#/components/parameters/add_request'
        - $ref: '#/components/parameters/bounds'
        - $ref: '#/components/parameters/countrycode'
        - $ref: '#/components/parameters/jsonp'
        - $ref: '#/components/parameters/language'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/no_annotations'
        - $ref: '#/components/parameters/no_dedupe'
        - $ref: '#/components/parameters/no_record'
        - $ref: '#/components/parameters/pretty'
        - $ref: '#/components/parameters/proximity'
        - $ref: '#/components/parameters/roadinfo'
      responses:
        '200':
          description: OK
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/ratelimit-limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/ratelimit-remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/ratelimit-reset'
          content:
            application/json; charset=utf-8:
              schema:
                $ref: '#/components/schemas/GetGeojson200ResponseBody'
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '401':
          description: Unable to authenticate
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '402':
          description: Valid request but quota exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '404':
          description: Invalid API endpoint
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '405':
          description: Method not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '408':
          description: Timeout; you can try again
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '410':
          description: Request too long
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '426':
          description: Upgrade required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '429':
          description: Too many requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '503':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: query
      name: key
      description: 30 character long, alphanumeric string
      x-externalDocs:
        description: API key unique to your account
        url: https://opencagedata.com/api#required-param
  parameters:
    query:
      name: q
      description: string or lat,lng to be geocoded
      in: query
      required: true
      x-externalDocs:
        description: q parameter documentation
        url: https://opencagedata.com/api#q-param
      schema:
        type: string
        description: Location to geocode - can be an address, place name, or decimal coordinates in latitude, longitude order
        minLength: 2
        examples:
          - 52.5432379, 13.4142133
          - Times Square, New York, USA
          - Eiffel Tower
    abbrv:
      description: when true we attempt to abbreviate the formatted field of results.
      in: query
      name: abbrv
      required: false
      x-externalDocs:
        description: abbrv parameter documentation
        url: https://opencagedata.com/api#abbrv-param
      schema:
        type: boolean
        default: false
    address_only:
      name: address_only
      description: when true we include only address details in the formatted field of results.
      in: query
      required: false
      x-externalDocs:
        description: address_only parameter documentation
        url: https://opencagedata.com/api#address_only-param
      schema:
        type: boolean
        default: false
    add_request:
      name: add_request
      in: query
      description: if true the request is included in the response.
      required: false
      x-externalDocs:
        description: add_request parameter documentation
        url: https://opencagedata.com/api#add_request-param
      schema:
        default: false
        type: boolean
    bounds:
      in: query
      description: four coordinate points forming the south-west and north-east corners of a bounding box
      name: bounds
      required: false
      x-externalDocs:
        description: bound parameter documentation
        url: https://opencagedata.com/api#bounds-param
      schema:
        type: string
        description: decimal coordinates in min long, min lat, max long, max lat order
        examples:
          - '-0.563160,51.280430,0.278970,51.683979'
    countrycode:
      name: countrycode
      description: CSV list of lowercase two letter ISO 3166-1 Alpha 2 codes to limit results to that country/countries.
      in: query
      required: false
      x-externalDocs:
        description: countrycode parameter documentation
        url: https://opencagedata.com/api#countrycode-param
      schema:
        type: string
        examples:
          - de
          - at
          - ch,li
        minLength: 2
    jsonp:
      name: jsonp
      description: wraps the returned JSON with a function name.
      in: query
      required: false
      x-externalDocs:
        description: jsonp parameter documentation
        url: https://opencagedata.com/api#jsonp-param
      schema:
        type: string
        description: Function name to wrap the JSON response in for JSONP callbacks
        examples:
          - myfunc
          - callback
          - handleResult
    language:
      description: an IETF format language code or "native"
      name: language
      in: query
      required: false
      x-externalDocs:
        description: language parameter documentation
        url: https://opencagedata.com/api#language
      schema:
        type: string
        description: the preferred language of results
        examples:
          - de
          - pt-BR
          - native
    limit:
      name: limit
      description: maximum number of results to return. Default is 10. Maximum is 100.
      in: query
      required: false
      x-externalDocs:
        description: limit parameter documentation
        url: https://opencagedata.com/api#limit-param
      schema:
        type: integer
        minimum: 1
        maximum: 100
        examples:
          - 1
          - 3
    no_annotations:
      name: no_annotations
      description: when true annotations are not added to results.
      in: query
      required: false
      x-externalDocs:
        description: no_annotations parameter documentation
        url: https://opencagedata.com/api#no_annotations-param
      schema:
        type: boolean
        default: false
    no_dedupe:
      name: no_dedupe
      description: when true results are not deduplicated
      in: query
      required: false
      x-externalDocs:
        description: no_dedupe parameter documentation
        url: https://opencagedata.com/api#no_dedupe-param
      schema:
        type: boolean
        default: false
    no_record:
      name: no_record
      description: when true query content is not logged
      in: query
      required: false
      x-externalDocs:
        description: no_record parameter documentation
        url: https://opencagedata.com/api#no_record-param
      schema:
        type: boolean
        default: false
    pretty:
      name: pretty
      description: when true results are pretty printed
      in: query
      required: false
      x-externalDocs:
        description: pretty parameter documentation
        url: https://opencagedata.com/api#pretty-param
      schema:
        type: boolean
        default: false
    proximity:
      name: proximity
      description: lat,lng to bias results
      in: query
      required: false
      x-externalDocs:
        description: proximity parameter documentation
        url: https://opencagedata.com/api#proximity-param
      schema:
        type: string
        description: Latitude and longitude decimal coordinates to bias results toward
        pattern: ^-?[0-9]{1,2}(\.[0-9]+)?,\s*-?[0-9]{1,3}(\.[0-9]+)?$
        examples:
          - 52.3877830, 9.7334394
          - 51.522618,-0.102530
          - 42.359578,-71.091982
    roadinfo:
      name: roadinfo
      description: when true we geocode to nearest road, include roadinfo annotation
      in: query
      required: false
      x-externalDocs:
        description: roadinfo parameter documentation
        url: https://opencagedata.com/api#roadinfo-param
      schema:
        type: boolean
        default: false
  headers:
    ratelimit-limit:
      description: '**Non-subscription customers only.** Total number of API requests your account is limited to over given time period (24 hours for free trials).'
      x-externalDocs:
        description: rate limit documentation
        url: https://opencagedata.com/api#rate-limiting
      schema:
        type: integer
        examples:
          - 2500
    ratelimit-remaining:
      description: '**Non-subscription customers only.** The number of requests left for the time window.'
      x-externalDocs:
        description: rate limit documentation
        url: https://opencagedata.com/api#rate-limiting
      schema:
        type: integer
        examples:
          - 2498
    ratelimit-reset:
      description: '**Non-subscription customers only.** The UNIX timestamp at which the current rate limit window resets.'
      x-externalDocs:
        description: rate limit documentation
        url: https://opencagedata.com/api#rate-limiting
      schema:
        type: integer
        examples:
          - 1605312000
  schemas:
    LatLng:
      type: object
      description: Geographic coordinates (latitude and longitude)
      properties:
        lat:
          type: number
          description: Latitude coordinate in decimal degrees
          format: double
          minimum: -90
          maximum: 90
          examples:
            - 40.7128
            - 51.5074
            - -33.8688
        lng:
          type: number
          description: Longitude coordinate in decimal degrees
          format: double
          minimum: -180
          maximum: 180
          examples:
            - -74.006
            - -0.1278
            - 151.2093
      required:
        - lat
        - lng
    Response:
      type: object
      properties:
        documentation:
          type: string
          description: URL to the API documentation
          format: uri
        rate:
          type:
            - object
            - 'null'
          description: Rate limit information. Not present for subscription customers.
          properties:
            limit:
              type: integer
              description: Total number of requests allowed within the time window
            remaining:
              type: integer
              description: Number of requests remaining within the current time window
            reset:
              type: integer
              description: Unix timestamp when the rate limit will reset
        licenses:
          type: array
          description: License information for data sources used in the response
          items:
            type: object
            required:
              - name
              - url
            properties:
              name:
                type: string
                description: Name of the license
              url:
                type: string
                format: uri
                description: URL where the full license text can be found
        results:
          type: array
          description: Array of geocoding results
          items:
            type: object
            properties:
              annotations:
                description: |
                  Additional data about the location. Which annotations are returned depends 
                  on the location of the result.
                type: object
                externalDocs:
                  description: Annotations documentation
                  url: https://opencagedata.com/api#annotations
                properties:
                  DMS:
                    type: object
                    description: Degrees, minutes, seconds representation of coordinates
                    properties:
                      lat:
                        type: string
                      lng:
                        type: string
                    required:
                      - lat
                      - lng
                  FIPS:
                    type: object
                    description: FIPS (Federal Information Processing Standards) codes
                    properties:
                      county:
                        type: string
                      state:
                        type: string
                    required:
                      - state
                  H3:
                    description: |
                      H3 geospatial indexing system, only available to paying customers and by request
                    type: string
                    externalDocs:
                      description: H3 annotation documentation
                      url: https://opencagedata.com/api#h3
                  MGRS:
                    type: string
                    description: Military Grid Reference System coordinates
                  Maidenhead:
                    type: string
                    description: Maidenhead Locator System coordinates
                  Mercator:
                    type: object
                    description: Web Mercator projection coordinates
                    properties:
                      x:
                        type: number
                      'y':
                        type: number
                    required:
                      - x
                      - 'y'
                  NUTS:
                    type: object
                    description: Nomenclature of Territorial Units for Statistics codes
                    properties:
                      NUTS0:
                        type: object
                        properties:
                          code:
                            type: string
                        required:
                          - code
                      NUTS1:
                        type: object
                        properties:
                          code:
                            type: string
                        required:
                          - code
                      NUTS2:
                        type: object
                        properties:
                          code:
                            type: string
                        required:
                          - code
                      NUTS3:
                        type: object
                        properties:
                          code:
                            type: string
                        required:
                          - code
                    required:
                      - NUTS0
                      - NUTS1
                      - NUTS2
                      - NUTS3
                  OSM:
                    type: object
                    description: OpenStreetMap related information
                    properties:
                      edit_url:
                        type: string
                        format: uri
                      note_url:
                        type: string
                        format: uri
                      url:
                        type: string
                        format: uri
                    required:
                      - note_url
                      - url
                  UN/LOCODE:
                    description: |
                      United Nations Code for Trade and Transport Locations
                    type: object
                    externalDocs:
                      description: UN/LOCODE documentation
                      url: https://opencagedata.com/api#unlocode
                    properties:
                      code:
                        type: string
                      date:
                        type: string
                      function:
                        type: object
                      meaning:
                        type: array
                        items:
                          type: string
                      raw:
                        type: string
                  UN_M49:
                    type: object
                    description: |
                      UN M49 standard country or area codes. Response varies based on region.
                    externalDocs:
                      description: UN M49 documentation
                      url: https://opencagedata.com/api#unm49
                    properties:
                      regions:
                        type: object
                        properties:
                          AMERICAS:
                            type: string
                          NORTHERN_AMERICA:
                            type: string
                          US:
                            type: string
                          WORLD:
                            type: string
                          DE:
                            type: string
                          EUROPE:
                            type: string
                          WESTERN_EUROPE:
                            type: string
                        required:
                          - WORLD
                      statistical_groupings:
                        type: array
                        items:
                          type: string
                    required:
                      - regions
                      - statistical_groupings
                  callingcode:
                    type: number
                    description: International calling code for the country
                  currency:
                    type: object
                    description: Currency information for the location's country
                    properties:
                      alternate_symbols:
                        type: array
                        items:
                          type: string
                      decimal_mark:
                        type: string
                      disambiguate_symbol:
                        type: string
                      html_entity:
                        type: string
                      iso_code:
                        type: string
                      iso_numeric:
                        type: string
                      name:
                        type: string
                      smallest_denomination:
                        type: number
                      subunit:
                        type: string
                      subunit_to_unit:
                        type: number
                      symbol:
                        type: string
                      symbol_first:
                        type: number
                      thousands_separator:
                        type: string
                    required:
                      - alternate_symbols
                      - decimal_mark
                      - html_entity
                      - iso_code
                      - iso_numeric
                      - name
                      - smallest_denomination
                      - subunit
                      - subunit_to_unit
                      - symbol
                      - symbol_first
                      - thousands_separator
                  flag:
                    type: string
                    description: Unicode representation of the country's flag
                  geohash:
                    type: string
                    description: Geohash representation of the coordinates
                  qibla:
                    type: number
                    description: Direction of the Qibla (in degrees from north)
                  roadinfo:
                    type: object
                    description: Information about roads at or near the location
                    properties:
                      drive_on:
                        type: string
                        enum:
                          - left
                          - right
                        description: Which side of the road traffic drives on
                      lanes:
                        type: number
                      maxheight:
                        type: string
                      maxspeed:
                        type: string
                      maxweight:
                        type: number
                      maxwidth:
                        type: number
                      oneway:
                        type: number
                        enum:
                          - 0
                          - 1
                        description: Whether the road is one-way (1) or two-way (0)
                      road:
                        type: string
                      road_reference:
                        type: string
                      road_reference_intl:
                        type: string
                      road_type:
                        type: string
                      speed_in:
                        type: string
                        enum:
                          - km/h
                          - mph
                        description: Units used for speed limits
                      surface:
                        type: number
                      toll:
                        type: string
                      width:
                        type: number
                    required:
                      - drive_on
                      - speed_in
                  sun:
                    type: object
                    description: Sun rise and set times for the location
                    properties:
                      rise:
                        type: object
                        description: Various sunrise times
                        properties:
                          apparent:
                            type: number
                            description: Sunrise time considering atmospheric refraction
                          astronomical:
                            type: number
                            description: When the sun is 18 degrees below the horizon
                          civil:
                            type: number
                            description: When the sun is 6 degrees below the horizon
                          nautical:
                            type: number
                            description: When the sun is 12 degrees below the horizon
                        required:
                          - apparent
                          - astronomical
                          - civil
                          - nautical
                      set:
                        type: object
                        description: Various sunset times
                        properties:
                          apparent:
                            type: number
                            description: Sunset time considering atmospheric refraction
                          astronomical:
                            type: number
                            description: When the sun is 18 degrees below the horizon
                          civil:
                            type: number
                            description: When the sun is 6 degrees below the horizon
                          nautical:
                            type: number
                            description: When the sun is 12 degrees below the horizon
                        required:
                          - apparent
                          - astronomical
                          - civil
                          - nautical
                    required:
                      - rise
                      - set
                  timezone:
                    type: object
                    description: Timezone information for the location
                    properties:
                      name:
                        type: string
                        description: IANA timezone database name
                      now_in_dst:
                        type: number
                        enum:
                          - 0
                          - 1
                        description: Whether daylight saving time is currently in effect
                      offset_sec:
                        type: number
                        description: Offset from UTC in seconds
                      offset_string:
                        type: string
                        description: Offset from UTC as string (e.g., +01:00)
                      short_name:
                        type: string
                        description: Short timezone name (e.g., EST, CEST)
                    required:
                      - name
                      - now_in_dst
                      - offset_sec
                      - offset_string
                      - short_name
                  what3words:
                    type: object
                    description: What3Words representation of the location
                    properties:
                      words:
                        type: string
                        description: Three-word address
                    required:
                      - words
              bounds:
                type: object
                description: Bounding box containing the location
                properties:
                  northeast:
                    $ref: '#/components/schemas/LatLng'
                  southwest:
                    $ref: '#/components/schemas/LatLng'
              components:
                description: |
                  Normalized components of the address. Fields will depend on the location.
                externalDocs:
                  description: Components documentation
                  url: https://opencagedata.com/api#formatted
                type: object
                properties:
                  ISO_3166-1_alpha-2:
                    type: string
                    description: Two-letter country code
                  ISO_3166-1_alpha-3:
                    type: string
                    description: Three-letter country code
                  ISO_3166-2:
                    type: array
                    description: Codes for country subdivisions
                    items:
                      type: string
                  _category:
                    type: string
                    description: Category of the location
                  _normalized_city:
                    type: string
                    description: Normalized city name
                  _type:
                    type: string
                    description: Type of the location
                  body_of_water:
                    type: string
                  borough:
                    type: string
                  city:
                    type: string
                  continent:
                    type: string
                  country:
                    type: string
                  country_code:
                    type: string
                  county:
                    type: string
                  house_number:
                    type: string
                  neighbourhood:
                    type: string
                  postcode:
                    type: string
                  road:
                    type: string
                  state:
                    type: string
                  state_code:
                    type: string
                  town:
                    type: string
                  village:
                    type: string
                  city_district:
                    type: string
                  office:
                    type: string
                  political_union:
                    type: string
                  suburb:
                    type: string
                required:
                  - _type
                  - _category
              confidence:
                type: integer
                description: |
                  Confidence score from 0-10 (10 being the most confident)
                minimum: 0
                maximum: 10
              distance_from_q:
                description: |
                  Only for reverse geocoding requests. Distance from the query point to the result.
                type: object
                externalDocs:
                  description: Response documentation
                  url: https://opencagedata.com/api#response
                properties:
                  meters:
                    type: number
                    description: Distance in meters
              formatted:
                type: string
                description: Human-readable formatted address
              geometry:
                $ref: '#/components/schemas/LatLng'
        status:
          type: object
          description: Status information about the request
          properties:
            message:
              type: string
              description: Status message
            code:
              type: integer
              description: HTTP status code
        stay_informed:
          type: object
          description: Links to follow OpenCage for updates
          properties:
            blog:
              type: string
              format: uri
              description: URL to the OpenCage blog
            twitter:
              type: string
              format: uri
              description: URL to OpenCage Twitter account
            mastodon:
              type: string
              format: uri
              description: URL to OpenCage Mastodon account
          required:
            - mastodon
        thanks:
          type: string
          description: Thank you message
        timestamp:
          type: object
          description: Timestamp information
          properties:
            created_http:
              type: string
              format: date-time
              description: HTTP-formatted timestamp
            created_unix:
              type: integer
              description: Unix timestamp
        total_results:
          type: integer
          description: Total number of results found
      required:
        - documentation
        - licenses
        - results
        - status
        - stay_informed
        - timestamp
        - total_results
    GetGeojson200ResponseBody:
      type: object
      description: GeoJSON response from the OpenCage Geocoder API
      externalDocs:
        description: Response format documentation
        url: https://opencagedata.com/api#response
      properties:
        documentation:
          type: string
          format: uri
          description: URL to the API documentation
        features:
          type: array
          description: Array of GeoJSON feature objects containing geocoding results
          items:
            type: object
            description: GeoJSON feature object
            properties:
              geometry:
                type: object
                description: GeoJSON geometry object representing the location point
                properties:
                  coordinates:
                    type: array
                    description: Location coordinates in [longitude, latitude] order (GeoJSON standard)
                    minItems: 2
                    maxItems: 3
                    items:
                      type: number
                      format: double
                  type:
                    type: string
                    description: GeoJSON geometry type
                    enum:
                      - Point
                required:
                  - coordinates
                  - type
              properties:
                type: object
                description: Properties of the geocoded location
                properties:
                  annotations:
                    type:
                      - object
                      - 'null'
                    description: |
                      Additional data about the location. The annotations provided depend on 
                      the specific location being geocoded.
                    externalDocs:
                      description: Annotations documentation
                      url: https://opencagedata.com/api#annotations
                    properties:
                      DMS:
                        type: object
                        description: Degrees, minutes, seconds representation of coordinates
                        properties:
                          lat:
                            type: string
                            description: Latitude in degrees, minutes, seconds format
                          lng:
                            type: string
                            description: Longitude in degrees, minutes, seconds format
                        required:
                          - lat
                          - lng
                      FIPS:
                        type: object
                        description: FIPS (Federal Information Processing Standards) codes
                        properties:
                          county:
                            type: string
                            description: FIPS county code
                          state:
                            type: string
                            description: FIPS state code
                        required:
                          - state
                      MGRS:
                        type: string
                        description: Military Grid Reference System coordinates
                      Maidenhead:
                        type: string
                        description: Maidenhead Locator System coordinates
                      Mercator:
                        type: object
                        description: Web Mercator projection coordinates
                        properties:
                          x:
                            type: number
                            description: X coordinate (longitude) in Web Mercator projection
                          'y':
                            type: number
                            description: Y coordinate (latitude) in Web Mercator projection
                        required:
                          - x
                          - 'y'
                      OSM:
                        type: object
                        description: OpenStreetMap related information
                        properties:
                          edit_url:
                            type: string
                            format: uri
                            description: URL to edit this location on OpenStreetMap
                          note_url:
                            type: string
                            format: uri
                            description: URL to add a note about this location on OpenStreetMap
                          url:
                            type: string
                            format: uri
                            description: URL to view this location on OpenStreetMap
                        required:
                          - note_url
                          - url
                      UN_M49:
                        type: object
                        description: |
                          UN M49 standard country or area codes. Response varies based on region.
                        externalDocs:
                          description: UN M49 documentation
                          url: https://opencagedata.com/api#unm49
                        properties:
                          regions:
                            type: object
                            description: Hierarchical region codes
                            properties:
                              AMERICAS:
                                type: string
                                description: Americas regional code
                              NORTHERN_AMERICA:
                                type: string
                                description: Northern America regional code
                              US:
                                type: string
                                description: Country code
                              WORLD:
                                type: string
                                description: World code
                              DE:
                                type: string
                                description: Country code
                              EUROPE:
                                type: string
                                description: Europe regional code
                              WESTERN_EUROPE:
                                type: string
                                description: Western Europe regional code
                            required:
                              - WORLD
                          statistical_groupings:
                            type: array
                            description: Statistical groupings the location belongs to
                            items:
                              type: string
                        required:
                          - regions
                          - statistical_groupings
                      callingcode:
                        type: number
                        description: International calling code for the country
                      currency:
                        type: object
                        description: Currency information for the location's country
                        properties:
                          alternate_symbols:
                            type: array
                            description: Alternative symbols used for the currency
                            items:
                              type: string
                          decimal_mark:
                            type: string
                            description: Character used as decimal separator
                          disambiguate_symbol:
                            type: string
                            description: Symbol used to disambiguate the currency
                          html_entity:
                            type: string
                            description: HTML entity for the currency symbol
                          iso_code:
                            type: string
                            description: ISO 4217 currency code
                          iso_numeric:
                            type: string
                            description: ISO 4217 numeric currency code
                          name:
                            type: string
                            description: Full name of the currency
                          smallest_denomination:
                            type: number
                            description: Smallest denomination in circulation
                          subunit:
                            type: string
                            description: Name of the subunit of the currency
                          subunit_to_unit:
                            type: number
                            description: Number of subunits in one unit
                          symbol:
                            type: string
                            description: Primary symbol used for the currency
                          symbol_first:
                            type: number
                            enum:
                              - 0
                              - 1
                            description: Whether the symbol appears before (1) or after (0) the amount
                          thousands_separator:
                            type: string
                            description: Character used as thousands separator
                        required:
                          - alternate_symbols
                          - decimal_mark
                          - html_entity
                          - iso_code
                          - iso_numeric
                          - name
                          - smallest_denomination
                          - subunit
                          - subunit_to_unit
                          - symbol
                          - symbol_first
                          - thousands_separator
                      flag:
                        type: string
                        description: Unicode representation of the country's flag
                      geohash:
                        type: string
                        description: Geohash representation of the coordinates
                      qibla:
                        type: number
                        description: Direction of the Qibla (in degrees from north)
                      roadinfo:
                        type: object
                        description: Information about roads at or near the location
                        properties:
                          drive_on:
                            type: string
                            enum:
                              - left
                              - right
                            description: Which side of the road traffic drives on
                          road:
                            type: string
                            description: Road name or identifier
                          speed_in:
                            type: string
                            enum:
                              - km/h
                              - mph
                            description: Units used for speed limits
                        required:
                          - drive_on
                          - speed_in
                      sun:
                        type: object
                        description: Sun rise and set times for the location
                        properties:
                          rise:
                            type: object
                            description: Various sunrise times
                            properties:
                              apparent:
                                type: number
                                description: Sunrise time considering atmospheric refraction
                              astronomical:
                                type: number
                                description: When the sun is 18 degrees below the horizon
                              civil:
                                type: number
                                description: When the sun is 6 degrees below the horizon
                              nautical:
                                type: number
                                description: When the sun is 12 degrees below the horizon
                            required:
                              - apparent
                              - astronomical
                              - civil
                              - nautical
                          set:
                            type: object
                            description: Various sunset times
                            properties:
                              apparent:
                                type: number
                                description: Sunset time considering atmospheric refraction
                              astronomical:
                                type: number
                                description: When the sun is 18 degrees below the horizon
                              civil:
                                type: number
                                description: When the sun is 6 degrees below the horizon
                              nautical:
                                type: number
                                description: When the sun is 12 degrees below the horizon
                            required:
                              - apparent
                              - astronomical
                              - civil
                              - nautical
                        required:
                          - rise
                          - set
                      timezone:
                        type: object
                        description: Timezone information for the location
                        properties:
                          name:
                            type: string
                            description: IANA timezone database name
                          now_in_dst:
                            type: number
                            enum:
                              - 0
                              - 1
                            description: Whether daylight saving time is currently in effect
                          offset_sec:
                            type: number
                            description: Offset from UTC in seconds
                          offset_string:
                            type: string
                            description: Offset from UTC as string (e.g., +01:00)
                          short_name:
                            type: string
                            description: Short timezone name (e.g., EST, CEST)
                        required:
                          - name
                          - now_in_dst
                          - offset_sec
                          - offset_string
                          - short_name
                      what3words:
                        type: object
                        description: What3Words representation of the location
                        properties:
                          words:
                            type: string
                            description: Three-word address
                        required:
                          - words
                      NUTS:
                        type: object
                        description: Nomenclature of Territorial Units for Statistics codes
                        properties:
                          NUTS0:
                            type: object
                            description: Country-level NUTS code
                            properties:
                              code:
                                type: string
                                description: NUTS0 code
                            required:
                              - code
                          NUTS1:
                            type: object
                            description: Major socio-economic region NUTS code
                            properties:
                              code:
                                type: string
                                description: NUTS1 code
                            required:
                              - code
                          NUTS2:
                            type: object
                            description: Basic region NUTS code
                            properties:
                              code:
                                type: string
                                description: NUTS2 code
                            required:
                              - code
                          NUTS3:
                            type: object
                            description: Small region NUTS code
                            properties:
                              code:
                                type: string
                                description: NUTS3 code
                            required:
                              - code
                        required:
                          - NUTS0
                          - NUTS1
                          - NUTS2
                          - NUTS3
                  bounds:
                    type: object
                    description: Bounding box containing the location
                    properties:
                      northeast:
                        type: object
                        description: Northeast corner of bounding box
                        properties:
                          lat:
                            type: number
                            format: double
                            minimum: -90
                            maximum: 90
                            description: Latitude of northeast corner
                          lng:
                            type: number
                            format: double
                            minimum: -180
                            maximum: 180
                            description: Longitude of northeast corner
                        required:
                          - lat
                          - lng
                      southwest:
                        type: object
                        description: Southwest corner of bounding box
                        properties:
                          lat:
                            type: number
                            format: double
                            minimum: -90
                            maximum: 90
                            description: Latitude of southwest corner
                          lng:
                            type: number
                            format: double
                            minimum: -180
                            maximum: 180
                            description: Longitude of southwest corner
                        required:
                          - lat
                          - lng
                    required:
                      - northeast
                      - southwest
                  components:
                    type: object
                    description: |
                      Normalized components of the address. Fields will depend on the location.
                    externalDocs:
                      description: Components documentation
                      url: https://opencagedata.com/api#components
                    properties:
                      ISO_3166-1_alpha-2:
                        type: string
                        description: Two-letter country code
                      ISO_3166-1_alpha-3:
                        type: string
                        description: Three-letter country code
                      ISO_3166-2:
                        type: array
                        description: Codes for country subdivisions
                        items:
                          type: string
                      _category:
                        type: string
                        description: Category of the location
                      _normalized_city:
                        type: string
                        description: The city / town / village placename
                      _type:
                        type: string
                        description: Type of the location
                      borough:
                        type: string
                        description: Borough or district within a city
                      city:
                        type: string
                        description: City name
                      continent:
                        type: string
                        description: Continent name
                      country:
                        type: string
                        description: Country name
                      country_code:
                        type: string
                        description: Two-letter country code (lowercase)
                      county:
                        type: string
                        description: County or district name
                      house_number:
                        type: string
                        description: Building or house number
                      neighbourhood:
                        type: string
                        description: Neighborhood name
                      postcode:
                        type: string
                        description: Postal code
                      road:
                        type: string
                        description: Street or road name
                      state:
                        type: string
                        description: State, province, or region name
                      state_code:
                        type: string
                        description: State or province code
                      town:
                        type: string
                        description: Town name
                      village:
                        type: string
                        description: Village name
                      city_district:
                        type: string
                        description: District within a city
                      office:
                        type: string
                        description: Office or building name
                      political_union:
                        type: string
                        description: Political union (e.g., European Union)
                      suburb:
                        type: string
                        description: Suburb name
                  confidence:
                    type: number
                    description: |
                      Confidence score from 0-10 (10 being the most confident)
                    minimum: 0
                    maximum: 10
                  formatted:
                    type: string
                    description: Human-readable formatted address
                required:
                  - components
                  - confidence
                  - formatted
              type:
                type: string
                description: GeoJSON object type
                enum:
                  - Feature
            required:
              - geometry
              - properties
              - type
        licenses:
          type: array
          description: License information for data sources used in the response
          items:
            type: object
            description: License information
            properties:
              name:
                type: string
                description: Name of the license
              url:
                type: string
                format: uri
                description: URL where the full license text can be found
            required:
              - name
              - url
        rate:
          description: Rate limit information (not present for subscription customers)
          properties:
            limit:
              type: number
              description: Total number of requests allowed within the time window
            remaining:
              type: number
              description: Number of requests remaining within the current time window
            reset:
              type: number
              description: Unix timestamp when the rate limit will reset
          required:
            - limit
            - remaining
            - reset
          type:
            - object
            - 'null'
        status:
          type: object
          description: Status information about the request
          properties:
            code:
              type: number
              description: HTTP status code
            message:
              type: string
              description: Status message
          required:
            - code
            - message
        stay_informed:
          type: object
          description: Links to follow OpenCage for updates
          properties:
            blog:
              type: string
              format: uri
              description: URL to the OpenCage blog
            mastodon:
              type: string
              format: uri
              description: URL to OpenCage Mastodon account
          required:
            - blog
            - mastodon
        thanks:
          type: string
          description: Thank you message
        timestamp:
          type: object
          description: Timestamp information
          properties:
            created_http:
              type: string
              format: date-time
              description: HTTP-formatted timestamp
            created_unix:
              type: number
              format: int64
              description: Unix timestamp
          required:
            - created_http
            - created_unix
        total_results:
          type: number
          description: Total number of results found
        type:
          type: string
          description: GeoJSON object type
          enum:
            - FeatureCollection
      required:
        - documentation
        - features
        - licenses
        - status
        - stay_informed
        - thanks
        - timestamp
        - total_results
        - type