openapi: 3.0.3 info: contact: name: OpenCage GmbH url: https://opencagedata.com/contact version: 1.1.0 termsOfService: https://opencagedata.com/terms title: OpenCage Geocoder 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.0.3 x-logo: url: https://opencagedata.com/opencagelogo-green.png servers: - url: https://api.opencagedata.com/geocode/v1 security: - ApiKeyAuth: [] tags: - name: Geocoding description: Convert address into coordinates (latitude, longitude)and relevant location information - name: Reverse Geocoding description: Convert coordinates (latitude, longitude) into addresses and relevant location information externalDocs: description: OpenCage Geocoder API documentation url: https://opencagedata.com/api paths: /json: get: description: Geocode (JSON) operationId: get-json 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' '503': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Response' /xml: get: operationId: get-xml description: Geocode (XML) 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' '503': description: Internal server error content: text/xml; charset=utf-8: schema: $ref: '#/components/schemas/Response' /geojson: get: operationId: get-geojson description: Geocode (GeoJSON) 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' '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 unique to your account. See https://opencagedata.com/api#required-params parameters: query: name: q description: string or lat,lng to be geocoded. ex Eiffel tower or 52.3877830, 9.7334394 in: query example: 52.3877830, 9.7334394 required: true schema: type: string abbrv: description: when true we attempt to abbreviate the formatted field of results. in: query name: abbrv required: false 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 schema: type: boolean default: false add_request: name: add_request in: query description: if true the request is included in the response. required: false schema: default: false type: boolean bounds: in: query description: four coordinate points forming the south-west and north-east corners of a bounding box (min long, min lat, max long, max lat). name: bounds required: false schema: type: string example: '-0.563160,51.280430,0.278970,51.683979' countrycode: name: countrycode description: CSV list of two letter ISO 3166-1 Alpha 2 codes) to limit results to that country/countries. in: query required: false schema: example: de,at,ch,li,lu type: string jsonp: name: jsonp description: wraps the returned JSON with a function name. in: query required: false example: myfunc schema: type: string language: description: 'an IETF format language code (ex: "es" or "pt-BR").' name: language in: query required: false example: de schema: type: string limit: name: limit description: maximum number of results to return. Default is 10. Maximum is 100. in: query required: false example: 1 schema: type: integer minimum: 1 maximum: 100 no_annotations: name: no_annotations description: when true annotations are not added to results. in: query required: false schema: type: boolean default: false no_dedupe: name: no_dedupe description: when true results are not deduplicated. in: query required: false schema: type: boolean default: false no_record: name: no_record description: when true query content is not logged. in: query required: false schema: type: boolean default: false pretty: name: pretty description: when true results are pretty printed. Useful for debugging. in: query required: false schema: type: boolean default: false proximity: name: proximity description: lat,lng to bias results. in: query required: false example: 52.3877830,9.7334394 schema: type: string roadinfo: name: roadinfo description: when true we geocode to nearest road, include roadinfo annotation in: query required: false 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).' schema: type: integer example: 2500 ratelimit-remaining: description: '**Non-subscription customers only.** The number of requests left for the time window.' schema: type: integer example: 2498 ratelimit-reset: description: '**Non-subscription customers only.** The UNIX timestamp at which the current rate limit window resets.' schema: type: integer example: 1605312000 schemas: LatLng: type: object properties: lat: type: number format: float lng: type: number format: float Response: properties: documentation: type: string rate: type: object properties: limit: type: integer remaining: type: integer reset: type: integer licenses: type: array items: type: object properties: name: type: string url: type: string results: type: array items: type: object properties: annotations: description: | which annotations are returned depends on the location of the result see https://opencagedata.com/api#annotations type: object properties: DMS: type: object properties: lat: type: string lng: type: string required: - lat - lng FIPS: type: object properties: county: type: string state: type: string required: - state H3: description: | only available to paying customers and by request see https://opencagedata.com/api#h3 type: string MGRS: type: string Maidenhead: type: string Mercator: type: object properties: x: type: number 'y': type: number required: - x - 'y' NUTS: type: object 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 properties: edit_url: type: string note_url: type: string url: type: string required: - note_url - url UN/LOCODE: description: | see https://opencagedata.com/api#unlocode type: object properties: code: type: string date: type: string function: type: object meaning: type: array items: type: string raw: type: string UN_M49: type: object description: | response varies based on region see 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 currency: type: object 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 geohash: type: string qibla: type: number roadinfo: type: object properties: drive_on: type: string lanes: type: number maxheight: type: string maxspeed: type: string maxweight: type: number maxwidth: type: number oneway: type: number road: type: string road_reference: type: string road_reference_intl: type: string road_type: type: string speed_in: type: string surface: type: number toll: type: string width: type: number required: - drive_on - speed_in sun: type: object properties: rise: type: object properties: apparent: type: number astronomical: type: number civil: type: number nautical: type: number required: - apparent - astronomical - civil - nautical set: type: object properties: apparent: type: number astronomical: type: number civil: type: number nautical: type: number required: - apparent - astronomical - civil - nautical required: - rise - set timezone: type: object properties: name: type: string now_in_dst: type: number offset_sec: type: number offset_string: type: string short_name: type: string required: - name - now_in_dst - offset_sec - offset_string - short_name what3words: type: object properties: words: type: string required: - words bounds: type: object properties: northeast: $ref: '#/components/schemas/LatLng' southwest: $ref: '#/components/schemas/LatLng' components: description: fields will depend on the location see https://opencagedata.com/api#formatted type: object properties: ISO_3166-1_alpha-2: type: string ISO_3166-1_alpha-3: type: string ISO_3166-2: type: array items: type: string _category: type: string _normalized_city: type: string _type: type: string 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 distance_from_q: description: | only for reverse geocoding requests see https://opencagedata.com/api#response type: object properties: meters: type: number formatted: type: string geometry: $ref: '#/components/schemas/LatLng' status: type: object properties: message: type: string code: type: integer stay_informed: type: object properties: blog: type: string twitter: type: string mastodon: type: string required: - mastodon thanks: type: string timestamp: type: object properties: created_http: type: string created_unix: type: integer total_results: type: integer type: object GetGeojson200ResponseBody: type: object properties: documentation: type: string features: type: array items: type: object properties: geometry: type: object properties: coordinates: type: array items: type: number type: type: string required: - coordinates - type properties: type: object properties: annotations: type: object properties: DMS: type: object properties: lat: type: string lng: type: string required: - lat - lng FIPS: type: object properties: county: type: string state: type: string required: - state MGRS: type: string Maidenhead: type: string Mercator: type: object properties: x: type: number 'y': type: number required: - x - 'y' OSM: type: object properties: edit_url: type: string note_url: type: string url: type: string required: - note_url - url UN_M49: type: object 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 currency: type: object 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 geohash: type: string qibla: type: number roadinfo: type: object properties: drive_on: type: string road: type: string speed_in: type: string required: - drive_on - speed_in sun: type: object properties: rise: type: object properties: apparent: type: number astronomical: type: number civil: type: number nautical: type: number required: - apparent - astronomical - civil - nautical set: type: object properties: apparent: type: number astronomical: type: number civil: type: number nautical: type: number required: - apparent - astronomical - civil - nautical required: - rise - set timezone: type: object properties: name: type: string now_in_dst: type: number offset_sec: type: number offset_string: type: string short_name: type: string required: - name - now_in_dst - offset_sec - offset_string - short_name what3words: type: object properties: words: type: string required: - words NUTS: type: object 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 required: - DMS - MGRS - Maidenhead - Mercator - OSM - UN_M49 - callingcode - currency - flag - geohash - qibla - roadinfo - sun - timezone - what3words bounds: type: object properties: northeast: type: object properties: lat: type: number lng: type: number required: - lat - lng southwest: type: object properties: lat: type: number lng: type: number required: - lat - lng required: - northeast - southwest components: type: object properties: ISO_3166-1_alpha-2: type: string ISO_3166-1_alpha-3: type: string ISO_3166-2: type: array items: type: string _category: type: string _type: 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: - ISO_3166-1_alpha-2 - ISO_3166-1_alpha-3 - ISO_3166-2 - _category - _type - continent - country - country_code - state - state_code confidence: type: number formatted: type: string required: - annotations - components - confidence - formatted type: type: string required: - geometry - properties - type licenses: type: array items: type: object properties: name: type: string url: type: string required: - name - url rate: type: object properties: limit: type: number remaining: type: number reset: type: number required: - limit - remaining - reset status: type: object properties: code: type: number message: type: string required: - code - message stay_informed: type: object properties: blog: type: string mastodon: type: string required: - blog - mastodon thanks: type: string timestamp: type: object properties: created_http: type: string created_unix: type: number required: - created_http - created_unix total_results: type: number type: type: string required: - documentation - features - licenses - rate - status - stay_informed - thanks - timestamp - total_results - type