openapi: 3.0.0
info:
version: 1.5.1
title: LocationIQ - API reference
description: 'LocationIQ provides flexible enterprise-grade location based solutions. We work with developers, startups and enterprises worldwide serving billions of requests everyday. This page provides an overview of the technical aspects of our API and will help you get started.'
contact:
email: hello@locationiq.com
paths:
/search:
get:
operationId: search
summary: Free Form Query
description: 'The Search API allows converting addresses, such as a street address, into geographic coordinates (latitude and longitude). These coordinates can serve various use-cases, from placing markers on a map to helping algorithms determine nearby bus stops. This process is also known as Forward Geocoding.'
tags:
- Search / Forward Geocoding
parameters:
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/format'
- $ref: '#/components/parameters/addressdetails-default-0'
- $ref: '#/components/parameters/statecode'
- $ref: '#/components/parameters/viewbox'
- $ref: '#/components/parameters/bounded'
- $ref: '#/components/parameters/limit-max-50'
- $ref: '#/components/parameters/accept-language'
- $ref: '#/components/parameters/countrycodes'
- $ref: '#/components/parameters/normalizeaddress'
- $ref: '#/components/parameters/normalizecity'
- $ref: '#/components/parameters/postaladdress'
- $ref: '#/components/parameters/matchquality'
- $ref: '#/components/parameters/source'
- $ref: '#/components/parameters/normalizeimportance'
- $ref: '#/components/parameters/dedupe-default-1'
- $ref: '#/components/parameters/namedetails'
- $ref: '#/components/parameters/extratags'
- $ref: '#/components/parameters/polygon_geojson'
- $ref: '#/components/parameters/polygon_kml'
- $ref: '#/components/parameters/polygon_svg'
- $ref: '#/components/parameters/polygon_text'
- $ref: '#/components/parameters/json_callback'
- $ref: '#/components/parameters/polygon_threshold'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/location-forward'
examples:
response:
value:
- place_id: '116136978'
licence: 'https://locationiq.com/attribution'
osm_type: way
osm_id: '34633854'
boundingbox:
- '40.7479255'
- '40.7489585'
- '-73.9865012'
- '-73.9848166'
lat: '40.74844205'
lon: '-73.98565890160751'
display_name: 'Empire State Building, 350, 5th Avenue, Manhattan Community Board 5, Manhattan, New York County, New York, New York, 10001, USA'
class: tourism
type: attraction
importance: 0.8515868466874569
icon: 'https://locationiq.org/static/images/mapicons/poi_point_of_interest.p.20.png'
address:
attraction: Empire State Building
house_number: '350'
road: 5th Avenue
neighbourhood: Manhattan Community Board 5
suburb: Manhattan
county: New York County
city: New York
state: New York
postcode: '10001'
country: United States of America
country_code: us
application/xml:
schema:
$ref: '#/components/schemas/location-forward'
examples:
Example 1:
value: |-
Empire State Building
350
5th Avenue
Manhattan Community Board 5
Manhattan
New York County
New York
New York
10001
United States of America
us
'400':
$ref: '#/components/responses/400Error-search'
'401':
$ref: '#/components/responses/401Error-search'
'403':
$ref: '#/components/responses/403Error-search'
'404':
$ref: '#/components/responses/404Error-search'
'429':
$ref: '#/components/responses/429Error-search'
'500':
$ref: '#/components/responses/500Error-search'
security:
- key: []
x-stoplight:
id: vo6s5vdzq9v1f
parameters: []
/search/structured:
get:
operationId: search-structured
summary: Structured Geocoding
description: 'Structured Query offers a more specific way to search for locations. Instead of using a single text string, you can provide distinct address components in a structured format. This includes specifying elements like street, neighborhood, city, state, country, and postal code, each sent as separate API parameters.'
tags:
- Search / Forward Geocoding
parameters:
- $ref: '#/components/parameters/street'
- $ref: '#/components/parameters/city'
- $ref: '#/components/parameters/county'
- $ref: '#/components/parameters/state'
- $ref: '#/components/parameters/country'
- $ref: '#/components/parameters/postalcode'
- $ref: '#/components/parameters/format'
- $ref: '#/components/parameters/addressdetails-default-0'
- $ref: '#/components/parameters/statecode'
- $ref: '#/components/parameters/viewbox'
- $ref: '#/components/parameters/bounded'
- $ref: '#/components/parameters/limit-max-50'
- $ref: '#/components/parameters/accept-language'
- $ref: '#/components/parameters/countrycodes'
- $ref: '#/components/parameters/normalizeaddress'
- $ref: '#/components/parameters/normalizecity'
- $ref: '#/components/parameters/postaladdress'
- $ref: '#/components/parameters/matchquality'
- $ref: '#/components/parameters/source'
- $ref: '#/components/parameters/normalizeimportance'
- $ref: '#/components/parameters/dedupe-default-1'
- $ref: '#/components/parameters/namedetails'
- $ref: '#/components/parameters/extratags'
- $ref: '#/components/parameters/polygon_geojson'
- $ref: '#/components/parameters/polygon_kml'
- $ref: '#/components/parameters/polygon_svg'
- $ref: '#/components/parameters/polygon_text'
- $ref: '#/components/parameters/json_callback'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/location-forward'
examples:
response:
value:
- place_id: '116136978'
licence: 'https://locationiq.com/attribution'
osm_type: way
osm_id: '34633854'
boundingbox:
- '40.7479255'
- '40.7489585'
- '-73.9865012'
- '-73.9848166'
lat: '40.74844205'
lon: '-73.98565890160751'
display_name: 'Empire State Building, 350, 5th Avenue, Manhattan Community Board 5, Manhattan, New York County, New York, New York, 10001, USA'
class: tourism
type: attraction
importance: 0.8515868466874569
icon: 'https://locationiq.org/static/images/mapicons/poi_point_of_interest.p.20.png'
address:
attraction: Empire State Building
house_number: '350'
road: 5th Avenue
neighbourhood: Manhattan Community Board 5
suburb: Manhattan
county: New York County
city: New York
state: New York
postcode: '10001'
country: United States of America
country_code: us
application/xml:
schema:
$ref: '#/components/schemas/location-forward'
examples:
Example 1:
value: |-
Empire State Building
350
5th Avenue
Manhattan Community Board 5
Manhattan
New York County
New York
New York
10001
United States of America
us
'400':
$ref: '#/components/responses/400Error-search'
'401':
$ref: '#/components/responses/401Error-search'
'403':
$ref: '#/components/responses/403Error-search'
'404':
$ref: '#/components/responses/404Error-search'
'429':
$ref: '#/components/responses/429Error-search'
'500':
$ref: '#/components/responses/500Error-search'
security:
- key: []
x-stoplight:
id: 4uvxh3zt7obcf
parameters: []
/search/postalcode:
get:
operationId: search-postalcode
summary: Postal Code Search
description: Postal Address Lookup streamlines the task of locating details when only a postal code match is necessary. It’s particularly useful when you want to fetch location information without handling complete addresses.
tags:
- Search / Forward Geocoding
parameters:
- $ref: '#/components/parameters/postalcode-required'
- $ref: '#/components/parameters/countrycodes'
- $ref: '#/components/parameters/format'
- $ref: '#/components/parameters/addressdetails-default-0'
- $ref: '#/components/parameters/statecode'
- $ref: '#/components/parameters/viewbox'
- $ref: '#/components/parameters/bounded'
- $ref: '#/components/parameters/limit-max-50'
- $ref: '#/components/parameters/accept-language'
- $ref: '#/components/parameters/normalizeaddress'
- $ref: '#/components/parameters/normalizecity'
- $ref: '#/components/parameters/postaladdress'
- $ref: '#/components/parameters/matchquality'
- $ref: '#/components/parameters/source'
- $ref: '#/components/parameters/normalizeimportance'
- $ref: '#/components/parameters/dedupe-default-1'
- $ref: '#/components/parameters/namedetails'
- $ref: '#/components/parameters/extratags'
- $ref: '#/components/parameters/polygon_geojson'
- $ref: '#/components/parameters/polygon_kml'
- $ref: '#/components/parameters/polygon_svg'
- $ref: '#/components/parameters/polygon_text'
- $ref: '#/components/parameters/json_callback'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/location-forward'
examples:
response:
value:
- place_id: '1528544'
licence: 'https://locationiq.com/attribution'
boundingbox:
- '40.7484'
- '40.7484'
- '-73.9967'
- '-73.9967'
lat: '40.7484'
lon: '-73.9967'
display_name: 'New York, New York, New York, 10001, USA'
class: place
type: postcode
importance: 0.1
address:
suburb: New York
county: New York
state: New York
postcode: '10001'
country: United States of America
country_code: us
town: New York
application/xml:
schema:
$ref: '#/components/schemas/location-forward'
examples:
Example 1:
value: |-
New York
New York
New York
10001
United States of America
us
New York
'400':
$ref: '#/components/responses/400Error-search'
'401':
$ref: '#/components/responses/401Error-search'
'403':
$ref: '#/components/responses/403Error-search'
'404':
$ref: '#/components/responses/404Error-search'
'429':
$ref: '#/components/responses/429Error-search'
'500':
$ref: '#/components/responses/500Error-search'
security:
- key: []
x-stoplight:
id: gkgks2co70se7
parameters: []
/reverse:
get:
operationId: reverse
summary: Reverse Geocoding
description: 'Reverse geocoding is the process of converting a coordinate or location (latitude, longitude) to a readable address or place name. This permits the identification of nearby street addresses, places, and/or area subdivisions such as a neighborhood, county, state, or country.'
tags:
- Reverse
parameters:
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/format'
- $ref: '#/components/parameters/zoom'
- $ref: '#/components/parameters/accept-language'
- $ref: '#/components/parameters/addressdetails-default-1'
- $ref: '#/components/parameters/normalizeaddress'
- $ref: '#/components/parameters/normalizecity'
- $ref: '#/components/parameters/postaladdress'
- $ref: '#/components/parameters/oceans'
- $ref: '#/components/parameters/showdistance'
- $ref: '#/components/parameters/statecode'
- $ref: '#/components/parameters/source'
- $ref: '#/components/parameters/namedetails'
- $ref: '#/components/parameters/extratags'
- $ref: '#/components/parameters/polygon_geojson'
- $ref: '#/components/parameters/polygon_kml'
- $ref: '#/components/parameters/polygon_svg'
- $ref: '#/components/parameters/polygon_text'
- $ref: '#/components/parameters/polygon_threshold'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/location-reverse'
examples:
response:
summary: lat=40.748442 lon=-73.985658
value:
place_id: '116136978'
licence: 'https://locationiq.com/attribution'
osm_type: way
osm_id: '34633854'
lat: '40.74844205'
lon: '-73.98565890160751'
display_name: 'Empire State Building, 350, 5th Avenue, Manhattan Community Board 5, Manhattan, New York County, New York, New York, 10001, USA'
address:
attraction: Empire State Building
house_number: '350'
road: 5th Avenue
neighbourhood: Manhattan Community Board 5
suburb: Manhattan
county: New York County
city: New York
state: New York
postcode: '10001'
country: United States of America
country_code: us
boundingbox:
- '40.7479255'
- '40.7489585'
- '-73.9865012'
- '-73.9848166'
application/xml:
schema:
$ref: '#/components/schemas/location-reverse'
examples:
Example 1:
value: |-
Empire State Building, 350, 5th Avenue, Manhattan Community Board 5, Manhattan, New York County, New York, New York, 10001, USA
Empire State Building
350
5th Avenue
Manhattan Community Board 5
Manhattan
New York County
New York
New York
10001
United States of America
us
headers: {}
'400':
$ref: '#/components/responses/400Error-reverse'
'401':
$ref: '#/components/responses/401Error-reverse'
'403':
$ref: '#/components/responses/403Error-reverse'
'404':
$ref: '#/components/responses/404Error-reverse'
'429':
$ref: '#/components/responses/429Error-reverse'
'500':
$ref: '#/components/responses/500Error-reverse'
security:
- key: []
x-stoplight:
id: k2d7t4cw5d6b4
/autocomplete:
get:
operationId: autocomplete
tags:
- Autocomplete
servers:
- url: 'https://api.locationiq.com/v1'
description: Autocomplete Endpoint
description: |-
The Autocomplete API is a variant of the Search API that returns place predictions in response to an HTTP request. The request specifies a textual search string and optional geographic bounds. The service can be used to provide autocomplete functionality for text-based geographic searches, by returning places such as businesses, addresses and points of interest as a user types.
The Autocomplete API can match on full words as well as substrings. Applications can therefore send queries as the user types, to provide on-the-fly place predictions.
Try this API in our Playground
> If you use Leaflet for your maps, you add LocationIQ's Autocomplete as a plugin instantly! You can view instructions here. You can also view a live demo here.
> The Autocomplete API endpoint (https://api.locationiq.com/v1) offers an Anycast IP address and route user requests to a datacenter closest to them. You can still manually specify a `region` similar to other LocationIQ endpoints, but in the interest of end-user experience, we don't recommended such a configuration.
parameters:
- $ref: '#/components/parameters/query'
- $ref: '#/components/parameters/countrycodes'
- $ref: '#/components/parameters/tag'
- $ref: '#/components/parameters/layers-autocomplete'
- $ref: '#/components/parameters/limit-max-20'
- $ref: '#/components/parameters/viewbox'
- $ref: '#/components/parameters/bounded'
- $ref: '#/components/parameters/json_callback'
- $ref: '#/components/parameters/normalizecity'
- $ref: '#/components/parameters/accept-language-autocomplete'
- $ref: '#/components/parameters/statecode'
- $ref: '#/components/parameters/importancesort'
- $ref: '#/components/parameters/dedupe-default-0'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/location-autocomplete'
examples:
response:
value:
place_id: '321978604508'
osm_id: '34633854'
osm_type: way
licence: 'https://locationiq.com/attribution'
lat: '40.7484284'
lon: '-73.9856546198733'
boundingbox:
- '40.7479226'
- '40.7489422'
- '-73.9864855'
- '-73.9848259'
class: tourism
type: attraction
display_name: 'Empire State Building, 350, 5th Avenue, Korea Town, Midtown South, Manhattan, Manhattan Community Board 5, New York County, New York City, New York, 10001, United States of America'
display_place: Empire State Building
display_address: '350, 5th Avenue, Midtown South, New York City, New York, 10001, USA'
address:
name: Empire State Building
house_number: '350'
road: 5th Avenue
suburb: Midtown South
city: New York City
state: New York
postcode: '10001'
country: United States of America
country_code: us
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'429':
$ref: '#/components/responses/429Error'
'500':
$ref: '#/components/responses/500Error'
security:
- key: []
x-stoplight:
id: h45btk8xk9epc
summary: Autocomplete
parameters: []
/lookup:
get:
operationId: lookup
summary: Lookup
description: 'The lookup API allows querying the address and other details of one or multiple OSM objects, such as nodes, ways, or relations.'
tags:
- Lookup
security:
- key: []
parameters:
- $ref: '#/components/parameters/osm_ids'
- $ref: '#/components/parameters/json_callback'
- $ref: '#/components/parameters/addressdetails-default-1'
- $ref: '#/components/parameters/extratags'
- $ref: '#/components/parameters/namedetails'
- $ref: '#/components/parameters/accept-language'
- $ref: '#/components/parameters/polygon_geojson'
- $ref: '#/components/parameters/polygon_kml'
- $ref: '#/components/parameters/polygon_svg'
- $ref: '#/components/parameters/polygon_text'
- $ref: '#/components/parameters/polygon_threshold'
- $ref: '#/components/parameters/normalizeaddress'
- $ref: '#/components/parameters/normalizecity'
- $ref: '#/components/parameters/postaladdress'
- $ref: '#/components/parameters/statecode'
- $ref: '#/components/parameters/format-only-json'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/lookup'
examples:
response:
value:
place_id: 115462561
licence: 'https://locationiq.com/attribution'
osm_type: way
osm_id: 50637691
boundingbox:
- '52.3994612'
- '52.3996426'
- '13.0479574'
- '13.0481754'
lat: '52.399550700000006'
lon: '13.048066846939687'
display_name: 'Brandenburger Tor, Brandenburger Straße, Historische Innenstadt, Innenstadt, Potsdam, Brandenburg, 14467, Germany'
class: tourism
type: attraction
importance: 0.2940287400552381
address:
tourism: Brandenburger Tor
road: Brandenburger Straße
suburb: Historische Innenstadt
city: Potsdam
state: Brandenburg
postcode: '14467'
country: Germany
country_code: de
extratags:
image: 'http://commons.wikimedia.org/wiki/File:Potsdam_brandenburger_tor.jpg'
heritage: '4'
wikidata: Q695045
architect: Carl von Gontard;Georg Christian Unger
wikipedia: 'de:Brandenburger Tor (Potsdam)'
wheelchair: 'yes'
description: Kleines Brandenburger Tor in Potsdam
'heritage:website': 'http://www.bldam-brandenburg.de/images/stories/PDF/DML%202012/04-p-internet-13.pdf'
'heritage:operator': bldam
'architect:wikidata': Q68768;Q95223
year_of_construction: '1771'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'500':
$ref: '#/components/responses/500Error'
x-stoplight:
id: a26654ef9fd16
'/directions/{profile}/{coordinates}':
get:
operationId: Directions
summary: Directions Service
tags:
- Routing
description: Finds the fastest route between coordinates in the supplied order.
parameters:
- $ref: '#/components/parameters/bearings'
- $ref: '#/components/parameters/radiuses'
- $ref: '#/components/parameters/hints'
- $ref: '#/components/parameters/alternatives'
- $ref: '#/components/parameters/steps'
- $ref: '#/components/parameters/annotations'
- $ref: '#/components/parameters/geometries'
- $ref: '#/components/parameters/overview'
- $ref: '#/components/parameters/continue_straight'
- $ref: '#/components/parameters/waypoints'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/directions-directions'
examples:
response:
value:
code: ok
waypoints:
distance: 159.132824
location:
- -0.161547
- 51.522462
name: Balcombe Street
routes:
legs:
steps: []
weight: 22.7
distance: 104.2
summary: ''
duration: 24.8
weight_name: routability
geometry: k~myHtp^KeA_@aEACCW
weight: 22.6
distance: 104.8
duration: 24.8
'400':
$ref: '#/components/responses/400Error-routing'
'401':
$ref: '#/components/responses/401Error-routing'
'403':
$ref: '#/components/responses/403Error-routing'
'404':
$ref: '#/components/responses/404Error-routing'
'429':
$ref: '#/components/responses/429Error-routing'
'500':
$ref: '#/components/responses/500Error-routing'
security:
- key: []
x-stoplight:
id: gebvck1pw2e2s
parameters:
- $ref: '#/components/parameters/profile'
- $ref: '#/components/parameters/coordinates'
'/optimize/{profile}/{coordinates}':
get:
operationId: Optimize
summary: Optimize Service
tags:
- Routing
description: Optimize API solves the Traveling Salesman Problem(TSP) using a greedy heuristic (farthest-insertion algorithm) for 10 or more waypoints and uses brute force for less than 10 waypoints. The returned path does not have to be the fastest path. As TSP is NP-hard it only returns an approximation. Note that all input coordinates have to be connected for the optimize service to work.
parameters:
- $ref: '#/components/parameters/bearings'
- $ref: '#/components/parameters/radiuses'
- $ref: '#/components/parameters/hints'
- $ref: '#/components/parameters/roundtrip'
- $ref: '#/components/parameters/source-routing'
- $ref: '#/components/parameters/destination-routing'
- $ref: '#/components/parameters/steps'
- $ref: '#/components/parameters/annotations'
- $ref: '#/components/parameters/geometries'
- $ref: '#/components/parameters/overview'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/directions-directions'
examples:
response:
value:
code: ok
waypoints:
distance: 159.132824
location:
- -0.161547
- 51.522462
name: Balcombe Street
routes:
legs:
steps: []
weight: 22.7
distance: 104.2
summary: ''
duration: 24.8
weight_name: routability
geometry: k~myHtp^KeA_@aEACCW
weight: 22.6
distance: 104.8
duration: 24.8
'400':
$ref: '#/components/responses/400Error-routing'
'401':
$ref: '#/components/responses/401Error-routing'
'403':
$ref: '#/components/responses/403Error-routing'
'404':
$ref: '#/components/responses/404Error-routing'
'429':
$ref: '#/components/responses/429Error-routing'
'500':
$ref: '#/components/responses/500Error-routing'
security:
- key: []
x-stoplight:
id: q2676upx3kwy3
parameters:
- $ref: '#/components/parameters/profile'
- $ref: '#/components/parameters/coordinates'
'/matching/{profile}/{coordinates}':
get:
operationId: Matching
summary: Matching Service
tags:
- Routing
description: Matching API matches or snaps given GPS points to the road network in the most plausible way. Please note the request might result multiple sub-traces. Large jumps in the timestamps (> 60s) or improbable transitions lead to trace splits if a complete matching could not be found. The algorithm might not be able to match all points. Outliers are removed if they can not be matched successfully.
parameters:
- $ref: '#/components/parameters/bearings'
- $ref: '#/components/parameters/radiuses'
- $ref: '#/components/parameters/hints'
- $ref: '#/components/parameters/steps'
- $ref: '#/components/parameters/geometries'
- $ref: '#/components/parameters/annotations'
- $ref: '#/components/parameters/overview'
- $ref: '#/components/parameters/timestamps'
- $ref: '#/components/parameters/gaps'
- $ref: '#/components/parameters/tidy'
- $ref: '#/components/parameters/waypoints'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/directions-matching'
examples:
response:
value:
code: ok
tracepoints:
waypoint_index: 0
matchings_index: 0
alternatives_count: 0
distance: 8.414822
location:
- -0.161136
- 51.523832
name: Huntsworth Mews
matchings:
duration: 109.3
distance: 752.4
weight: 109.3
geometry: '}fnyHbn^|@_@O_BeDlAw@}G~@uB@WXs@fE}Ab@OxBpU'
confidence: 0
weight_name: routability
legs:
steps: []
weight: 10.2
distance: 36.7
summary: ''
duration: 10.2
'400':
$ref: '#/components/responses/400Error-routing'
'401':
$ref: '#/components/responses/401Error-routing'
'403':
$ref: '#/components/responses/403Error-routing'
'404':
$ref: '#/components/responses/404Error-routing'
'429':
$ref: '#/components/responses/429Error-routing'
'500':
$ref: '#/components/responses/500Error-routing'
security:
- key: []
x-stoplight:
id: u5q1uzl506fak
parameters:
- $ref: '#/components/parameters/profile'
- $ref: '#/components/parameters/coordinates'
'/matrix/{profile}/{coordinates}':
get:
operationId: Matrix
summary: Matrix Service
tags:
- Routing
description: 'Computes duration of the fastest route between all pairs of supplied coordinates. Returns the durations or distances or both between the coordinate pairs. Note that the distances are not the shortest distance between two coordinates, but rather the distances of the fastest routes.'
parameters:
- $ref: '#/components/parameters/bearings'
- $ref: '#/components/parameters/radiuses'
- $ref: '#/components/parameters/hints'
- $ref: '#/components/parameters/sources'
- $ref: '#/components/parameters/destinations'
- $ref: '#/components/parameters/annotations'
- $ref: '#/components/parameters/fallback_speed'
- $ref: '#/components/parameters/fallback_coordinate'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/directions-matrix'
examples:
response:
value:
code: ok
fallback_speed_cells: []
distances:
- 392.9
sources:
distance: 159.132824
location:
- -0.161547
- 51.522462
name: Balcombe Street
destinations:
distance: 158.798387
location:
- -0.159453
- 51.522045
name: ''
'400':
$ref: '#/components/responses/400Error-routing'
'401':
$ref: '#/components/responses/401Error-routing'
'403':
$ref: '#/components/responses/403Error-routing'
'404':
$ref: '#/components/responses/404Error-routing'
'429':
$ref: '#/components/responses/429Error-routing'
'500':
$ref: '#/components/responses/500Error-routing'
security:
- key: []
x-stoplight:
id: eby0stka8wh3d
parameters:
- $ref: '#/components/parameters/profile'
- $ref: '#/components/parameters/coordinates'
'/nearest/{profile}/{coordinates}':
get:
operationId: Nearest
summary: Nearest Service
tags:
- Routing
description: 'Snaps a coordinate to the street network and returns the nearest n matches. Where coordinates only supports a single {longitude},{latitude} entry.'
parameters:
- $ref: '#/components/parameters/bearings'
- $ref: '#/components/parameters/radiuses'
- $ref: '#/components/parameters/hints'
- $ref: '#/components/parameters/number'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/directions-nearest'
examples:
response:
value:
waypoints:
nodes:
- 2966517546
- 0
distance: 159.132824
location:
- -0.161547
- 51.522462
name: Balcombe Street
code: ok
'400':
$ref: '#/components/responses/400Error-routing'
'401':
$ref: '#/components/responses/401Error-routing'
'403':
$ref: '#/components/responses/403Error-routing'
'404':
$ref: '#/components/responses/404Error-routing'
'429':
$ref: '#/components/responses/429Error-routing'
'500':
$ref: '#/components/responses/500Error-routing'
security:
- key: []
x-stoplight:
id: rfmravnv1lehu
parameters:
- $ref: '#/components/parameters/profile'
- $ref: '#/components/parameters/coordinates'
/nearby:
get:
summary: Nearby - Places (Public BETA)
tags:
- Nearby
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/location-nearby'
examples:
Example 1:
value:
- place_id: '423028398818'
osm_type: way
osm_id: '34633854'
lat: '40.7484284'
lon: '-73.98565462'
class: tourism
type: attraction
tag_type: attraction
name: Empire State Building
display_name: 'Empire State Building, 350, 5th Avenue, Korea Town, Midtown South, New York, New York, 10001, United States of America'
address:
name: Empire State Building
house_number: '350'
road: 5th Avenue
neighbourhood: Korea Town
suburb: Midtown South
city: New York
state: New York
postcode: '10001'
country: United States of America
country_code: us
boundingbox:
- '40.7479226'
- '40.7489422'
- '-73.9864855'
- '-73.9848259'
distance: 1
- place_id: '423629875658'
osm_type: node
osm_id: '5190610589'
lat: '40.7483271'
lon: '-73.9856549'
class: tourism
type: attraction
tag_type: attraction
name: NY Skyride
display_name: 'NY Skyride, 350, 5th Avenue, Korea Town, Midtown South, New York, New York, 10001, United States of America'
address:
name: NY Skyride
house_number: '350'
road: 5th Avenue
neighbourhood: Korea Town
suburb: Midtown South
city: New York
state: New York
postcode: '10001'
country: United States of America
country_code: us
boundingbox:
- '40.7483271'
- '40.7483271'
- '-73.9856549'
- '-73.9856549'
distance: 9
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'429':
$ref: '#/components/responses/429Error'
'500':
$ref: '#/components/responses/500Error'
operationId: nearby
x-stoplight:
id: gpol02h04m5pb
description: |-
The Nearby API returns nearby places around a specified location.
Results can include points of interest such as cafes, hospitals, and airports, as well as place-level features such as cities, depending on the requested `tag`.
Note: The Nearby API endpoint is presently in BETA. The request or response format may change without notice. While we don't expect to remove any elements, there will be additions.
parameters:
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/tag-nearby'
- $ref: '#/components/parameters/radius'
- $ref: '#/components/parameters/limit-max-50'
- $ref: '#/components/parameters/dedupe-default-0'
security:
- key: []
/timezone:
get:
summary: Timezone
tags:
- Timezone
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/timezone'
examples:
Example 1:
value:
timezone:
name: Asia/Kolkata
now_in_dst: 0
offset_sec: 19800
short_name: IST
full_name: India Standard Time
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'404':
$ref: '#/components/responses/404Error'
'429':
$ref: '#/components/responses/429Error'
'500':
$ref: '#/components/responses/500Error'
operationId: get-timezone
x-stoplight:
id: r2247kyww7h3n
description: The Timezone API provides time offset data for locations on the surface of the earth.
parameters:
- $ref: '#/components/parameters/lat'
- $ref: '#/components/parameters/lon'
- $ref: '#/components/parameters/timestamp'
security:
- key: []
/balance:
get:
operationId: balance
tags:
- Balance
description: 'The Balance API provides a count of request credits left in the user''s account for the day. Balance is reset at midnight UTC every day (00:00 UTC).'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/balance'
examples:
response:
value:
status: ok
balance:
day: 30000
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
'429':
$ref: '#/components/responses/429Error'
'500':
$ref: '#/components/responses/500Error'
security:
- key: []
x-stoplight:
id: xmqiqrdeoq51q
summary: Balance
parameters: []
servers:
- url: 'https://us1.locationiq.com/v1'
description: US Region Endpoint
- url: 'https://eu1.locationiq.com/v1'
description: EU Region Endpoint
- url: 'https://api.locationiq.com/v1'
description: Autocomplete only Endpoint
components:
securitySchemes:
key:
name: key
type: apiKey
in: query
description: LocationIQ Access Token
schemas:
namedetails:
type: object
x-examples:
Example 1:
name: Empire State Building
'name:en': Empire State Building
'name:es': Edificio Empire State
'name:he': בניין אמפייר סטייט
'name:hi': एम्पायर स्टेट बिल्डिंग
'name:ko': 엠파이어 스테이트 빌딩
'name:ru': Эмпайр-Стейт-Билдинг
'name:uk': Емпайр-Стейт-Білдінг
'name:zh': 帝国大厦
properties:
name:
type: string
description: |
The dictionary with full list of available names including ref etc. Returned when `namedetails=1` is set in the request.
address:
title: address
type: object
example:
house_number: '3894'
road: Spring Mill Way
residential: Hunter’s Point
village: Landen
city: Landen
county: Warren County
state: Ohio
postcode: '45039'
country: United States of America
country_code: us
state_code: oh
description: |-
Breakdown of the address into elements.
All these elements are optional and only those elements that are available for a given location will be returned.
properties:
house_number:
type: string
description: House number
road:
type: string
description: Road name
neighbourhood:
type: string
description: Neighbourhood
hamlet:
type: string
description: Hamlet
suburb:
type: string
description: Suburb
village:
type: string
description: Village name
town:
type: string
description: Town name
city_district:
type: string
description: Administrative area between city level and town level
city:
type: string
description: City name
region:
type: string
description: Region name
county:
type: string
description: County name
state_district:
type: string
description: District name
state:
type: string
description: State name
state_code:
type: string
description: State code
postcode:
type: string
description: Postal code
country:
type: string
description: Country name
country_code:
type: string
description: Country code
name:
type: string
description: Name of the entity/road in the given location
water:
type: string
x-stoplight:
id: 7nunw3epqpcqo
description: 'The name of an ocean or sea, if the location falls within a body of water outside any country''s administrative regions.'
x-examples:
Example 1:
house_number: '3894'
road: Spring Mill Way
residential: Hunter’s Point
village: Landen
city: Landen
county: Warren County
state: Ohio
postcode: '45039'
country: United States of America
country_code: us
state_code: oh
Result from Ocean:
house_number: '3894'
road: Spring Mill Way
residential: Hunter’s Point
village: Landen
city: Landen
county: Warren County
state: Ohio
postcode: '45039'
country: United States of America
country_code: us
state_code: oh
Example 2:
name: South Pacific Ocean
water: South Pacific Ocean
address-normalized:
title: address-normalized
x-stoplight:
id: q798lnglnqkb4
type: object
example:
house_number: '3894'
road: Spring Mill Way
residential: Hunter’s Point
village: Landen
city: Landen
county: Warren County
state: Ohio
postcode: '45039'
country: United States of America
country_code: us
state_code: oh
description: |
The default address section returns a wide range of elements - from common ones such as `road` and `country` to obscure ones such as `hamlet`, `cycleway`, `park`. This was done to maintain backward compatibility with OpenStreetMap's Nominatim. To make parsing easier for developers, the `normalizeaddress` parameter rolls up elements in the `address` section of the response to the list of elements defined below.
properties:
name:
type: string
description: House name or Point of Interest (POI)
house_number:
type: string
description: House or Building number
road:
type: string
description: 'Roads, Highways, Freeways, Motorways'
neighbourhood:
type: string
description: 'Neighbourhoods, Allotments, Quarters, Communities'
suburb:
type: string
description: 'Suburbs, Subdivisions'
island:
type: string
description: 'Islands, Islets'
city:
type: string
description: 'Cities, Towns, Villages, Municipalities, Districts, Boroughs, Hamlets'
county:
type: string
description: Counties
state:
type: string
description: 'States, Provinces, Regions, State Districts'
state_code:
type: string
description: State or Province Code
postcode:
type: string
description: 'Postal Codes, Zipcodes'
country:
type: string
description: 'Countries, Nation-states'
country_code:
type: string
description: Country Code - 2 letter (ISO 3166-1 alpha-2)
x-examples:
Example 1:
name: Empire State Building
house_number: '350'
road: 5th Avenue
neighbourhood: Manhattan Community Board 5
suburb: Manhattan
city: New York
county: New York County
state: New York
postcode: '10001'
country: United States of America
country_code: us
Result from Ocean:
name: South Pacific Ocean
Example 2:
name: South Pacific Ocean
address-autocomplete:
title: address-autocomplete
x-stoplight:
id: ne9kgzxgg54ig
type: object
example:
house_number: '3894'
road: Spring Mill Way
residential: Hunter’s Point
village: Landen
city: Landen
county: Warren County
state: Ohio
postcode: '45039'
country: United States of America
country_code: us
state_code: oh
description: |-
Breakdown of the address into elements.
All these elements are optional and only those elements that are available for a given location will be returned.
x-examples:
Example 1:
name: Empire State Building
house_number: '350'
road: 5th Avenue
neighbourhood: Manhattan Community Board 5
suburb: Manhattan
city: New York
county: New York County
state: New York
postcode: '10001'
country: United States of America
country_code: us
Result from Ocean:
name: South Pacific Ocean
Example 2:
name: South Pacific Ocean
properties:
name:
type: string
description: House name or Point of Interest (POI)
house_number:
type: string
description: House or Building number
road:
type: string
description: 'Roads, Highways, Freeways, Motorways'
neighbourhood:
type: string
description: 'Neighbourhoods, Allotments, Quarters, Communities'
suburb:
type: string
description: 'Suburbs, Subdivisions'
city:
type: string
description: 'Cities, Towns, Villages, Municipalities, Districts, Boroughs, Hamlets'
county:
type: string
description: Counties
state:
type: string
description: 'States, Provinces, Regions, State Districts'
state_code:
type: string
description: State or Province Code
postcode:
type: string
description: 'Postal Codes, Zipcodes'
country:
type: string
description: 'Countries, Nation-states'
country_code:
type: string
description: Country Code - 2 letter (ISO 3166-1 alpha-2)
address-nearby:
title: address-nearby
x-stoplight:
id: tbe7xjx22s96f
type: object
example:
house_number: '3894'
road: Spring Mill Way
residential: Hunter’s Point
village: Landen
city: Landen
county: Warren County
state: Ohio
postcode: '45039'
country: United States of America
country_code: us
state_code: oh
description: |-
Breakdown of the address into elements.
All these elements are optional and only those elements that are available for a given location will be returned.
x-examples:
Example 1:
name: Empire State Building
house_number: '350'
road: 5th Avenue
neighbourhood: Manhattan Community Board 5
suburb: Manhattan
city: New York
county: New York County
state: New York
postcode: '10001'
country: United States of America
country_code: us
Result from Ocean:
name: South Pacific Ocean
Example 2:
name: South Pacific Ocean
properties:
name:
type: string
description: House name or Point of Interest (POI)
house_number:
type: string
description: House or Building number
road:
type: string
description: 'Roads, Highways, Freeways, Motorways'
neighbourhood:
type: string
description: 'Neighbourhoods, Allotments, Quarters, Communities'
suburb:
type: string
description: 'Suburbs, Subdivisions'
city:
type: string
description: 'Cities, Towns, Villages, Municipalities, Districts, Boroughs, Hamlets'
county:
type: string
description: Counties
state:
type: string
description: 'States, Provinces, Regions, State Districts'
state_code:
type: string
description: State or Province Code
postcode:
type: string
description: 'Postal Codes, Zipcodes'
country:
type: string
description: 'Countries, Nation-states'
country_code:
type: string
description: Country Code - 2 letter (ISO 3166-1 alpha-2)
balance:
title: balance
type: object
example:
status: ok
balance:
day: 547933
bonus: 123
properties:
status:
type: string
description: |
`ok` on success.
balance:
$ref: '#/components/schemas/daybalance'
x-examples:
Example 1:
status: ok
balance:
day: 30000
bonus: 0
daybalance:
title: daybalance
type: object
description: An array comprising individual components such as `day` and `bonus`.
properties:
day:
type: integer
description: Balance of requests credits in your account for the day.
bonus:
type: integer
description: Balance of bonus / promotional request credits in your account.
x-examples:
Example 1:
day: 30000
bonus: 0
error:
title: error
type: object
properties:
error:
type: string
example:
error: Invalid key
error-routing:
title: error
x-stoplight:
id: b9c442d5d14ed
type: object
properties:
code:
type: string
example:
error: Invalid key
x-examples:
Example 1:
code: Invalid key
location-reverse:
title: location-reverse-geocoding
x-stoplight:
id: 7039d5df8864b
type: object
example:
place_id: '223483692'
licence: '© LocationIQ.com CC BY 4.0, Data © OpenStreetMap contributors, ODbL 1.0'
osm_type: way
osm_id: '19301621'
boundingbox:
- '39.307405567782'
- '39.307505567782'
- '-84.292824851595'
- '-84.292724851595'
lat: '39.3074555677816'
lon: '-84.2927748515948'
display_name: '3894, Spring Mill Way, Hunter’s Point, Landen, Warren County, Ohio, 45039, United States of America'
class: place
type: house
importance: 0.62025
address:
name: Empire State Building
house_number: '3894'
road: Spring Mill Way
residential: Hunter’s Point
village: Landen
county: Warren County
state: Ohio
postcode: '45039'
country: United States of America
country_code: us
city: Landen
properties:
place_id:
type: string
description: Unique identifier for the place.
licence:
type: string
description: License information for the data.
osm_type:
type: string
description: Type of the OpenStreetMap object. Omitted for results sourced from non-OSM datasets.
osm_id:
type: string
description: Unique identifier for the OpenStreetMap object. Omitted for results sourced from non-OSM datasets.
lat:
type: string
description: Latitude of the location.
lon:
type: string
description: Longitude of the location.
display_name:
type: string
description: Formatted address for display.
address:
anyOf:
- $ref: '#/components/schemas/address'
- $ref: '#/components/schemas/address-normalized'
boundingbox:
type: array
description: 'List of bounding box coordinates [min_lat, max_lat, min_lon, max_lon].'
items:
type: string
distance:
$ref: '#/components/schemas/distance'
namedetails:
$ref: '#/components/schemas/namedetails'
extratags:
$ref: '#/components/schemas/extratags'
geojson:
$ref: '#/components/schemas/geojson'
geokml:
$ref: '#/components/schemas/geokml'
svg:
$ref: '#/components/schemas/svg'
geotext:
$ref: '#/components/schemas/geotext'
postaladdress:
$ref: '#/components/schemas/postaladdress'
required:
- place_id
- licence
- lat
- lon
- display_name
- boundingbox
location-forward:
title: location-forward-geocoding
x-stoplight:
id: 360vfacsuwhfx
type: array
items:
type: object
properties:
place_id:
type: string
description: Unique identifier for the place.
licence:
type: string
description: License information for the data.
osm_type:
type: string
description: Type of the OpenStreetMap object. Omitted for results sourced from non-OSM datasets.
osm_id:
type: string
description: Unique identifier for the OpenStreetMap object. Omitted for results sourced from non-OSM datasets.
lat:
type: string
description: Latitude of the location.
lon:
type: string
description: Longitude of the location.
display_name:
type: string
description: Formatted address for display.
class:
type: string
description: The category of this result
type:
type: string
description: The 'type' of the class/category of this result
importance:
type: number
description: Calculated importance of this result compared to the search query the user has provided. Ranges between 0 and 1.
format: float
address:
anyOf:
- $ref: '#/components/schemas/address'
- $ref: '#/components/schemas/address-normalized'
boundingbox:
type: array
description: 'List of bounding box coordinates [min_lat, max_lat, min_lon, max_lon].'
items:
type: string
namedetails:
$ref: '#/components/schemas/namedetails'
extratags:
$ref: '#/components/schemas/extratags'
geojson:
$ref: '#/components/schemas/geojson'
geokml:
$ref: '#/components/schemas/geokml'
svg:
$ref: '#/components/schemas/svg'
geotext:
$ref: '#/components/schemas/geotext'
icon:
type: string
x-stoplight:
id: udpck9wsvlgou
description: 'The URL of an icon representing this result, if applicable.'
matchquality:
$ref: '#/components/schemas/matchquality'
postaladdress:
$ref: '#/components/schemas/postaladdress'
required:
- place_id
- licence
- lat
- lon
- display_name
- boundingbox
description: ''
x-examples:
Example 1:
- place_id: '223483692'
licence: '© LocationIQ.com CC BY 4.0, Data © OpenStreetMap contributors, ODbL 1.0'
osm_type: way
osm_id: '19301621'
boundingbox:
- '39.307405567782'
- '39.307505567782'
- '-84.292824851595'
- '-84.292724851595'
lat: '39.3074555677816'
lon: '-84.2927748515948'
display_name: '3894, Spring Mill Way, Hunter’s Point, Landen, Warren County, Ohio, 45039, United States of America'
class: place
type: house
importance: 0.62025
address:
name: Empire State Building
house_number: '3894'
road: Spring Mill Way
residential: Hunter’s Point
village: Landen
county: Warren County
state: Ohio
postcode: '45039'
country: United States of America
country_code: us
city: Landen
location-nearby:
title: location-nearby-poi
x-stoplight:
id: gpmrvu628jbn5
type: array
x-examples:
Example 1:
- place_id: '223483692'
licence: '© LocationIQ.com CC BY 4.0, Data © OpenStreetMap contributors, ODbL 1.0'
osm_type: way
osm_id: '19301621'
boundingbox:
- '39.307405567782'
- '39.307505567782'
- '-84.292824851595'
- '-84.292724851595'
lat: '39.3074555677816'
lon: '-84.2927748515948'
display_name: '3894, Spring Mill Way, Hunter’s Point, Landen, Warren County, Ohio, 45039, United States of America'
class: place
type: house
importance: 0.62025
address:
name: Empire State Building
house_number: '3894'
road: Spring Mill Way
residential: Hunter’s Point
village: Landen
county: Warren County
state: Ohio
postcode: '45039'
country: United States of America
country_code: us
city: Landen
items:
type: object
properties:
place_id:
type: string
description: Unique identifier for the place.
licence:
type: string
description: License information for the data.
osm_type:
type: string
description: Type of the OpenStreetMap object. Omitted for results sourced from non-OSM datasets.
osm_id:
type: string
description: Unique identifier for the OpenStreetMap object. Omitted for results sourced from non-OSM datasets.
lat:
type: string
description: Latitude of the location.
lon:
type: string
description: Longitude of the location.
display_name:
type: string
description: Formatted address for display.
class:
type: string
description: The category of this result
type:
type: string
description: The 'type' of the class/category of this result
address:
$ref: '#/components/schemas/address-nearby'
boundingbox:
type: array
description: 'List of bounding box coordinates [min_lat, max_lat, min_lon, max_lon].'
items:
type: string
required:
- place_id
- licence
- lat
- lon
- display_name
- boundingbox
location-autocomplete:
title: location-autocomplete
x-stoplight:
id: 05c483aae353e
type: array
items:
type: object
properties:
place_id:
type: string
description: Unique identifier for the place.
osm_id:
type: string
description: Unique identifier for the OpenStreetMap object. Omitted for results sourced from non-OSM datasets.
osm_type:
type: string
description: Type of the OpenStreetMap object. Omitted for results sourced from non-OSM datasets.
licence:
type: string
description: License information for the data.
lat:
type: string
description: Latitude of the location.
lon:
type: string
description: Longitude of the location.
boundingbox:
type: array
description: 'List of bounding box coordinates [min_lat, max_lat, min_lon, max_lon].'
items:
type: string
class:
type: string
description: The category of this result
type:
type: string
description: The 'type' of the class/category of this result
display_name:
type: string
description: Formatted address for display.
display_place:
type: string
description: 'Only the name part of the address; if the `type` is a `city`, just the city''s name. If the `type` is `highway`, just the road''s name. This is helpful when a client library wants to display this information separately.'
display_address:
type: string
description: The complete address without the text already present in `display_place`.
address:
$ref: '#/components/schemas/address-autocomplete'
x-examples:
Example 1:
- place_id: '322123240136'
osm_id: '34633854'
osm_type: way
licence: 'https://locationiq.com/attribution'
lat: '40.7484284'
lon: '-73.98565462'
boundingbox:
- '40.7479226'
- '40.7489422'
- '-73.9864855'
- '-73.9848259'
class: office
type: 'yes'
display_name: 'Empire State Building, 350, 5th Avenue, Midtown South, Manhattan, New York, New York, 10001, USA'
display_place: Empire State Building
display_address: '350, 5th Avenue, Midtown South, Manhattan, New York, New York, 10001, USA'
address:
name: Empire State Building
house_number: '350'
road: 5th Avenue
neighbourhood: Midtown South
suburb: Manhattan
city: New York
state: New York
postcode: '10001'
country: United States of America
country_code: us
waypoints:
type: array
description: Object used to describe waypoint on a route.
items:
type: object
properties:
hint:
type: string
x-stoplight:
id: to7sli9hdk2jt
description: 'The distance, in meters, from the input coordinate to the snapped coordinate.'
distance:
type: number
description: 'The distance, in meters, from the input coordinate to the snapped coordinate.'
name:
type: string
x-stoplight:
id: 5vuo71t8c0zy4
description: |-
Unique internal identifier of the segment (ephemeral, not constant over data updates)
This can be used on subsequent request to significantly speed up the query and to connect multiple services.
E.g. you can use the `hint` value obtained by the `nearest` query as `hint` values for `route` inputs.
location:
type: array
description: 'Array that contains the `[longitude, latitude]` pair of the snapped coordinate.'
items:
type: number
directions_route_legs:
type: array
description: Represents a route between two waypoints.
items:
type: object
properties:
steps:
type: array
description: |-
A step consists of a maneuver such as a turn or merge, followed
by a distance of travel along a single way to the subsequent
step.
Depends on the `steps` parameter.
| steps | |
|--------------|-----------------------------------------------------------------------|
| true | array of `RouteStep` objects describing the turn-by-turn instructions |
| false | empty array |
items:
type: object
properties:
intersections:
type: object
description: |-
An intersection gives a full representation of any cross-way the path passes bay. For every step, the very first intersection (`intersections[0]`) corresponds to the
location of the StepManeuver. Further intersections are listed for every cross-way until the next turn instruction.
properties:
location:
type: array
description: 'A `[longitude, latitude]` pair describing the location of the turn.'
items:
type: number
in:
type: number
x-stoplight:
id: lskt57vdr20n9
description: |-
index into bearings/entry array. Used to calculate the bearing just before the turn. Namely, the clockwise angle from true north to the
direction of travel immediately before the maneuver/passing the intersection. Bearings are given relative to the intersection. To get the bearing
in the direction of driving, the bearing has to be rotated by a value of 180. The value is not supplied for `depart` maneuvers.
out:
type: number
description: |-
index into the bearings/entry array. Used to extract the bearing just after the turn. Namely, The clockwise angle from true north to the
direction of travel immediately after the maneuver/passing the intersection. The value is not supplied for `arrive` maneuvers.
bearings:
type: number
description: 'A list of bearing values (e.g. [0,90,180,270]) that are available at the intersection. The bearings describe all available roads at the intersection. Values are between 0-359 (0=true north)'
entry:
type: string
description: |-
A list of entry flags, corresponding in a 1:1 relationship to the bearings. A value of `true` indicates that the respective road could be entered on a valid route.
`false` indicates that the turn onto the respective road would violate a restriction.
classes:
type: array
x-stoplight:
id: 8eciacki4fjia
description: An array of strings signifying the classes (as specified in the profile) of the road exiting the intersection.
items:
x-stoplight:
id: zl73uiawtykik
type: string
lanes:
type: array
x-stoplight:
id: cbz5c1js7urfb
description: A `Lane` represents a turn lane at the corresponding turn location.
items:
x-stoplight:
id: 2belpw9ad3exo
type: object
properties:
indications:
type: string
x-stoplight:
id: c4au3wfzuqkb3
description: |-
An indication (e.g. marking on the road) specifying the turn lane. A road can have multiple indications (e.g. an arrow pointing straight and left). The indications are given in an array, each containing one of the following types. Further indications might be added on without an API version change.
| `value` | Description |
|------------------------|---------------------------------------------------------------------------------------------------------------------------|
| `none` | No dedicated indication is shown. |
| `uturn` | An indication signaling the possibility to reverse (i.e. fully bend arrow). |
| `sharp right` | An indication indicating a sharp right turn (i.e. strongly bend arrow). |
| `right` | An indication indicating a right turn (i.e. bend arrow). |
| `slight right` | An indication indicating a slight right turn (i.e. slightly bend arrow). |
| `straight` | No dedicated indication is shown (i.e. straight arrow). |
| `slight left` | An indication indicating a slight left turn (i.e. slightly bend arrow). |
| `left` | An indication indicating a left turn (i.e. bend arrow). |
| `sharp left` | An indication indicating a sharp left turn (i.e. strongly bend arrow). |
valid:
type: string
x-stoplight:
id: rm2ay92cpk5dn
description: A boolean flag (represented as `string`) indicating whether the lane is a valid choice in the current maneuver.
driving_side:
type: string
description: The legal driving side at the location for this step. Either `left` or `right`.
geometry:
type: string
description: |-
The unsimplified geometry of the route segment, depending on the `geometries` parameter.
| `geometry` | |
|------------|--------------------------------------------------------------------|
| polyline | [polyline](https://www.npmjs.com/package/polyline) with precision 5 in [latitude,longitude] encoding |
| polyline6 | [polyline](https://www.npmjs.com/package/polyline) with precision 6 in [latitude,longitude] encoding |
| geojson | [GeoJSON `LineString`](http://geojson.org/geojson-spec.html#linestring) |
duration:
type: number
description: 'The estimated travel time, in `float` number of seconds.'
distance:
type: number
description: 'The distance of travel from the maneuver to the subsequent step, in `float` meters.'
name:
type: string
description: The name of the way along which travel proceeds.
weight:
type: number
description: The calculated weight of the step.
mode:
type: string
description: A string signifying the mode of transportation.
maneuver:
type: array
description: A `StepManeuver` object representing the maneuver.
items:
type: object
properties:
bearing_after:
type: number
description: |-
The clockwise angle from true north to the
direction of travel immediately after the maneuver. Range 0-359.
location:
type: array
description: 'A `[longitude, latitude]` pair describing the location of the turn.'
items:
type: number
type:
type: string
description: |-
A string indicating the type of maneuver. **new identifiers might be introduced without API change**
| `type` | Description |
|------------------|--------------------------------------------------------------|
| `turn` | a basic turn into direction of the `modifier` |
| `new name` | no turn is taken/possible, but the road name changes. The road can take a turn itself, following `modifier`. |
| `depart` | indicates the departure of the leg |
| `arrive` | indicates the destination of the leg |
| `merge` | merge onto a street (e.g. getting on the highway from a ramp, the `modifier specifies the direction of the merge`) |
| `ramp` | **Deprecated**. Replaced by `on_ramp` and `off_ramp`. |
| `on ramp` | take a ramp to enter a highway (direction given my `modifier`) |
| `off ramp` | take a ramp to exit a highway (direction given my `modifier`) |
| `fork` | take the left/right side at a fork depending on `modifier` |
| `end of road` | road ends in a T intersection turn in direction of `modifier`|
| `use lane` | **Deprecated** replaced by lanes on all intersection entries |
| `continue` | Turn in direction of `modifier` to stay on the same road |
| `roundabout` | traverse roundabout, if the route leaves the roundabout there will be an additional property `exit` for exit counting. The modifier specifies the direction of entering the roundabout. |
| `rotary` | a traffic circle. While very similar to a larger version of a roundabout, it does not necessarily follow roundabout rules for right of way. It can offer `rotary_name` and/or `rotary_pronunciation` parameters (located in the RouteStep object) in addition to the `exit` parameter (located on the StepManeuver object). |
| `roundabout turn`| Describes a turn at a small roundabout that should be treated as normal turn. The `modifier` indicates the turn direction. Example instruction: `At the roundabout turn left`. |
| `notification` | not an actual turn but a change in the driving conditions. For example the travel mode or classes. If the road takes a turn itself, the `modifier` describes the direction |
| `exit roundabout`| Describes a maneuver exiting a roundabout (usually preceded by a `roundabout` instruction) |
| `exit rotary` | Describes the maneuver exiting a rotary (large named roundabout) |
bearing_before:
type: number
description: |-
he clockwise angle from true north to the
direction of travel immediately before the maneuver. Range 0-359.
modifier:
type: string
description: |-
An optional `string` indicating the direction change of the maneuver.
| `modifier` | Description |
|-------------------|-------------------------------------------|
| `uturn` | indicates reversal of direction |
| `sharp right` | a sharp right turn |
| `right` | a normal turn to the right |
| `slight right` | a slight turn to the right |
| `straight` | no relevant change in direction |
| `slight left` | a slight turn to the left |
| `left` | a normal turn to the left |
| `sharp left` | a sharp turn to the left |
The list of turns without a modifier is limited to: `depart/arrive`. If the source/target location is close enough to the `depart/arrive` location, no modifier will be given.
The meaning depends on the `type` property.
| `type` | Description |
|------------------------|---------------------------------------------------------------------------------------------------------------------------|
| `turn` | `modifier` indicates the change in direction accomplished through the turn |
| `depart`/`arrive` | `modifier` indicates the position of departure point and arrival point in relation to the current direction of travel |
- `exit` An optional `integer` indicating number of the exit to take. The property exists for the `roundabout` / `rotary` property:
Number of the roundabout exit to take. If exit is `undefined` the destination is on the roundabout.
New properties (potentially depending on `type`) may be introduced in the future without an API version change.
ref:
type: string
description: 'A reference number or code for the way. Optionally included, if ref data is available for the given way.'
weight:
type: number
description: The calculated weight of the route leg.
distance:
type: number
description: |
The distance traveled by this route leg, in `float` meters.
annotations:
type: object
description: |
Additional details about each coordinate along the route geometry, with fine-grained information about each segment or node id.
| annotations | |
|--------------|-------------------------------------------------------------------------------|
| true | An `Annotation` object containing node ids, durations, distances and weights. |
| false | `undefined` |
properties:
speed:
type: array
description: 'Convenience field, calculation of `distance / duration` rounded to one decimal place.'
items:
type: number
metadata:
type: object
description: Metadata related to other annotations.
properties:
datasource_names:
type: array
description: 'The names of the datasources used for the speed between each pair of coordinates. `lua profile` is the default profile, other values are the filenames supplied via `--segment-speed-file` to `osrm-contract` or `osrm-customize`.'
items:
type: string
nodes:
type: array
description: 'The OSM node ID for each coordinate along the route, excluding the first/last user-supplied coordinates.'
items:
type: number
duration:
type: array
description: 'The duration between each pair of coordinates, in seconds. Does not include the duration of any turns.'
items:
type: number
distance:
type: array
description: 'The distance, in meters, between each pair of coordinates.'
items:
type: number
weight:
type: array
description: The weights between each pair of coordinates. Does not include any turn costs.
items:
type: number
datasources:
type: array
description: 'The index of the datasource for the speed between each pair of coordinates. `0` is the default profile, other values are supplied via `--segment-speed-file` to `osrm-contract` or `osrm-customize`. String-like names are in the `metadata.datasource_names` array.'
items:
type: number
summary:
type: string
description: |-
Summary of the route taken as `string`. Depends on the `summary` parameter.
| summary | |
|--------------|-----------------------------------------------------------------------|
| true | Names of the two major roads used. Can be empty if route is too short.|
| false | empty `string` |
duration:
type: string
description: 'The estimated travel time, in `float` number of seconds.'
matchings_route_legs:
type: array
items:
type: object
properties:
steps:
type: array
items:
type: object
properties:
intersections:
type: object
properties:
out:
type: number
entry:
type: string
location:
type: array
items:
type: number
bearings:
type: number
driving_side:
type: string
geometry:
type: string
duration:
type: number
distance:
type: number
name:
type: string
weight:
type: number
mode:
type: string
maneuver:
type: array
items:
type: object
properties:
bearing_after:
type: number
location:
type: array
items:
type: number
type:
type: string
bearing_before:
type: number
modifier:
type: string
ref:
type: string
weight:
type: number
distance:
type: number
summary:
type: string
duration:
type: string
matching_tracepoints:
type: array
description: |-
Array of `Waypoint` objects representing all points of the trace in order.
If the trace point was omitted by map matching because it is an outlier, the entry will be `null`.
items:
type: object
properties:
waypoint_index:
type: integer
description: Index of the waypoint inside the matched route.
matchings_index:
type: integer
description: Index to the `Route` object in `matchings` the sub-trace was matched to.
alternatives_count:
type: integer
description: Number of probable alternative matchings for this trace point. A value of zero indicate that this point was matched unambiguously. Split the trace at these points for incremental map matching.
distance:
type: number
location:
type: array
items:
type: number
name:
type: string
matching_matchings:
type: array
description: An array of `Route` objects that assemble the trace.
items:
type: object
properties:
duration:
type: number
distance:
type: number
weight:
type: number
geometry:
type: string
confidence:
type: number
description: Confidence of the matching. `float` value between 0 and 1. 1 is very confident that the matching is correct.
weight_name:
type: string
legs:
$ref: '#/components/schemas/matchings_route_legs'
directions-directions:
title: Directions
type: object
x-examples:
Example 1:
code: string
waypoints:
- distance: 0
location:
- 0
routes: []
properties:
code:
type: string
description: If the request was successful `Ok` otherwise see the service dependent and general status codes.
waypoints:
$ref: '#/components/schemas/waypoints'
routes:
$ref: '#/components/schemas/routes-routing'
directions-optimize:
title: Directions
x-stoplight:
id: riabv13h0f48t
type: object
x-examples:
Example 1:
code: string
waypoints:
- distance: 0
location:
- 0
routes: []
properties:
code:
type: string
description: If the request was successful `Ok` otherwise see the service dependent and general status codes.
waypoints:
$ref: '#/components/schemas/waypoints'
trips:
$ref: '#/components/schemas/routes-routing'
routes-routing:
title: Routes
type: array
description: Represents a route through (potentially multiple) waypoints.
items:
$ref: '#/components/schemas/route-routing'
route-routing:
title: Route
type: object
properties:
legs:
$ref: '#/components/schemas/directions_route_legs'
weight_name:
type: string
geometry:
type: string
weight:
type: number
distance:
type: number
duration:
type: number
directions-matching:
title: Matching
type: object
properties:
code:
type: string
description: If the request was successful `Ok` otherwise see the service dependent and general status codes.
tracepoints:
$ref: '#/components/schemas/matching_tracepoints'
matchings:
$ref: '#/components/schemas/matching_matchings'
directions-matrix:
title: Matrix
type: object
properties:
code:
type: string
description: If the request was successful `Ok` otherwise see the service dependent and general status codes.
distances:
type: array
description: |-
array of arrays that stores the matrix in row-major order. `distances[i][j]` gives the travel distance from
the i-th waypoint to the j-th waypoint. Values are given in meters. Can be `null` if no route between `i` and `j` can be found.
items:
type: array
items:
x-stoplight:
id: 47kxducsjqmpa
type: number
durations:
type: array
x-stoplight:
id: 1dbpasj6bvxow
description: |-
array of arrays that stores the matrix in row-major order. `durations[i][j]` gives the travel time from
the i-th waypoint to the j-th waypoint. Values are given in seconds. Can be `null` if no route between `i` and `j` can be found.
items:
x-stoplight:
id: d0uif6pp5vwkx
type: array
items:
x-stoplight:
id: l20aqj8f0wgop
type: number
fallback_speed_cells:
type: array
items:
type: number
sources:
type: array
description: array of `Waypoint` objects describing all sources in order.
items:
type: object
properties:
distance:
type: number
location:
type: array
items:
type: number
name:
type: string
destinations:
type: array
description: array of `Waypoint` objects describing all destinations in order.
items:
type: object
properties:
distance:
type: number
location:
type: array
items:
type: number
name:
type: string
directions-nearest:
title: Nearest
type: object
properties:
code:
type: string
description: If the request was successful `Ok` otherwise see the service dependent and general status codes.
waypoints:
type: array
description: 'Array of `Waypoint` objects sorted by distance to the input coordinate. '
items:
type: object
properties:
nodes:
type: array
description: Array of OpenStreetMap node ids.
items:
type: number
distance:
type: number
location:
type: array
items:
type: number
name:
type: string
extratags:
type: object
x-examples:
Example 1:
ele: '15'
height: '443.2'
wikidata: Q9188
wikipedia: 'en:Empire State Building'
start_date: '1931'
wheelchair: 'yes'
'building:use': office
opening_hours: 'Mo-Su 08:00-02:00'
'building:levels': '102'
construction_date: 1930-1931
description: |
The dictionary with additional useful tags like website or maxspeed. Returned when `extratags=1` is set in the request.
geojson:
type: object
properties:
type:
type: string
coordinates:
type: array
items:
type: number
x-examples:
Example 1:
type: Polygon
coordinates:
- - - -73.9865012
- 40.748491
- - -73.9851602
- 40.7479255
- - -73.9848166
- 40.7483931
- - -73.9861574
- 40.7489585
- - -73.9863252
- 40.7487301
- - -73.9863554
- 40.748689
- - -73.9864839
- 40.7485145
- - -73.9865012
- 40.748491
description: Output geometry of results in geojson format. Returned when `polygon_geojson=1` is set in the request.
geokml:
type: string
x-examples:
Example 1: '-73.986501200000006,40.748491000000001 -73.985160199999996,40.747925500000001 -73.984816600000002,40.748393100000001 -73.986157399999996,40.748958500000001 -73.986325199999996,40.748730100000003 -73.986355399999994,40.748688999999999 -73.986483899999996,40.748514499999999 -73.986501200000006,40.748491000000001'
description: Output geometry of results in kml format. Returned when `polygon_kml=1` is set in the request.
svg:
type: string
x-examples:
Example 1: M -73.9865012 -40.748491 L -73.9851602 -40.7479255 -73.9848166 -40.7483931 -73.9861574 -40.7489585 -73.9863252 -40.7487301 -73.9863554 -40.748689 -73.9864839 -40.7485145 Z
description: Output geometry of results in svg format. Returned when `polygon_svg=1` is set in the request.
geotext:
type: string
x-examples:
Example 1: 'POLYGON((-73.9865012 40.748491,-73.9851602 40.7479255,-73.9848166 40.7483931,-73.9861574 40.7489585,-73.9863252 40.7487301,-73.9863554 40.748689,-73.9864839 40.7485145,-73.9865012 40.748491))'
title: ''
description: Output geometry of results as a WKT. Returned when `polygon_text=1` is set in the request.
distance:
type: number
x-examples:
Example 1: 23
format: double
description: The straight line distance (meters) between the input location and the result's location. Returned when `showdistance=1` is set in the request.
matchquality:
type: object
x-examples:
Example 1:
matchcode: exact
matchtype: point
matchlevel: venue
description: 'An additional object `matchquality` for every result in the response, containing the following elements: `matchcode`, `matchtype`, `matchlevel`.'
properties:
matchcode:
$ref: '#/components/schemas/matchcode'
matchtype:
$ref: '#/components/schemas/matchtype'
matchlevel:
$ref: '#/components/schemas/matchlevel'
matchcode:
title: matchcode
x-stoplight:
id: keiun4kwm07z4
type: string
description: |
Specifies the quality of the returned address.
matchcode | description
------------|---------------
exact | The result matches the input query with a high level of probability.
fallback | The result does not exactly match the input but is closely related to it provided there is direct a heierarchial relation.
approximate| The result matches the input query with a medium to low level of probability.
matchtype:
title: matchtype
x-stoplight:
id: 20ejxqp1iy2wr
type: string
description: |-
Specifies quality of the returned location match
matchtype | description
--------------|---------------
point | The coordinate returned is a point address, typically with rooftop accuracy.
centroid | The coordinate returned is a centroid of a road or administrative boundary.
interpolated | The coordinate returned is a point determined by interpolation.
matchlevel:
type: string
x-examples:
Example 1: venue
description: |-
Specifies the most granular address element that matches the geocoding query.
matchlevel | details
-----------------|---------------
venue | The returned address is of a Point of Interest (PoI) level.
building | The returned address is of a house level.
street | The returned address is on a street level.
neighbourhood | The returned address is on a neighbourhood level.
island | The returned address is on a island level.
borough | The returned address is on a borough level.
city | The returned address is on a city level.
county | The returned address is on a county level.
state | The returned address is on a state level.
country | The returned address is on a country level.
marine | The returned address is on a marine level.
postalcode | The returned address is on a postalcode level.
timezone:
type: object
x-examples:
Example 1:
timezone:
name: Asia/Kolkata
now_in_dst: 0
offset_sec: 19800
short_name: IST
full_name: India Standard Time
properties:
timezone:
type: object
description: Timezone object found for the location.
properties:
name:
type: string
description: 'Timezone identifier, compatible with the IANA Tz Database. Typically in the format "Area/Location" (e.g., "America/New_York", "Europe/Paris"), but can also include ocean areas (e.g., "Atlantic/Azores") and special administrative zones (e.g., "Etc/UTC", "Etc/GMT-14"). We always return the most current identifier (e.g., "Asia/Kolkata", not "Asia/Calcutta"). Note that "Etc/GMT" zones use POSIX-style signs, opposite to ISO 8601 convention (e.g., "Etc/GMT-14" is 14 hours ahead of GMT).'
now_in_dst:
type: integer
description: Represents whether the zone currently observing `DST` or not.
offset_sec:
type: integer
description: The offset from `UTC` (in seconds) for the given location. Considers `DST` savings.
short_name:
type: string
description: 'Time zone abbreviation, usually 3 or 4 letters (e.g., "EDT" for Eastern Daylight Time, "CEST" for Central European Summer Time). In some cases, especially for locations without standardized abbreviations, it may be a numeric UTC offset (e.g., "+03" or "+0330").'
full_name:
type: string
x-stoplight:
id: 1qb7hcby2gwow
description: 'Complete, descriptive name of the time zone, e.g. "Pacific Daylight Time" or "Central European Standard Time". For some locations (e.g., oceans) where such a name is unavailable, it is returned in the format of GMT±HH:MM (e.g., GMT+03:30).'
postaladdress:
title: postaladdress
x-stoplight:
id: zq4zgnef9uq9n
type: string
description: Returns address specifically formatted for each country. Returned when `postaladdress` is set in the request
x-examples:
Example 1: '5, Avenue Anatole France, 75007, Paris, France'
lookup:
type: object
x-examples:
Example 1:
place_id: 115462561
licence: 'Data © OpenStreetMap contributors, ODbL 1.0. https://osm.org/copyright'
osm_type: way
osm_id: 50637691
boundingbox:
- '52.3994612'
- '52.3996426'
- '13.0479574'
- '13.0481754'
lat: '52.399550700000006'
lon: '13.048066846939687'
display_name: 'Brandenburger Tor, Brandenburger Straße, Historische Innenstadt, Innenstadt, Potsdam, Brandenburg, 14467, Germany'
class: tourism
type: attraction
address:
tourism: Brandenburger Tor
road: Brandenburger Straße
suburb: Historische Innenstadt
city: Potsdam
state: Brandenburg
postcode: '14467'
country: Germany
country_code: de
extratags:
image: 'http://commons.wikimedia.org/wiki/File:Potsdam_brandenburger_tor.jpg'
heritage: '4'
wikidata: Q695045
architect: Carl von Gontard;Georg Christian Unger
wikipedia: 'de:Brandenburger Tor (Potsdam)'
wheelchair: 'yes'
description: Kleines Brandenburger Tor in Potsdam
'heritage:website': 'http://www.bldam-brandenburg.de/images/stories/PDF/DML%202012/04-p-internet-13.pdf'
'heritage:operator': bldam
'architect:wikidata': Q68768;Q95223
year_of_construction: '1771'
properties:
place_id:
type: integer
description: Unique identifier for the place.
licence:
type: string
description: License information for the data.
osm_type:
type: string
description: Type of the OpenStreetMap object. Omitted for results sourced from non-OSM datasets.
osm_id:
type: integer
description: Unique identifier for the OpenStreetMap object. Omitted for results sourced from non-OSM datasets.
boundingbox:
type: array
description: 'List of bounding box coordinates [min_lat, max_lat, min_lon, max_lon].'
items:
type: string
lat:
type: string
description: Latitude of the location.
lon:
type: string
description: |
Longitude of the location.
display_name:
type: string
description: Formatted address for display.
class:
type: string
description: Categorization of map features based on their nature.
type:
type: string
description: It denotes the specific kind of feature within a class.
address:
$ref: '#/components/schemas/address'
extratags:
$ref: '#/components/schemas/extratags'
parameters:
query:
name: q
in: query
description: 'Free-form query string to search for. Commas are optional, but improves performance by reducing the complexity of the search.'
schema:
type: string
example: Empire State Building
required: true
bearings:
name: bearings
in: query
description: |-
Limits the search to segments with given bearing in degrees towards true north in clockwise direction. List of positive integer pairs separated by semi-colon and bearings array should be equal to length of coordinate array. Accepted Value :- `{bearing};{bearing}[;{bearing} ...]`
Each `{bearing}` follows the following format: `{value},{range}` `integer 0 .. 360,integer 0 .. 180`
required: false
example: '10,20;40,30;30,9'
schema:
type: string
radiuses:
name: radiuses
in: query
description: |-
Limits the search to given radius in meters Radiuses array length should be same as coordinates array, each value separated by semi-colon. Accepted Value - `{radius};{radius}[;{radius} ...]`
Each `{radius}` has following format: `double >= 0` or `unlimited` (default)
required: false
example: 500;200;300
schema:
type: string
generate_hints:
name: generate_hints
in: query
description: 'Adds a Hint to the response which can be used in subsequent requests, see hints parameter. Accepted Value - `true` (default), `false` Format - Base64 String'
required: false
example: 'false'
schema:
type: string
approaches:
name: approaches
in: query
description: |-
Keep waypoints on curb side. Accepted Value - `{approach};{approach}[;{approach} ...]`
approach has the following format - `curb` or `unrestricted` (default).'
required: false
example: curb;curb;curb
schema:
type: string
exclude:
name: exclude
in: query
description: |-
Additive list of classes to avoid, order does not matter. Accepted Value - `{class}[,{class}]`
class has the following format - A class name determined by the profile or none.
required: false
example: toll
schema:
type: string
zoom:
name: zoom
in: query
required: false
schema:
type: integer
minimum: 0
maximum: 18
default: 18
example: 18
description: |-
Level of detail required where `0` is country and `18` is house/building. Defaults to `18`.
In terms of address details the zoom levels are as follows:
zoom | address detail
-----|---------------
3 | country
5 | state
8 | county
10 | city
14 | suburb
16 | street
18 | building
addressdetails-default-1:
name: addressdetails
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 1
description: 'Include a breakdown of the address of this result into elements. Important components include (but not limited to) country, postcode, state, county, city, town. Only those elements that are available for a given location will be returned.'
addressdetails-default-0:
name: addressdetails
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: Include a breakdown of the address of this result into elements. Defaults to `0`.
format:
name: format
in: query
required: false
schema:
type: string
default: xml
enum:
- xml
- json
- xmlv1.1
example: json
description: |-
Output Format. Defaults to xml.
> This version (v1) of our Reverse Geocoding API is compatible with OpenStreetMap's Nominatim Geocoder in both JSON & XML formats. However, all our enhancements such as additional datasets and algorithms are supported only in `json` or `xmlv1.1` format options.
accept-language:
name: accept-language
in: query
required: false
schema:
type: string
default: en
example: en
description: |-
Preferred language order for showing search results, overrides the value specified in the `Accept-Language` HTTP header. Defaults to `en`.
To use native language for the response when available, use `accept-language=native`.
Either uses standard rfc2616 accept-language string or a simple comma separated list of language codes.
accept-language-autocomplete:
name: accept-language
in: query
required: false
schema:
type: string
default: en
example: en
description: |-
Preferred language order for showing search results, overrides the value specified in the `Accept-Language` HTTP header. Defaults to `en`.
Accepts a simple comma separated list of the supported language codes.
To use native language for the response when available, use `accept-language=native`.
The Autocomplete endpoint currently supports the following languages: English `en`, Czech `cs`, Dutch `nl`, French `fr`, German `de`, Indonesian `id`, Italian `it`, Norwegian `no`, Polish `pl`, Spanish `es`, Russian `ru`, Swedish `sv` and Ukrainian `uk`.
If you'd like us to add support for a specific language, please reach out.
namedetails:
name: namedetails
in: query
schema:
type: integer
enum:
- 0
- 1
default: 0
description: 'Include a list of alternative names in the results. These may include language variants, references, operator and brand. Defaults to `0`.'
json_callback:
name: json_callback
in: query
required: false
schema:
type: string
description: Wrap json output in a callback function (JSONP) i.e. <string>(<json>). Only has an effect for JSON output formats.
polygon_geojson:
name: polygon_geojson
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: Output geometry of results in geojson format. Defaults to `0`.
polygon_kml:
name: polygon_kml
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: Output geometry of results in kml format. Defaults to `0`.
polygon_svg:
name: polygon_svg
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: Output geometry of results in svg format. Defaults to `0`.
polygon_text:
name: polygon_text
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: Output geometry of results as a WKT. Defaults to `0`.
extratags:
name: extratags
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: 'Include additional information in the result if available, e.g. wikipedia link, opening hours. Defaults to `0`.'
normalizeaddress:
name: normalizeaddress
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: |-
Makes parsing of the `address` object easier by returning a predictable and defined list of elements. Defaults to `0` for backward compatibility. We recommend setting this to `1` for new projects.
Element Name | Description
------------- | -----------
name | House name or Point of Interest (POI) such as a Cafe or School
house_number | House or Building number
road | Roads, Highways, Freeways, Motorways
neighbourhood | Neighbourhoods, Allotments, Quarters, Communities
suburb | Suburbs, Subdivisions
island | Islands, Islets
city | Cities, Towns, Villages, Municipalities, Districts, Boroughs, Hamlets
county | Counties
state | States, Provinces, Regions, State Districts
state_code | State or Province Code
postcode | Postal Codes, Zipcodes
country | Countries, Nation-states
country_code | Country Code - 2 letter (ISO 3166-1 alpha-2)
normalizecity:
name: normalizecity
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: 'For responses with no `city` value in the address section, the next available element in this order - `city_district`, `locality`, `town`, `borough`, `municipality`, `village`, `hamlet`, `quarter`, `neighbourhood` - from the address section will be normalized to city. Defaults to `0`.'
statecode:
name: statecode
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: 'Adds state or province code when available to the `state_code` key inside the `address` object when available. Defaults to `0`.'
showdistance:
name: showdistance
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: Returns the straight line distance (meters) between the input location and the result's location. Value is set in the `distance` key of the response. Defaults to `0`.
postaladdress:
name: postaladdress
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: 'Returns address inside the `postaladdress` key, that is specifically formatted for each country. Currently supported for addresses in Belgium, Brazil, France, Germany, Greece, India, Ireland, Italy, Portugal, South Africa, Spain and United Kingdom. Defaults to `0`.'
oceans:
name: oceans
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: 'Allows you to specify whether or not the API should return the name of an ocean or sea if the coordinates provided fall within a body of water. By default, this parameter is set to `0` for backward compatibility. When set to `1` and used in conjunction with `addressdetails=1`, the response will contain a limited `address` section consisting of only the `name` and `water` elements, providing the name of the ocean or sea the coordinates correspond to, if the coordinates fall within a body of water.'
lat:
name: lat
in: query
required: true
schema:
type: number
example: 40.748442
format: float
description: Latitude of the location to generate an address for.
lon:
name: lon
in: query
required: true
schema:
type: number
example: -73.985658
format: float
description: Longitude of the location to generate an address for.
source:
name: source
in: query
required: false
schema:
type: string
description: 'If this parameter is not specified, LocationIQ uses multiple public and proprietary datasets to return results. If you''d like to restrict results to only OpenStreetMap data, you can set the value of this parameter to `nom`. This will only query our internal cluster of Nominatim servers, and return results. We may still apply some post-processing steps to these results though, so results may vary from the official Nominatim instance.'
postalcode:
name: postalcode
in: query
required: false
schema:
type: string
description: 'Use this to indicate the postal or ZIP code, aiding in pinpointing the exact area within a city or locality.'
postalcode-required:
name: postalcode
in: query
required: true
schema:
type: string
description: 'Use this to indicate the postal or ZIP code, aiding in pinpointing the exact area within a city or locality.'
street:
name: street
in: query
required: false
schema:
type: string
description: 'Pass this parameter to specify the street address (building number, name and road).'
country:
name: country
in: query
required: false
schema:
type: string
description: ' Include this to provide country of the address, crucial for precise geocoding on a global scale.'
county:
name: county
in: query
required: false
schema:
type: string
description: Use this to indicate the county or administrative region of the address.
city:
name: city
in: query
required: false
schema:
type: string
description: Include this parameter to provide the city information for geocoding.
state:
name: state
in: query
required: false
schema:
type: string
description: 'Pass this to specify the state or province of the address, helping to identify the region within the country.'
viewbox:
name: viewbox
in: query
required: false
schema:
type: string
example: '-73.9965012,40.7489255,-73.9858166,40.7499585'
description: 'The preferred area to find search results. Any two corner points of the box - `max_lon,max_lat,min_lon,min_lat` or `min_lon,min_lat,max_lon,max_lat` - are accepted in any order as long as they span a real box. To restrict results to those within the viewbox, use along with the `bounded` option.'
bounded:
name: bounded
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
description: Restrict result to items contained within the bounds specified in the `viewbox` parameter. Defaults to `0`.
countrycodes:
name: countrycodes
in: query
required: false
schema:
type: string
example: 'us,ca,gb'
description: Limit search results to a specific country or a comma-separated list of countries. Should be the ISO 3166-1 alpha-2 code(s).
dedupe-default-0:
name: dedupe
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: When enabled, the geocoder attempts to filter out duplicate results for the same real-world place. Because `limit` is applied before deduplication, fewer results than requested may be returned.
dedupe-default-1:
name: dedupe
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 1
description: 'Sometimes you have several objects in OSM identifying the same place or object in reality. The simplest case is a street being split in many different OSM ways due to different characteristics. Our Geocoder will attempt to detect such duplicates and only return one match; this is controlled by the dedupe parameter which defaults to `1`. Since the limit is, for reasons of efficiency, enforced before and not after de-duplicating, it is possible that de-duplicating leaves you with less results than requested.'
importancesort:
name: importancesort
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 1
description: 'Determines whether results are sorted by their individual `importance` values. If `importancesort=0` and is used along with the `viewbox` parameter, results are sorted only by distance. Defaults to `1`.'
tag:
name: tag
in: query
required: false
schema:
type: string
example: 'place:city'
description: |-
Restricts results to specific types of elements. This can be used to return only administrative areas - such as towns or cities - or specific Points of Interest such as schools or restaurants.
This is defined as key value pairs of `class` and `type` values based on OpenStreetMap''s (OSM) exhaustive list.
Multiple `class` and `type` values can be specified as a comma-separated list.
**Examples:**
- To return only cities: `tag=place:city`
- To return only types of `place`, such as Suburbs, Towns and Cities, use a wildcard: `tag=place:*`
- To restrict results to specific types of `place`: `tag=place:city,place:town,place:village`
- To restrict results to cafes: `tag=amenity:cafe`
- To restrict results to all types except those with amenity as class: `tag=!amenity:*`
- To restrict results to only the amenity class except gym: `tag=amenity:*,!amenity:gym`
- To restrict results to all types except elements with amenity as class and gym as type: `tag=!amenity:gym`
layers-autocomplete:
name: layers
in: query
required: false
schema:
type: string
example: 'state,country'
description: |-
Restricts results to specific layers on the Autocomplete API.
Multiple layer values can be specified as a comma-separated list.
Values are case-insensitive and extra spaces are ignored.
Unsupported values are ignored.
**Supported values:** `road`, `neighbourhood`, `suburb`, `city`, `county`, `state`, `country`, `postcode`
**Note:** `layers=postcode` applies a postal-code-only filter only when it is the sole layer and `tag` is not set. If `tag` is set, `tag` filtering is preserved and `postcode` in `layers` is ignored.
**Examples:**
- To return only states: `layers=state`
- To return only countries: `layers=country`
- To return states and countries: `layers=state,country`
- To return postal code records: `layers=postcode`
tag-nearby:
name: tag
in: query
required: false
schema:
type: string
example: 'amenity:school'
description: |-
You can use a `tag` to restrict Nearby API results to specific types of places. We support two types of tags: a single-word format for common use-cases and key-value pairs for advanced use-cases.
### 1. Single-word Format (Simple)
For most use-cases, the list of tags below should suffice. Multiple tags can be specified as a comma-separated list.
Tag | Description
----------------| -----------
all | Return a list of all places
airport | List of airports
city | List of nearby cities
restaurant | List of restaurants
bank | List of banks
atm | List of ATMs
hotel | List of hotels
pub | List of pubs
bus_station | List of bus stations
railway_station | List of railway stations
cinema | List of cinema theatres
hospital | List of hospitals
college | List of colleges
school | List of schools
pharmacy | List of pharmacies
supermarket | List of supermarket
fuel | List of fuel stations
gym | List of gyms
place_of_worship| List of places of worship
toilet | List of toilets
park | List of parks
stadium | List of stadiums
parking | List of parking
cardealer | List of car dealers
### 2. Key Value Format (Advanced)
For advanced use-cases that need additional tags not present in the table above, we also support tags based on OpenStreetMap''s (OSM) exhaustive list of tags. These tags are represented as key-value pairs of `class` and `type` values. Multiple `class` and `type` values can be specified as a comma-separated list.
**Examples:**
* To return a list of all places: tag=all
* To return city records: tag=place:city
* To return records with amenity class (e.g., restaurants, hospitals, banks): tag=amenity:*
* To return records with the amenity class and school as type (i.e., a list of schools): tag=amenity:school
* To return all records except those with amenity as class: tag=all,!amenity:*
* To return all records in the amenity class except gym: tag=amenity:*,!amenity:gym
* To return all records except elements with amenity as class and gym as type: tag=!amenity:gym
* To return a list of airports, hotels, and parking spaces nearby: tag=aeroway:aerodrome,tourism:hotel,amenity:parking
matchquality:
name: matchquality
in: query
required: false
schema:
type: integer
enum:
- 0
- 1
default: 0
description: Returns additional information about quality of the result in a `matchquality` object. Defaults to `0`.
limit-max-20:
name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 20
description: 'Limit the number of returned results. Accepted value: `1` to `20`. Defaults to `10`.'
limit-max-50:
name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 50
description: 'Limit the number of returned results. Accepted value: `1` to `50`. Defaults to `10`.'
normalizeimportance:
name: normalizeimportance
in: query
schema:
type: integer
default: 1
enum:
- 0
- 1
description: 'When this parameter is absent or set to `1`, the `importance` value(s) in the API response is limited to the range of 0 to 1. Values outside this range are adjusted to the nearest boundary (0 or 1). Setting `normalizeimportance` to `0` allows the importance value to be lower or higher than the specified range of 0 to 1. Defaults to `1`'
radius:
name: radius
in: query
required: false
schema:
type: integer
default: 100
minimum: 1
maximum: 500000
description: |-
Radius (in meters) from the given latitude and longitude to search for results in.
Accepted value: `1` to `500000`. Defaults to `100`.
Note: Nearby API results are matched using each result's associated location point, not the full boundary or area of the result. A result is returned only when the search radius reaches that point.
For example, a search near outer London may not return `London` until the radius is large enough to reach London's associated location point, even if part of the wider London area is already within the search radius.
alternatives:
name: alternatives
in: query
description: |-
Search for alternative routes. Passing a number alternatives=n searches for up to n alternative routes.
Accepted value: `true`, `false` (default), or Number
required: false
example: 0
schema:
type: number
steps:
name: steps
in: query
description: |-
Returned route steps for each route leg.
Accepted value: `true`, `false` (default)
required: false
example: 'true'
schema:
type: string
annotations:
name: annotations
in: query
description: |-
Returns additional metadata for each coordinate along the route geometry.
Accepted value: `true`, `false` (default), `nodes`, `distance`, `duration`, `datasources`, `weight`, `speed`
required: false
example: 'false'
schema:
type: string
default: 'false'
geometries:
name: geometries
in: query
description: 'Returned route geometry format (influences overview and per step). Accepted value: `polyline` (default), `polyline6`, `geojson`'
required: false
example: polyline
schema:
type: string
default: polyline
overview:
name: overview
in: query
description: |-
Add overview geometry either full, simplified according to highest zoom level it could be display on, or not at all.
Accepted value: `simplified` (default), `full`, `false`
required: false
example: simplified
schema:
type: string
default: simplified
continue_straight:
name: continue_straight
in: query
description: |-
Forces the route to keep going straight at waypoints constraining uturns there even if it would be faster.
Accepted value: `default` (default), `true`, `false`. Default value depends on the profile.
required: false
example: default
schema:
type: string
default: default
timestamps:
name: timestamps
in: query
description: |-
'Timestamps for the input locations in seconds since UNIX epoch. Timestamps need to be monotonically increasing.
Accepted value: `{timestamp};{timestamp}[;{timestamp} ...]`
Each `{timestamp}` has the following format: integer seconds since UNIX epoch'
required: false
example: 200;300;900
schema:
type: string
gaps:
name: gaps
in: query
description: 'Allows the input track splitting based on huge timestamp gaps between points. Accepted value: `split` (default), `ignore`'
required: false
example: ignore
schema:
type: string
default: split
tidy:
name: tidy
in: query
description: 'Allows the input track modification to obtain better matching quality for noisy tracks. Accepted value: `true`, `false` (default).'
required: false
example: 'false'
schema:
type: string
default: 'false'
waypoints:
name: waypoints
in: query
description: 'Treats input coordinates indicated by given indices as waypoints in returned Match object. Default is to treat all input coordinates as waypoints. `{index};{index};{index}... ]`'
required: false
example: 0;1;2
schema:
type: string
sources:
name: sources
in: query
description: |-
Use location with given index as source. Accepted value: `{index};{index}[;{index} ...]` or `all` (default).
Each `{index}` has the following format: 0 <= integer < #locations
required: false
example: 0
schema:
type: integer
destinations:
name: destinations
in: query
description: |-
Use location with given index as destination.
Accepted value: `{index};{index}[;{index} ...]` or `all` (default)
Each `{index}` has the following format: 0 <= integer < #locations
required: false
example: 2
schema:
type: integer
fallback_speed:
name: fallback_speed
in: query
description: |-
If no route found between a source/destination pair, calculate the as-the-crow-flies distance, then use this speed to estimate duration.
Accepted value: double > 0
required: false
example: 25.65
schema:
type: number
fallback_coordinate:
name: fallback_coordinate
in: query
description: |-
When using a fallback_speed, use the user-supplied coordinate (input), or the snapped location (snapped) for calculating distances.
Accepted value: `input` (default), or `snapped`.
required: false
example: snapped
schema:
type: string
default: input
number:
name: number
in: query
description: 'Number of nearest segments that should be returned. Accepted value: `integer >= 1` (default `1`) '
required: false
example: 3
schema:
type: integer
coordinates:
name: coordinates
in: path
required: true
schema:
type: string
description: 'String of format `{longitude},{latitude};{longitude},{latitude}[;{longitude},{latitude} ...]` or `polyline({polyline}) or polyline6({polyline6})`.
You can send up to a maximum of `25` coordinate pairs per request (except `Nearest API` where `coordinates` only supports a single {longitude},{latitude} entry)'
profile:
name: profile
in: path
required: true
schema:
type: string
example: driving
enum:
- driving
- walking
description: 'Mode of transportation. `driving` and `walking` are supported. '
service:
name: service
in: query
schema:
type: string
enum:
- directions
- matching
- matrix
- nearest
- optimize
description: 'One of the following values: `directions`, `matching`, `matrix`, `nearest`, `optimize`'
hints:
name: hints
in: query
required: false
schema:
type: string
description: 'Hint from previous request to derive position in street network. Accepted value: `{hint};{hint}[;{hint} ...]`'
roundtrip:
name: roundtrip
in: query
required: false
schema:
type: string
description: 'Returned route is a roundtrip (route returns to first location) . Accepted value: `true` (default), `false`'
source-routing:
name: source
in: query
required: false
schema:
type: string
description: 'Returned route starts at `any` or `first` coordinate. Accepted value: `any` (default), `first`.'
destination-routing:
name: destination
in: query
required: false
schema:
type: string
description: 'Returned route ends at `any` or `last` coordinate. Accepted value: `any` (default), `last`.'
timestamp:
name: timestamp
in: query
schema:
type: number
example: 1701179610
description: 'Unix epoch time in seconds (number of seconds since January 1, 1970, 00:00:00 UTC). Defaults to current time if omitted. This parameter allows retrieval of time zone information for specific moments, which is useful for handling Daylight Saving Time changes and ensuring correct time zone offsets for historical data or future event scheduling.'
allowEmptyValue: true
osm_ids:
name: osm_ids
in: query
required: true
schema:
type: string
example: 'R146656,W104393803,N240109189'
description: 'This must contain a comma-separated list of OSM ids each prefixed with its type, one of node(N), way(W) or relation(R). Up to 3 ids can be queried at the same time.'
polygon_threshold:
name: polygon_threshold
in: query
required: false
schema:
type: number
example: 0.2
default: 0
description: 'When one of the polygon_* outputs is chosen, return a simplified version of the output geometry. The parameter describes the tolerance in degrees with which the geometry may differ from the original geometry. Topology is preserved in the geometry.'
format-only-json:
name: format
in: query
required: false
schema:
type: string
description: Output Format. Only `json` supported as of now.
responses:
400Error:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Invalid Request:
value:
error: Invalid Request
401Error:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Invalid Key:
value:
error: Invalid Key
403Error:
description: The request has been made from an unauthorized domain.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Access restricted:
value:
error: Access restricted
404Error:
description: No location or places were found for the given input.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Unable to geocode:
value:
error: Unable to geocode
429Error:
description: Request exceeded the rate-limits set on your account.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Rate Limited Day:
value:
error: Rate Limited Day
Rate Limited Minute:
value:
error: Rate Limited Minute
Rate Limited Second:
value:
error: Rate Limited Second
500Error:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Internal Server Error:
value:
error: Unknown error - Please try again after some time
400Error-search:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Invalid Request:
value:
error: Invalid Request
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Invalid Request
examples:
Invalid Request:
value: |-
Invalid Request
401Error-search:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Invalid Key:
value:
error: Invalid Key
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Invalid Key
examples:
Invalid Key:
value: |-
Invalid Key
403Error-search:
description: The request has been made from an unauthorized domain.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Access restricted:
value:
error: Access restricted
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Access restricted
examples:
Access restricted:
value: |-
Access restricted
404Error-search:
description: No location or places were found for the given input.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Unable to geocode:
value:
error: Unable to geocode
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Unable to geocode
examples:
Unable to geocode:
value: |-
Unable to geocode
429Error-search:
description: Request exceeded the rate-limits set on your account.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Rate Limited Day:
value:
error: Rate Limited Day
Rate Limited Minute:
value:
error: Rate Limited Minute
Rate Limited Second:
value:
error: Rate Limited Second
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Rate Limited Second
examples:
Rate Limited Day:
value: |-
Rate Limited Day
Rate Limited Minute:
value: |-
Rate Limited Minute
Rate Limited Second:
value: |-
Rate Limited Second
500Error-search:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Internal Server Error:
value:
error: Unknown error - Please try again after some time
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Internal Server Error
examples:
Internal Server Error:
value: |-
Unknown error - Please try again after some time
400Error-reverse:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Invalid Request:
value:
error: Invalid Request
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Invalid Request
examples:
Invalid Request:
value: |-
Invalid Request
401Error-reverse:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Invalid Key:
value:
error: Invalid Key
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Invalid Key
examples:
Invalid Key:
value: |-
Invalid Key
403Error-reverse:
description: The request has been made from an unauthorized domain.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Access restricted:
value:
error: Access restricted
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Access restricted
examples:
Access restricted:
value: |-
Access restricted
404Error-reverse:
description: No location or places were found for the given input.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Unable to geocode:
value:
error: Unable to geocode
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Unable to geocode
examples:
Unable to geocode:
value: |-
Unable to geocode
429Error-reverse:
description: Request exceeded the rate-limits set on your account.
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Rate Limited Day:
value:
error: Rate Limited Day
Rate Limited Minute:
value:
error: Rate Limited Minute
Rate Limited Second:
value:
error: Rate Limited Second
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Rate Limited Second
examples:
Rate Limited Day:
value: |-
Rate Limited Day
Rate Limited Minute:
value: |-
Rate Limited Minute
Rate Limited Second:
value: |-
Rate Limited Second
500Error-reverse:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/error'
examples:
Internal Server Error:
value:
error: Unknown error - Please try again after some time
application/xml:
schema:
type: object
properties:
error:
type: string
x-examples:
Example 1:
error: Internal Server Error
examples:
Internal Server Error:
value: |-
Unknown error - Please try again after some time
400Error-routing:
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/error-routing'
examples:
Invalid Options:
value:
code: InvalidOptions
InvalidUrl:
value:
code: InvalidUrl
Invalid Service:
value:
code: InvalidService
Invalid Query:
value:
code: InvalidQuery
Invalid Value:
value:
code: InvalidValue
Not Implemented:
value:
code: NotImplemented
Too Big:
value:
code: TooBig
401Error-routing:
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/error-routing'
examples:
Invalid Key:
value:
code: Invalid Key
403Error-routing:
description: The request has been made from an unauthorized domain.
content:
application/json:
schema:
$ref: '#/components/schemas/error-routing'
examples:
Access restricted:
value:
code: Access restricted
404Error-routing:
description: No location or places were found for the given input
content:
application/json:
schema:
$ref: '#/components/schemas/error-routing'
examples:
No Match:
value:
code: NoMatch
No Segment:
value:
code: NoSegment
No Trips:
value:
code: NoTrips
429Error-routing:
description: Request exceeded the rate-limits set on your account
content:
application/json:
schema:
$ref: '#/components/schemas/error-routing'
examples:
Rate Limited Day:
value:
code: Rate Limited Day
Rate Limited Minute:
value:
code: Rate Limited Minute
Rate Limited Second:
value:
code: Rate Limited Day
500Error-routing:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/error-routing'
examples:
Internal Server Error:
value:
code: Unknown error - Please try again after some time