kinlane
commented
8 hours ago openapi: 3.0.3
servers:
- url: 'https://api.stadiamaps.com'
- url: 'https://api-eu.stadiamaps.com'
info:
description: >-
The Stadia Maps Geospatial APIs provide you with the data you need to build awesome applications.
version: 7.1.0
title: Stadia Maps Geospatial APIs
contact:
name: Stadia Maps Support
url: 'https://www.stadiamaps.com'
email: support@stadiamaps.com
paths:
/tz/lookup/v1:
get:
tags:
- Geospatial
operationId: tz-lookup
summary: Get the current time zone information for any point on earth.
description: >-
The Stadia TZ API provides time zone information, as well as information
about any special offset (such as DST) in effect based on the latest IANA
TZDB. Note that this API may not be accurate for timestamps in the past and
does not claim to report precise nautical times in the open ocean beyond
territorial waters.
security:
- ApiKeyAuth: [ ]
parameters:
- name: lat
in: query
description: The latitude of the point you are interested in.
required: true
schema:
type: number
format: double
minimum: -90
maximum: 90
- name: lng
in: query
description: The longitude of the point you are interested in.
required: true
schema:
type: number
format: double
minimum: -180
maximum: 180
- name: timestamp
in: query
description: >-
The UNIX timestamp at which the UTC and DST offsets will be calculated.
This defaults to the present time. This endpoint is not necessarily guaranteed to be accurate
for timestamps that occurred in the past. Time zone geographic boundaries change
over time, so if the point you are querying for was previously in a different
time zone, historical results will not be accurate. If, however, the point has
been in the same geographic time zone for a very long time (ex: `America/New_York`),
the historical data may be accurate for 100+ years in the past (depending on how far
back the IANA TZDB rules have been specified).
required: false
schema:
type: integer
format: int64
minimum: 0
maximum: 8200290900000 # Approximately 262,000 years in the future, at which point Chrono breaks
responses:
'200':
description: The time zone metadata.
content:
application/json:
schema:
$ref: '#/components/schemas/tzResponse'
'404':
description: Time zone not found
/elevation/v1:
post:
tags:
- Geospatial
operationId: elevation
summary: Get the elevation profile along a polyline or at a point.
description: >-
The Stadia elevation API allows you to get the elevation of any point on earth.
You can pass either a simple set of points or a Google encoded polyline string.
This pairs well with our routing APIs, so you can generate an elevation profile
for your next bike or run.
security:
- ApiKeyAuth: [ ]
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/heightRequest'
responses:
'200':
description: A list of elevations along the polyline, in meters.
content:
application/json:
schema:
$ref: '#/components/schemas/heightResponse'
'400':
description: Bad request; more details will be included
/route/v1:
post:
tags:
- Routing
operationId: route
summary: Get turn by turn routing instructions between two or more locations.
description: >-
The route (turn-by-turn) API computes routes between two or more locations. It supports a
variety of tunable costing methods, and supports routing through intermediate waypoints and
discontinuous multi-leg routes.
security:
- ApiKeyAuth: [ ]
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/routeRequest'
responses:
'200':
description: The computed route(s).
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/routeResponse'
- $ref: '#/components/schemas/osrmRouteResponse'
'400':
description: Bad request; more details will be included
'500':
description: An internal parse error occurred; more details will be included
/nearest_roads/v1:
post:
tags:
- Routing
operationId: nearest-roads
summary: Find the nearest roads to the set of input locations.
description: >-
The nearest roads API allows you query for detailed information about streets and intersections near the
input locations.
security:
- ApiKeyAuth: [ ]
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/nearestRoadsRequest'
responses:
'200':
description: A list of streets and intersections that match the query.
content:
application/json:
schema:
$ref: '#/components/schemas/nearestRoadsResponse'
'400':
description: Bad request; more details will be included
/matrix/v1:
post:
tags:
- Routing
operationId: time-distance-matrix
summary: Calculate a time distance matrix for use in an optimizer.
description: >-
The time distance matrix API lets you compare travel times between a set of possible start and end points.
See https://docs.stadiamaps.com/limits/ for documentation of our latest limits.
security:
- ApiKeyAuth: [ ]
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/matrixRequest'
responses:
'200':
description: A matrix of times and distances between the start and end points.
content:
application/json:
schema:
$ref: '#/components/schemas/matrixResponse'
'400':
description: >-
Bad request; more details will be included.
NOTE: failure to find suitable edges near a location will result in a 400.
/isochrone/v1:
post:
tags:
- Routing
operationId: isochrone
summary: Calculate areas of equal travel time from a location.
description: >-
The isochrone API computes reachable areas within a time or distance constraint.
The resulting polygon can be rendered on a map and used for assessing urban mobility,
planning, or as a search filter of places within a constrained range.
security:
- ApiKeyAuth: [ ]
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/isochroneRequest'
responses:
'200':
description: A GeoJSON object which can be integrated into your geospatial application.
content:
application/json:
schema:
$ref: '#/components/schemas/isochroneResponse'
'400':
description: Bad request; more details will be included
/optimized_route/v1:
post:
tags:
- Routing
operationId: optimized-route
summary: Calculate an optimized route between a known start and end point.
description: >-
The optimized route API is a mix of the matrix and normal route API. For an optimized route,
the start and end point are fixed, but the intermediate points will be re-ordered to form an
optimal route visiting all nodes once.
security:
- ApiKeyAuth: [ ]
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/optimizedRouteRequest'
responses:
'200':
description: >-
The optimized route, which looks more or less like a normal route response. The only
significant difference is that the `locations` may be re-ordered and annotated with an `original_index`.
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/routeResponse'
- $ref: '#/components/schemas/osrmRouteResponse'
'400':
description: Bad request; more details will be included
'500':
description: An internal parse error occurred; more details will be included
/map_match/v1:
post:
tags:
- Routing
operationId: map-match
summary: Match a recorded route to the road network.
description: >-
The map matching API transforms a recorded route into navigation instructions like you would get from
the `route` endpoint. The input can be in the form of either an encoded polyline, or (optionally) timestamped
coordinates.
security:
- ApiKeyAuth: [ ]
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/mapMatchRequest'
responses:
'200':
description: >-
The matched route(s), which looks more or less like a normal route response, optionally with
a `linear_references` key.
content:
application/json:
schema:
$ref: '#/components/schemas/mapMatchRouteResponse'
'400':
description: Bad request; more details will be included
'500':
description: An internal parse error occurred; more details will be included
/trace_attributes/v1:
post:
tags:
- Routing
operationId: trace-attributes
summary: Trace the attributes of roads visited on a route.
description: >-
The trace attributes endpoint retrieves detailed information along a route, returning details for each section
along the path, as well as any intersections encountered. In addition to tracing a recording route, this
is great for providing just-in-time info to navigation applications, enabling them to conserve resources by
omitting info like speed limits upfront that may be irrelevant if the user goes off-route.
security:
- ApiKeyAuth: [ ]
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/traceAttributesRequest'
responses:
'200':
description: >-
The edges along the traced route with detailed info.
content:
application/json:
schema:
$ref: '#/components/schemas/traceAttributesResponse'
'400':
description: Bad request; more details will be included
/geocoding/v1/autocomplete:
get:
tags:
- Geocoding
operationId: autocomplete
summary: Search and geocode quickly based on partial input.
description: >-
Autocomplete enables interactive search-as-you-type user experiences, suggesting places as you type,
along with information that will help your users find the correct place quickly.
security:
- ApiKeyAuth: [ ]
parameters:
- $ref: '#/components/parameters/searchText'
- $ref: '#/components/parameters/searchFocusLat'
- $ref: '#/components/parameters/searchFocusLon'
- $ref: '#/components/parameters/searchBoundaryRectMinLat'
- $ref: '#/components/parameters/searchBoundaryRectMaxLat'
- $ref: '#/components/parameters/searchBoundaryRectMinLon'
- $ref: '#/components/parameters/searchBoundaryRectMaxLon'
- $ref: '#/components/parameters/searchBoundaryCircleLat'
- $ref: '#/components/parameters/searchBoundaryCircleLon'
- $ref: '#/components/parameters/searchBoundaryCircleRadius'
- $ref: '#/components/parameters/searchBoundaryCountry'
- $ref: '#/components/parameters/searchBoundaryGID'
- $ref: '#/components/parameters/searchLayers'
- $ref: '#/components/parameters/searchSources'
- $ref: '#/components/parameters/size'
- $ref: '#/components/parameters/peliasLang'
responses:
'200':
description: A GeoJSON collection of autocomplete search results.
content:
application/json:
schema:
$ref: '#/components/schemas/peliasResponse'
'400':
description: Bad request
/geocoding/v1/search:
get:
tags:
- Geocoding
operationId: search
summary: Search for location and other info using a place name or address (forward geocoding).
description: >-
The search endpoint lets you search for addresses, points of interest, and administrative areas.
This is most commonly used for forward geocoding applications where you need to find the geographic
coordinates of an address.
security:
- ApiKeyAuth: [ ]
parameters:
- $ref: '#/components/parameters/searchText'
- $ref: '#/components/parameters/searchFocusLat'
- $ref: '#/components/parameters/searchFocusLon'
- $ref: '#/components/parameters/searchBoundaryRectMinLat'
- $ref: '#/components/parameters/searchBoundaryRectMaxLat'
- $ref: '#/components/parameters/searchBoundaryRectMinLon'
- $ref: '#/components/parameters/searchBoundaryRectMaxLon'
- $ref: '#/components/parameters/searchBoundaryCircleLat'
- $ref: '#/components/parameters/searchBoundaryCircleLon'
- $ref: '#/components/parameters/searchBoundaryCircleRadius'
- $ref: '#/components/parameters/searchBoundaryCountry'
- $ref: '#/components/parameters/searchBoundaryGID'
- $ref: '#/components/parameters/searchLayers'
- $ref: '#/components/parameters/searchSources'
- $ref: '#/components/parameters/size'
- $ref: '#/components/parameters/peliasLang'
responses:
'200':
description: A GeoJSON collection of search results.
content:
application/json:
schema:
$ref: '#/components/schemas/peliasResponse'
'400':
description: Bad request
/geocoding/v1/search/structured:
get:
tags:
- Geocoding
operationId: search-structured
summary: Find locations matching components (structured forward geocoding).
description: >-
The structured search endpoint lets you search for addresses, points of interest, and administrative areas.
Rather than a single string which the API must infer meaning from, the structured search endpoint allows you to
specify the known components upfront, which is useful in many forward geocoding workflows.
security:
- ApiKeyAuth: [ ]
parameters:
- $ref: '#/components/parameters/searchAddress'
- $ref: '#/components/parameters/searchNeighborhood'
- $ref: '#/components/parameters/searchBorough'
- $ref: '#/components/parameters/searchLocality'
- $ref: '#/components/parameters/searchCounty'
- $ref: '#/components/parameters/searchRegion'
- $ref: '#/components/parameters/searchPostalCode'
- $ref: '#/components/parameters/searchCountry'
- $ref: '#/components/parameters/searchFocusLat'
- $ref: '#/components/parameters/searchFocusLon'
- $ref: '#/components/parameters/searchBoundaryRectMinLat'
- $ref: '#/components/parameters/searchBoundaryRectMaxLat'
- $ref: '#/components/parameters/searchBoundaryRectMinLon'
- $ref: '#/components/parameters/searchBoundaryRectMaxLon'
- $ref: '#/components/parameters/searchBoundaryCircleLat'
- $ref: '#/components/parameters/searchBoundaryCircleLon'
- $ref: '#/components/parameters/searchBoundaryCircleRadius'
- $ref: '#/components/parameters/searchBoundaryCountry'
- $ref: '#/components/parameters/searchBoundaryGID'
- $ref: '#/components/parameters/searchLayers'
- $ref: '#/components/parameters/searchSources'
- $ref: '#/components/parameters/size'
- $ref: '#/components/parameters/peliasLang'
responses:
'200':
description: A GeoJSON collection of search results.
content:
application/json:
schema:
$ref: '#/components/schemas/peliasResponse'
'400':
description: Bad request
/geocoding/v1/search/bulk:
post:
tags:
- Geocoding
operationId: search-bulk
summary: Quickly run a batch of geocoding queries against the search or structured search endpoints.
description: >-
The batch endpoint lets you specify many search or structured search requests at once.
Once received, all requests will be processed internally on our infrastructure,
improving throughput when you need to do a lot of queries.
security:
- ApiKeyAuth: [ ]
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/bulkSearchRequest'
responses:
'200':
description: >-
A JSON array of the individual query responses, each annotated with a status code.
Individual requests may fail but this endpoint will still return all results.
Responses will be in the same order as the input.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/bulkSearchResponse'
'400':
description: Bad request; more details will be included
/geocoding/v1/reverse:
get:
tags:
- Geocoding
operationId: reverse
summary: Find places and addresses near geographic coordinates (reverse geocoding).
description: >-
Reverse geocoding and search finds places and addresses near any geographic coordinates.
security:
- ApiKeyAuth: [ ]
parameters:
- $ref: '#/components/parameters/reverseLat'
- $ref: '#/components/parameters/reverseLon'
- $ref: '#/components/parameters/searchBoundaryCircleRadius'
- $ref: '#/components/parameters/searchLayers'
- $ref: '#/components/parameters/searchSources'
- $ref: '#/components/parameters/searchBoundaryCountry'
- $ref: '#/components/parameters/searchBoundaryGID'
- $ref: '#/components/parameters/size'
- $ref: '#/components/parameters/peliasLang'
responses:
'200':
description: A GeoJSON collection of search results.
content:
application/json:
schema:
$ref: '#/components/schemas/peliasResponse'
'400':
description: Bad request
/geocoding/v1/place:
get:
tags:
- Geocoding
operationId: place
summary: Retrieve details of a place using its GID.
description: >-
Many search result components include an associated GID field (for example, an address may have a
`localadmin_gid`). The place endpoint lets you look up these places directly by ID. Note that these
IDs are not stable for all sources. See the [online documentation](https://docs.stadiamaps.com/geocoding-search-autocomplete/place-lookup/)
for details.
security:
- ApiKeyAuth: [ ]
parameters:
- $ref: '#/components/parameters/placeIDs'
- $ref: '#/components/parameters/peliasLang'
responses:
'200':
description: A GeoJSON collection of search results.
content:
application/json:
schema:
$ref: '#/components/schemas/peliasResponse'
'400':
description: Bad request
components:
securitySchemes:
ApiKeyAuth:
type: apiKey
in: query
name: api_key
schemas:
requestId:
type: string
description: An identifier to disambiguate requests (echoed by the server).
example: kesklinn
coordinate:
type: object
properties:
lat:
type: number
format: double
description: The latitude of a point in the shape.
example: 59.436884
minimum: -90
maximum: 90
lon:
type: number
format: double
description: The longitude of a point in the shape.
example: 24.742595
minimum: -180
maximum: 180
required:
- lat
- lon
valhallaLongUnits:
type: string
enum:
- miles
- kilometers
default: kilometers
valhallaLanguages:
type: string
enum:
- bg-BG
- ca-ES
- cs-CZ
- da-DK
- de-DE
- el-GR
- en-GB
- en-US-x-pirate
- en-US
- es-ES
- et-EE
- fi-FI
- fr-FR
- hi-IN
- hu-HU
- it-IT
- ja-JP
- nb-NO
- nl-NL
- pl-PL
- pt-BR
- pt-PT
- ro-RO
- ru-RU
- sk-SK
- sl-SI
- sv-SE
- tr-TR
- uk-UA
default: en-US
simpleRoutingWaypoint:
allOf:
- $ref: '#/components/schemas/coordinate'
- type: object
properties:
type:
type: string
enum:
- break
- through
- via
- break_through
description: >-
A `break` represents the start or end of a leg, and allows reversals. A `through` location is an
intermediate waypoint that must be visited between `break`s, but at which reversals are not allowed.
A `via` is similar to a `through` except that reversals are allowed. A `break_through` is similar
to a `break` in that it can be the start/end of a leg, but does not allow reversals.
default: break
routingWaypoint:
allOf:
- $ref: '#/components/schemas/simpleRoutingWaypoint'
- type: object
properties:
heading:
type: integer
description: >-
The preferred direction of travel when starting the route, in integer clockwise degrees from north.
North is 0, south is 180, east is 90, and west is 270.
minimum: 0
maximum: 360
heading_tolerance:
type: integer
description: >-
The tolerance (in degrees) determining whether a street is considered the same direction.
minimum: 0
maximum: 360
default: 60
minimum_reachability:
type: integer
description: >-
The minimum number of nodes that must be reachable for a given edge to consider that edge as
belonging to a connected region. If a candidate edge has fewer connections, it will be considered
a disconnected island.
minimum: 0
default: 50
radius:
type: integer
description: >-
The distance (in meters) to look for candidate edges around the location for purposes of snapping
locations to the route graph. If there are no candidates within this distance, the closest candidate
within a reasonable search distance will be used. This is subject to clamping by internal limits.
minimum: 0
default: 0
rank_candidates:
type: boolean
description: >-
If true, candidates will be ranked according to their distance from the target location as well as other
factors. If false, candidates will only be ranked using their distance from the target.
default: true
preferred_side:
type: string
enum:
- same
- opposite
- either
description: >-
If the location is not offset from the road centerline or is closest to an intersection,
this option has no effect. Otherwise, the preferred side of street is used to determine
whether or not the location should be visited from the same, opposite or either side
of the road with respect to the side of the road the given locale drives on.
node_snap_tolerance:
type: integer
description: >-
During edge correlation this is the tolerance (in meters) used to determine whether or not to
snap to the intersection rather than along the street, if the snap location is within this
distance from the intersection, the intersection is used instead.
minimum: 0
default: 5
street_side_tolerance:
type: integer
description: >-
A tolerance in meters from the edge centerline used for determining the side of the street that the
location is on. If the distance to the centerline is less than this tolerance, no side will be
inferred. Otherwise, the left or right side will be selected depending on the direction of travel.
minimum: 0
default: 5
street_side_max_distance:
type: integer
description: >-
A tolerance in meters from the edge centerline used for determining the side of the street that the
location is on. If the distance to the centerline is greater than this tolerance, no side will be
inferred. Otherwise, the left or right side will be selected depending on the direction of travel.
minimum: 0
default: 1000
search_filter:
type: object
properties:
exclude_tunnel:
type: boolean
description: Excludes roads marked as tunnels
default: false
exclude_bridge:
type: boolean
description: Excludes roads marked as bridges
default: false
exclude_ramp:
type: boolean
description: Excludes roads marked as ramps
default: false
exclude_closures:
type: boolean
description: Excludes roads marked as closed
default: true
min_road_class:
description: The lowest road class allowed
default: service_other
allOf:
- $ref: '#/components/schemas/roadClass'
max_road_class:
description: The highest road class allowed
default: motorway
allOf:
- $ref: '#/components/schemas/roadClass'
routingResponseWaypoint:
allOf:
- $ref: '#/components/schemas/simpleRoutingWaypoint'
- type: object
properties:
original_index:
type: integer
description: The original index of the location (locations may be reordered for optimized routes)
minimum: 0
mapMatchWaypoint:
allOf:
- $ref: '#/components/schemas/simpleRoutingWaypoint'
- type: object
properties:
time:
type: integer
description: >-
The timestamp of the waypoint, in seconds. This can inform the map matching algorithm about when the
point was measured. A UNIX timestamp, or any increasing integer sequence measuring seconds from some
reference point can be used.
matrixWaypoint:
allOf:
- $ref: '#/components/schemas/coordinate'
- type: object
properties:
search_cutoff:
type: integer
description: >-
The cutoff (in meters) at which we will assume the input is too far away from civilisation to be worth correlating to the nearest graph elements.
The default is 35 km.
default: break
roadClass:
type: string
enum:
- motorway
- trunk
- primary
- secondary
- tertiary
- unclassified
- residential
- service_other
description: Class of road (ranked in descending order)
costingModel:
type: string
enum:
- auto
- bus
- taxi
- truck
- bicycle
- bikeshare
- motor_scooter
- motorcycle
- pedestrian
- low_speed_vehicle
description: >-
A model which influences the routing based on the type of travel.
The costing model affects parameters ranging from which roads are legally accessible
to preferences based on comfort or speed.
See https://valhalla.github.io/valhalla/api/turn-by-turn/api-reference/#costing-models
for in-depth descriptions of each costing model.
isochroneCostingModel:
type: string
enum:
- auto
- bus
- taxi
- truck
- bicycle
- bikeshare
- motor_scooter
- motorcycle
- pedestrian
- low_speed_vehicle
matrixCostingModel:
type: string
enum:
- auto
- bus
- taxi
- truck
- bicycle
- bikeshare
- motor_scooter
- motorcycle
- pedestrian
- low_speed_vehicle
mapMatchCostingModel:
type: string
enum:
- auto
- bus
- taxi
- truck
- bicycle
- bikeshare
- motor_scooter
- motorcycle
- pedestrian
- low_speed_vehicle
costingOptions:
type: object
properties:
auto:
$ref: '#/components/schemas/autoCostingOptions'
bus:
$ref: '#/components/schemas/autoCostingOptions'
taxi:
$ref: '#/components/schemas/autoCostingOptions'
truck:
$ref: '#/components/schemas/truckCostingOptions'
bicycle:
$ref: '#/components/schemas/bicycleCostingOptions'
motor_scooter:
$ref: '#/components/schemas/motorScooterCostingOptions'
motorcycle:
$ref: '#/components/schemas/motorcycleCostingOptions'
pedestrian:
$ref: '#/components/schemas/pedestrianCostingOptions'
low_speed_vehicle:
$ref: '#/components/schemas/lowSpeedVehicleCostingOptions'
useFerryCostingOption:
type: number
format: double
description: >-
A measure of willingness to take ferries. Values near 0 attempt to avoid ferries, and values near 1
will favour them. Note that as some routes may be impossible without ferries, 0 does not guarantee
avoidance of them.
default: 0.5
minimum: 0
maximum: 1
useLivingStreetsCostingOption:
type: number
format: double
description: >-
A measure of willingness to take living streets. Values near 0 attempt to avoid them, and values near 1
will favour them. Note that as some routes may be impossible without living streets, 0 does not guarantee
avoidance of them. The default value is 0 for trucks; 0.1 for other motor vehicles; 0.5 for bicycles;
and 0.6 for pedestrians.
minimum: 0
maximum: 1
useTracksCostingOption:
type: number
format: double
description: >-
A measure of willingness to take track roads. Values near 0 attempt to avoid them, and values near 1
will favour them. Note that as some routes may be impossible without track roads, 0 does not guarantee
avoidance of them. The default value is 0 for automobiles, busses, and trucks; and 0.5 for all other
costing modes.
minimum: 0
maximum: 1
servicePenaltyCostingOption:
type: integer
description: >-
A penalty applied to transitions to service roads. This penalty can be used to reduce
the likelihood of suggesting a route with service roads unless absolutely necessary.
The default penalty is 15 for cars, busses, motor scooters, and motorcycles; and zero for others.
serviceFactorCostingOption:
type: number
format: double
description: >-
A factor that multiplies the cost when service roads are encountered. The default is 1.2 for cars and
busses, and 1 for trucks, motor scooters, and motorcycles.
default: 1
useHillsCostingOption:
type: number
format: double
description: >-
A measure of willingness to take tackle hills. Values near 0 attempt to avoid hills and steeper grades
even if it means a longer route, and values near 1 indicates that the user does not fear them.
Note that as some routes may be impossible without hills, 0 does not guarantee
avoidance of them.
default: 0.5
minimum: 0
maximum: 1
baseCostingOptions:
type: object
properties:
maneuver_penalty:
type: integer
description: A penalty (in seconds) applied when transitioning between roads (determined by name).
default: 5
gate_cost:
type: integer
description: The estimated cost (in seconds) when a gate is encountered.
default: 15
gate_penalty:
type: integer
description: >-
A penalty (in seconds) applied to the route cost when a gate is encountered. This penalty can be used
to reduce the likelihood of suggesting a route with gates unless absolutely necessary.
default: 300
country_crossing_cost:
type: integer
description: The estimated cost (in seconds) when encountering an international border.
default: 600
country_crossing_penalty:
type: integer
description: >-
A penalty applied to transitions to international border crossings. This penalty can be used to reduce
the likelihood of suggesting a route with border crossings unless absolutely necessary.
default: 0
service_penalty:
$ref: '#/components/schemas/servicePenaltyCostingOption'
service_factor:
$ref: '#/components/schemas/serviceFactorCostingOption'
use_living_streets:
$ref: '#/components/schemas/useLivingStreetsCostingOption'
use_ferry:
$ref: '#/components/schemas/useFerryCostingOption'
ignore_restrictions:
type: boolean
description: >-
If set to true, ignores any restrictions (eg: turn and conditional restrictions).
Useful for matching GPS traces to the road network regardless of restrictions.
ignore_non_vehicular_restrictions:
type: boolean
description: >-
If set to true, ignores most restrictions (eg: turn and conditional restrictions),
but still respects restrictions that impact vehicle safety such as weight and size.
ignore_oneways:
type: boolean
description: >-
If set to true, ignores directional restrictions on roads.
Useful for matching GPS traces to the road network regardless of restrictions.
autoCostingOptions:
allOf:
- $ref: '#/components/schemas/baseCostingOptions'
- type: object
properties:
height:
type: number
format: double
description: The height of the automobile (in meters).
default: 1.9
width:
type: number
format: double
description: The width of the automobile (in meters).
default: 1.6
toll_booth_cost:
type: integer
description: The estimated cost (in seconds) when a toll booth is encountered.
default: 15
toll_booth_penalty:
type: integer
description: >-
A penalty (in seconds) applied to the route cost when a toll booth is encountered. This penalty can be
used to reduce the likelihood of suggesting a route with toll booths unless absolutely necessary.
default: 0
ferry_cost:
type: integer
description: The estimated cost (in seconds) when a ferry is encountered.
default: 300
use_highways:
type: number
format: double
description: >-
A measure of willingness to take highways. Values near 0 attempt to avoid highways, and values near 1
will favour them. Note that as some routes may be impossible without highways, 0 does not guarantee
avoidance of them.
default: 0.5
minimum: 0
maximum: 1
use_tolls:
type: number
format: double
description: >-
A measure of willingness to take toll roads. Values near 0 attempt to avoid tolls, and values near 1
will favour them. Note that as some routes may be impossible without tolls, 0 does not guarantee
avoidance of them.
default: 0.5
minimum: 0
maximum: 1
use_tracks:
$ref: '#/components/schemas/useTracksCostingOption'
top_speed:
type: integer
description: The top speed (in kph) that the vehicle is capable of travelling.
default: 140
minimum: 10
maximum: 252
shortest:
type: boolean
description: >-
If true changes the cost metric to be quasi-shortest (pure distance-based) costing. This will disable ALL
other costing factors.
default: false
ignore_closures:
type: boolean
description: >-
If true, ignores all known closures. This option cannot be set if `location.search_filter.exclude_closures`
is also specified.
default: false
include_hov2:
type: boolean
description: >-
If true, indicates the desire to include HOV roads with a 2-occupant requirement in the route
when advantageous.
default: false
include_hov3:
type: boolean
description: >-
If true, indicates the desire to include HOV roads with a 3-occupant requirement in the route
when advantageous.
default: false
include_hot:
type: boolean
description: >-
If true, indicates the desire to include toll roads which require the driver to pay a
toll if the occupant requirement isn't met
default: false
alley_factor:
type: number
format: double
description: A factor that multiplies the cost when alleys are encountered.
default: 1
truckCostingOptions:
allOf:
- $ref: '#/components/schemas/autoCostingOptions'
- type: object
properties:
height:
type: number
format: double
description: The height of the truck (in meters).
default: 4.11
width:
type: number
format: double
description: The width of the truck (in meters).
default: 2.6
length:
type: number
format: double
description: The length of the truck (in meters).
default: 21.64
weight:
type: number
format: double
description: The weight of the truck (in tonnes).
default: 21.77
axle_load:
type: number
format: double
description: The axle load of the truck (in tonnes).
default: 9.07
hazmat:
type: boolean
description: Whether or not the truck is carrying hazardous materials.
default: false
bicycleCostingOptions:
allOf:
- $ref: '#/components/schemas/baseCostingOptions'
- type: object
properties:
bicycle_type:
type: string
enum:
- Road
- Hybrid
- Cross
- Mountain
default: Hybrid
description: >-
The type of bicycle:
* Road: has narrow tires and is generally lightweight and designed for speed on paved surfaces
* Hybrid or City: designed for city riding or casual riding on roads and paths with good surfaces
* Cross: similar to a road bike, but has wider tires so it can handle rougher surfaces
* Mountain: able to handle most surfaces, but generally heavier and slower on paved surfaces
cycling_speed:
type: integer
description: >-
The average comfortable travel speed (in kph) along smooth, flat roads. The costing
will vary the speed based on the surface, bicycle type, elevation change, etc.
This value should be the average sustainable cruising speed the cyclist can maintain
over the entire route.
The default speeds are as follows based on bicycle type:
* Road - 25kph
* Cross - 20kph
* Hybrid - 18kph
* Mountain - 16kph
use_roads:
type: number
format: double
description: >-
A measure of willingness to use roads alongside other vehicles. Values near 0 attempt to avoid roads
and stay on cycleways, and values near 1 indicate the cyclist is more comfortable on roads.
default: 0.5
minimum: 0
maximum: 1
use_hills:
$ref: '#/components/schemas/useHillsCostingOption'
avoid_bad_surfaces:
type: number
format: double
description: >-
A measure of how much the cyclist wants to avoid roads with poor surfaces relative to the type of
bicycle being ridden. When 0, there is no penalization of roads with poorer surfaces, and only
bicycle speed is taken into account. As the value approaches 1, roads with poor surfaces relative
to the bicycle type receive a heaver penalty, so they will only be taken if they significantly
reduce travel time. When the value is 1, all bad surfaces are completely avoided from the route,
including the start and end points.
default: 0.25
minimum: 0
maximum: 1
bss_return_cost:
type: integer
description: The estimated cost (in seconds) to return a bicycle in `bikeshare` mode.
default: 120
bss_return_penalty:
type: integer
description: A penalty (in seconds) to return a bicycle in `bikeshare` mode.
default: 0
motorScooterCostingOptions:
allOf:
- $ref: '#/components/schemas/autoCostingOptions'
- type: object
properties:
use_primary:
type: number
format: double
description: >-
A measure of willingness to use primary roads. Values near 0 attempt to avoid primary roads
and stay on roads with lower speeds, and values near 1 indicate the rider is more comfortable on
these roads.
default: 0.5
minimum: 0
maximum: 1
use_hills:
type: number
format: double
description: >-
A measure of willingness to take tackle hills. Values near 0 attempt to avoid hills and steeper grades
even if it means a longer route, and values near 1 indicates that the rider does not fear them.
Note that as some routes may be impossible without hills, 0 does not guarantee
avoidance of them.
default: 0.5
minimum: 0
maximum: 1
motorcycleCostingOptions:
allOf:
- $ref: '#/components/schemas/autoCostingOptions'
- type: object
properties:
use_highways:
type: number
format: double
description: >-
A measure of willingness to use highways. Values near 0 attempt to avoid highways
and stay on roads with lower speeds, and values near 1 indicate the rider is more comfortable on
these roads.
default: 1.0
minimum: 0
maximum: 1
use_trails:
type: number
format: double
description: >-
A measure of the rider's sense of adventure. Values near 0 attempt to avoid highways
and stay on roads with potentially unsuitable terrain (trails, tracks, unclassified, or bad surfaces),
and values near 1 will tend to avoid major roads and route on secondary roads.
default: 0.0
minimum: 0
maximum: 1
pedestrianCostingOptions:
type: object
properties:
walking_speed:
type: integer
description: Walking speed in kph.
default: 5.1
minimum: 0.5
maximum: 25
walkway_factor:
type: number
format: double
description: A factor that multiplies the cost when walkways are encountered.
default: 1
sidewalk_factor:
type: number
format: double
description: A factor that multiplies the cost when sidewalks are encountered.
default: 1
alley_factor:
type: number
format: double
description: A factor that multiplies the cost when alleys are encountered.
default: 2
driveway_factor:
type: number
format: double
description: A factor that multiplies the cost when driveways are encountered.
default: 5
step_penalty:
type: integer
description: A penalty (in seconds) added to each transition onto a path with steps or stairs.
default: 30
use_ferry:
$ref: '#/components/schemas/useFerryCostingOption'
use_living_streets:
$ref: '#/components/schemas/useLivingStreetsCostingOption'
use_tracks:
$ref: '#/components/schemas/useTracksCostingOption'
use_hills:
$ref: '#/components/schemas/useHillsCostingOption'
use_lit:
type: number
format: double
description: >-
A measure of preference for streets that are lit. 0 indicates indifference toward lit streets,
and 1 indicates that unlit streets should be avoided.
Note that even with values near 1, there is no guarantee that the returned route will include
lit segments.
default: 0
minimum: 0
maximum: 1
service_penalty:
$ref: '#/components/schemas/servicePenaltyCostingOption'
service_factor:
$ref: '#/components/schemas/serviceFactorCostingOption'
max_hiking_difficulty:
type: integer
description: The maximum difficulty of hiking trails allowed. This corresponds to the OSM `sac_scale`.
default: 1
minimum: 1
maximum: 6
bss_rent_cost:
type: integer
description: The estimated cost (in seconds) to rent a bicycle from a sharing station in `bikeshare` mode.
default: 120
bss_rent_penalty:
type: integer
description: A penalty (in seconds) to rent a bicycle in `bikeshare` mode.
default: 0
lowSpeedVehicleCostingOptions:
allOf:
- $ref: '#/components/schemas/baseCostingOptions'
- type: object
properties:
vehicle_type:
type: string
enum:
- low_speed_vehicle
- golf_cart
default: low_speed_vehicle
description: >-
The type of vehicle:
* low_speed_vehicle (BETA): a low-speed vehicle which falls under a different regulatory and licensing regime than automobiles (ex: LSV in the US and Canada, Quadricycles in the EU, etc.)
* golf_cart: a street legal golf cart that is under a similar regulator regime as the generic LSV laws, but may need to follow special paths when available or abide by restrictions specific to golf carts.
top_speed:
type: integer
description: >-
The top speed (in kph) that the vehicle is capable of travelling.
This impacts travel time calculations as well as which roads are preferred.
A very low speed vehicle will tend to prefer lower speed roads even in the presence of other legal routes.
default: 35
minimum: 20
maximum: 60
max_allowed_speed_limit:
type: integer
description: >-
The maximum speed limit for highways on which it is legal for the vehicle to travel.
Defaults to 57 (kph; around 35 mph). Acceptable values range from 20 to 80.
Highways with *tagged* speed limits higher than this value will not be routed over (some caveats apply; this feature is still BETA).
default: 57
minimum: 20
maximum: 80
directionsOptions:
type: object
properties:
units:
$ref: '#/components/schemas/distanceUnit'
language:
$ref: '#/components/schemas/valhallaLanguages'
directions_type:
type: string
enum:
- none
- maneuvers
- instructions
default: instructions
description: >-
The level of directional narrative to include. Locations and times will always be returned,
but narrative generation verbosity can be controlled with this parameter.
extendedDirectionsOptions:
type: object
properties:
format:
type: string
enum:
- json
- osrm
description: >-
The output response format.
The default JSON format is extremely compact and ideal for web or data-constrained use cases
where you want to fetch additional attributes on demand in small chunks.
The OSRM format is much richer and is configurable with significantly more info
for turn-by-turn navigation use cases.
banner_instructions:
type: boolean
description: >-
Optionally includes helpful banners with timing information for turn-by-turn navigation.
This is only available in the OSRM format.
voice_instructions:
type: boolean
description: >-
Optionally includes voice instructions with timing information for turn-by-turn navigation.
This is only available in the OSRM format.
filters:
$ref: '#/components/schemas/annotationFilters'
annotationFilters:
type: object
properties:
action:
type: string
enum:
- include
- exclude
attributes:
type: array
items:
type: string
enum:
- shape_attributes.speed
- shape_attributes.speed_limit
- shape_attributes.time
- shape_attributes.length
description: >-
A set of granular attributes to include between every pair of coordinates along the route.
This can significantly increase the response size.
distanceUnit:
type: string
enum:
- km
- mi
default: km
matrixDistance:
type: object
properties:
distance:
type: number
format: double
nullable: true
description: >-
The distance (in `units`) between the location in `sources` at `from_index`
and the location in `targets` at `to_index`.
This value may be 0 in the case that the source and destination are the same,
and `null` if no route was found between the locations.
time:
type: integer
nullable: true
description: >-
The travel time (in seconds) between the location in `sources` at `from_index`
and the location in `targets` at `to_index`.
This value may be 0 in the case that the source and destination are the same,
and `null` if no route was found between the locations.
from_index:
type: integer
description: The index of the start location in the `sources` array.
to_index:
type: integer
description: The index of the end location in the `targets` array.
required:
- distance
- time
- from_index
- to_index
contour:
type: object
properties:
time:
type: number
format: double
description: The time in minutes for the contour. Mutually exclusive of distance.
example: 15
distance:
type: number
format: double
description: The distance in km for the contour. Mutually exclusive of time.
example: 10.0
color:
type: string
description: >-
The color for the output contour, specified as a hex value (without a leading `#`).
If no color is specified, one will be assigned automatically.
example: aabbcc
mapMatchTraceOptions:
type: object
properties:
search_radius:
type: integer
description: The search radius, in meters, when trying to match each trace point.
gps_accuracy:
type: number
format: double
description: The accuracy of the GPS, in meters.
breakage_distance:
type: number
format: double
description: The breaking distance, in meters, between trace points.
interpolation_distance:
type: number
format: double
description: The interpolation distance, in meters, beyond which trace points are merged together.
turn_penalty_factor:
type: integer
description: >-
Penalizes turns from one road segment to next. For a pedestrian trace, you may see a back-and-forth
motion along the streets of your path with the default settings. Try increasing the turn penalty factor
to 500 to reduce jitter in the output. Note that if GPS accuracy is already good, increasing this above
the default will usually negatively affect the quality of map matching.
traceAttributeKey:
type: string
enum:
- edge.names
- edge.length
- edge.speed
- edge.road_class
- edge.begin_heading
- edge.end_heading
- edge.begin_shape_index
- edge.end_shape_index
- edge.traversability
- edge.use
- edge.toll
- edge.unpaved
- edge.tunnel
- edge.bridge
- edge.roundabout
- edge.internal_intersection
- edge.drive_on_right
- edge.surface
- edge.sign.exit_number
- edge.sign.exit_branch
- edge.sign.exit_toward
- edge.sign.exit_name
- edge.travel_mode
- edge.vehicle_type
- edge.pedestrian_type
- edge.bicycle_type
- edge.transit_type
- edge.id
- edge.way_id
- edge.weighted_grade
- edge.max_upward_grade
- edge.max_downward_grade
- edge.mean_elevation
- edge.lane_count
- edge.cycle_lane
- edge.bicycle_network
- edge.sac_scale
- edge.sidewalk
- edge.density
- edge.speed_limit
- edge.truck_speed
- edge.truck_route
- node.intersecting_edge.begin_heading
- node.intersecting_edge.from_edge_name_consistency
- node.intersecting_edge.to_edge_name_consistency
- node.intersecting_edge.driveability
- node.intersecting_edge.cyclability
- node.intersecting_edge.walkability
- node.intersecting_edge.use
- node.intersecting_edge.road_class
- node.elapsed_time
- node.admin_index
- node.type
- node.fork
- node.time_zone
- osm_changeset
- shape
- admin.country_code
- admin.country_text
- admin.state_code
- admin.state_text
- matched.point
- matched.type
- matched.edge_index
- matched.begin_route_discontinuity
- matched.end_route_discontinuity
- matched.distance_along_edge
- matched.distance_from_trace_point
traceAttributeFilterOptions:
type: object
properties:
attributes:
type: array
items:
$ref: '#/components/schemas/traceAttributeKey'
minItems: 1
action:
type: string
enum:
- include
- exclude
description: Determines whether the list of attributes will be used as a whitelist or a blacklist.
required:
- attributes
- action
traceEdge:
type: object
properties:
names:
type: array
items:
type: string
description: The name(s) of the road at this edge, if any.
length:
type: number
format: double
description: The length of this edge in `units`.
speed:
type: integer
description: >-
The speed of this edge in `units`/hr, in terms of average/free-flow speed for routing purposes.
This is affected by any number of factors such as the road service, vehicle type, etc. and not
just the posted speed limits.
road_class:
$ref: '#/components/schemas/roadClass'
begin_heading:
type: integer
description: The direction at the beginning of an edge. The units are degrees clockwise from north.
end_heading:
type: integer
description: The direction at the end of an edge. The units are degrees clockwise from north.
begin_shape_index:
type: integer
description: Index into the list of shape points for the start of the edge.
end_shape_index:
type: integer
description: Index into the list of shape points for the end of the edge.
traversability:
$ref: '#/components/schemas/traversability'
use:
$ref: '#/components/schemas/edgeUse'
toll:
type: boolean
description: True if the edge has a toll.
unpaved:
type: boolean
description: True if the edge has rough payment.
tunnel:
type: boolean
description: True if the edge is a tunnel.
bridge:
type: boolean
description: True if the edge is a bridge.
roundabout:
type: boolean
description: True if the edge is a roundabout.
internal_intersection:
type: boolean
description: True if the edge is an internal intersection.
drive_on_right:
type: boolean
description: True if the edge is in an area where you must drive on the right side of the road.
surface:
type: string
enum:
- paved_smooth
- paved
- paved_rough
- compacted
- dirt
- gravel
- path
- impassable
description: The type of surface for the edge.
sign:
$ref: '#/components/schemas/edgeSign'
travel_mode:
$ref: '#/components/schemas/travelMode'
vehicle_type:
type: string
enum:
- car
- motorcycle
- bus
- tractor_trailer
- golf_cart
- low_speed_vehicle
pedestrian_type:
type: string
enum:
- foot
- wheelchair
- segway
bicycle_type:
type: string
enum:
- road
- cross
- hybrid
- mountain
transit_type:
type: string
enum:
- tram
- metro
- rail
- bus
- ferry
- cable_car
- gondola
- funicular
id:
type: integer
format: int64
way_id:
type: integer
format: int64
description: The way identifier of the edge in OSM.
weighted_grade:
type: number
format: double
description: >-
The weighted grade factor. The weighted grade is derived from elevation data.
It is a measure used for hill avoidance in routing - sort of a relative energy use along an edge.
But since an edge can possibly go up and down over several hills,
it might not equate to what you would normally think of as grade.
max_upward_grade:
type: integer
description: The maximum upward slope. A value of 32768 indicates no elevation data is available for this edge.
max_downward_grade:
type: integer
description: The maximum downward slope. A value of 32768 indicates no elevation data is available for this edge.
mean_elevation:
type: integer
description: >-
The mean elevation along the edge. Units are meters by default. If the `units` are specified
as miles, then the mean elevation is returned in feet. A value of 32768 indicates no elevation data is
available for this edge.
lane_count:
type: integer
description: The number of lanes for this edge.
cycle_lane:
type: string
enum:
- none
- shared
- dedicated
- separated
description: The type of cycle lane (if any) along this edge.
bicycle_network:
type: integer
description: >-
The type of bicycle network, if any. This is an integer comprised of constants bitwise or'd
together. For example, a route that's part of both a local and mountain network would have
a value of 12.
1 - National
2 - Regional
4 - Local
8 - Mountain
sac_scale:
type: integer
description: >-
The difficulty of the hiking trail according to the SAC scale.
0 - No Sac Scale
1 - Hiking
2 - Mountain hiking
3 - Demanding mountain hiking
4 - Alpine hiking
5 - Demanding alpine hiking
6 - Difficult alpine hiking
sidewalk:
type: string
enum:
- left
- right
- both
- none
density:
type: integer
speed_limit:
description: >-
The speed limit along the edge measured in `units`/hr. This may be either an integer or the string
"unlimited" if speed limit data is available. If absent, there is no speed limit data available.
truck_speed:
type: integer
description: >-
The truck speed of this edge in `units`/hr, in terms of average/free-flow speed for routing purposes.
This is affected by any number of factors such as the road service, vehicle type, etc. and not
just the posted speed limits.
truck_route:
type: boolean
description: True if the edge is part of a truck route/network.
end_node:
$ref: '#/components/schemas/endNode'
adminRegion:
type: object
properties:
country_code:
type: string
description: The [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code.
country_text:
type: string
description: The country name
state_code:
type: string
description: The abbreviation code for the state (varies by country).
state_text:
type: string
description: The state name.
matchedPoint:
type: object
properties:
lat:
type: number
format: double
description: The latitude of the matched point.
lon:
type: number
format: double
description: The longitude of the matched point.
type:
type: string
enum:
- unmatched
- interpolated
- matched
edge_index:
type: integer
description: The index of the edge in the list of `edges`. This key will be missing if the point is unmatched.
begin_route_discontinuity:
type: boolean
description: If true, this match result is the begin location of a route discontinuity.
default: false
end_route_discontinuity:
type: boolean
description: If true, this match result is the end location of a route discontinuity.
default: false
distance_along_edge:
type: number
format: double
description: >-
The distance along the associated edge for this matched point, expressed as a value between 0 and 1.
For example, if the matched point is halfway along the edge, then the value will be 0.5. This key
will be absent if the point is unmatched.
distance_from_trace_point:
type: number
format: double
description: >-
The distance in meters from the trace point to the matched point. This key will be absent if the
point is unmatched.
required:
- lat
- lon
- type
heightRequest:
type: object
properties:
id:
$ref: '#/components/schemas/requestId'
shape:
type: array
items:
$ref: '#/components/schemas/coordinate'
description: REQUIRED if `encoded_polyline` is not present.
encoded_polyline:
type: string
description: REQUIRED if `shape` is not present. An encoded polyline (https://developers.google.com/maps/documentation/utilities/polylinealgorithm).
shape_format:
type: string
enum:
- polyline6
- polyline5
default: polyline6
description: Specifies whether the polyline is encoded with 6 digit precision (polyline6) or 5 digit precision (polyline5).
range:
type: boolean
default: false
description: Controls whether or not the returned array is one-dimensional (height only) or two-dimensional (with a range and height). The range dimension can be used to generate a graph or steepness gradient along a route.
height_precision:
type: integer
default: 0
minimum: 0
maximum: 2
description: >-
The decimal precision (number of digits after the point) of the output.
When 0, integer values are returned. Valid values are 0, 1, and 2.
resample_distance:
type: integer
minimum: 10
description: >-
The distance at which the input polyline should be sampled to provide uniform distances between points.
If not set, the input shape will be used as-is.
example:
{
"id": "kesklinn",
"shape": [
{
"lat": 59.436884,
"lon": 24.742595
}
],
"shape_format": "polyline6",
"range": false,
"height_precision": 0
}
matrixRequest:
allOf:
- type: object
properties:
id:
$ref: '#/components/schemas/requestId'
sources:
type: array
items:
$ref: '#/components/schemas/matrixWaypoint'
description: The list of starting locations
minItems: 1
targets:
type: array
items:
$ref: '#/components/schemas/matrixWaypoint'
description: The list of ending locations
minItems: 1
costing:
$ref: '#/components/schemas/matrixCostingModel'
costing_options:
$ref: '#/components/schemas/costingOptions'
matrix_locations:
type: integer
description: >-
Only applicable to one-to-many or many-to-one requests. This defaults to all locations.
When specified explicitly, this option allows a partial result to be returned. This is basically
equivalent to "find the closest/best locations out of the full set." This can have a dramatic
improvement for large requests.
- $ref: '#/components/schemas/directionsOptions'
required:
- sources
- targets
- costing
example:
{
"sources": [
{
"lat": 40.744014,
"lon": -73.990508
}
],
"targets": [
{
"lat": 40.744014,
"lon": -73.990508
},
{
"lat": 40.739735,
"lon": -73.979713
},
{
"lat": 40.752522,
"lon": -73.985015
},
{
"lat": 40.750117,
"lon": -73.983704
},
{
"lat": 40.750552,
"lon": -73.993519
}
],
"costing": "pedestrian"
}
isochroneRequest:
type: object
properties:
id:
$ref: '#/components/schemas/requestId'
locations:
type: array
items:
$ref: '#/components/schemas/coordinate'
costing:
$ref: '#/components/schemas/isochroneCostingModel'
costing_options:
$ref: '#/components/schemas/costingOptions'
contours:
type: array
items:
$ref: '#/components/schemas/contour'
maxItems: 4
minItems: 1
polygons:
type: boolean
default: false
description: >-
If true, the generated GeoJSON will use polygons. The default is to use LineStrings.
Polygon output makes it easier to render overlapping areas in some visualization
tools (such as MapLibre renderers).
denoise:
type: number
format: double
default: 1
minimum: 0
maximum: 1
description: >-
A value in the range [0, 1] which will be used to smooth out or remove smaller contours.
A value of 1 will only return the largest contour for a given time value. A value of 0.5 drops any contours
that are less than half the area of the largest contour in the set of contours for that same time value.
generalize:
type: number
format: double
default: 200.0
description: >-
The value in meters to be used as a tolerance for Douglas-Peucker generalization.
show_locations:
type: boolean
default: false
description: >-
If true, then the output GeoJSON will include the input locations as two MultiPoint features: one
for the exact input coordinates, and a second for the route network node location that the point
was snapped to.
required:
- locations
- contours
- costing
example: >-
{
"id": "kesklinn",
"locations": [
{
"lat": 59.436884,
"lon": 24.742595
}
],
"costing": "pedestrian",
"contours": [
{
"time": 5,
"color": "aabbcc"
}
],
"polygons": true
}
routeRequest:
allOf:
- type: object
properties:
id:
$ref: '#/components/schemas/requestId'
locations:
type: array
items:
$ref: '#/components/schemas/routingWaypoint'
minItems: 2
costing:
$ref: '#/components/schemas/costingModel'
costing_options:
$ref: '#/components/schemas/costingOptions'
exclude_locations:
type: array
items:
$ref: '#/components/schemas/routingWaypoint'
description: >-
This has the same format as the locations list.
Locations are mapped to the closed road(s), and these road(s)
are excluded from the route path computation.
exclude_polygons:
type: array
items:
type: array
items:
type: array
items:
type: number
format: double
description: >-
One or multiple exterior rings of polygons in the form of nested JSON arrays.
Roads intersecting these rings will be avoided during path finding. Open rings will be
closed automatically.
If you only need to avoid a few specific roads, it's much more efficient to use `exclude_locations`.
example: [[[30, 10], [40, 40], [20, 40], [10, 20], [30, 10]]]
alternates:
type: integer
description: >-
How many alternate routes are desired. Note that fewer or no alternates may be returned.
Alternates are not yet supported on routes with more than 2 locations or on time-dependent routes.
elevation_interval:
$ref: '#/components/schemas/elevation_interval'
roundabout_exits:
type: boolean
description: >-
Determines whether the output should include roundabout exit instructions.
default: true
- $ref: '#/components/schemas/directionsOptions'
- $ref: '#/components/schemas/extendedDirectionsOptions'
required:
- locations
- costing
example:
{
"locations": [
{
"lon": -149.543469,
"lat": 60.5347155,
"type": "break"
},
{
"lon": -149.5485806,
"lat": 60.5349908,
"type": "break"
}
],
"costing": "auto",
"costing_options": {
"auto": {
"use_tolls": 1,
"use_highways": 0
}
},
"units": "miles"
}
optimizedRouteRequest:
allOf:
- type: object
properties:
id:
$ref: '#/components/schemas/requestId'
locations:
type: array
items:
$ref: '#/components/schemas/coordinate'
description: >-
The list of locations. The first and last are assumed to be the start and end points, and
all intermediate points are locations that you want to visit along the way.
minItems: 3
costing:
$ref: '#/components/schemas/matrixCostingModel'
costing_options:
$ref: '#/components/schemas/costingOptions'
elevation_interval:
$ref: '#/components/schemas/elevation_interval'
- $ref: '#/components/schemas/directionsOptions'
- $ref: '#/components/schemas/extendedDirectionsOptions'
required:
- locations
- costing
example:
{
"locations": [
{
"lat": 40.042072,
"lon": -76.306572
},
{
"lat": 39.992115,
"lon": -76.781559
},
{
"lat": 39.984519,
"lon": -76.6956
},
{
"lat": 39.996586,
"lon": -76.769028
},
{
"lat": 39.984322,
"lon": -76.706672
}
],
"costing": "auto",
"units": "miles"
}
nearestRoadsRequest:
allOf:
- type: object
properties:
locations:
type: array
items:
$ref: '#/components/schemas/coordinate'
minItems: 1
costing:
$ref: '#/components/schemas/costingModel'
costing_options:
$ref: '#/components/schemas/costingOptions'
verbose:
type: boolean
default: false
- $ref: '#/components/schemas/directionsOptions'
required:
- locations
example:
{
"locations": [
{
"lat": 59.436884,
"lon": 24.742595
}
],
"verbose": true
}
baseTraceRequest:
allOf:
- type: object
properties:
id:
$ref: '#/components/schemas/requestId'
shape:
type: array
items:
$ref: '#/components/schemas/mapMatchWaypoint'
description: >-
REQUIRED if `encoded_polyline` is not present. Note that `break` type locations are only supported
when `shape_match` is set to `map_match`.
encoded_polyline:
type: string
description: >-
REQUIRED if `shape` is not present. An encoded polyline
(https://developers.google.com/maps/documentation/utilities/polylinealgorithm). Note that the polyline
must be encoded with 6 digits of precision rather than the usual 5.
costing:
$ref: '#/components/schemas/mapMatchCostingModel'
costing_options:
$ref: '#/components/schemas/costingOptions'
shape_match:
type: string
enum:
- edge_walk
- map_snap
- walk_or_snap
description: >-
Three snapping modes provide some control over how the map matching occurs.
`edge_walk` is fast, but requires extremely precise data that matches the route graph
almost perfectly. `map_snap` can handle significantly noisier data, but is very expensive.
`walk_or_snap`, the default, tries to use edge walking first and falls back to map matching
if edge walking fails.
In general, you should not need to change this parameter unless you want to trace a multi-leg
route with multiple `break` locations in the `shape`.
- $ref: '#/components/schemas/directionsOptions'
required:
- costing
mapMatchRequest:
allOf:
- $ref: '#/components/schemas/baseTraceRequest'
- $ref: '#/components/schemas/extendedDirectionsOptions'
- type: object
properties:
begin_time:
type: integer
description: >-
The timestamp at the start of the trace. Combined with `durations`, this provides a way to
include timing information for an `encoded_polyline` trace.
durations:
type: integer
description: >-
A list of durations (in seconds) between each successive pair of points in a polyline.
use_timestamps:
type: boolean
description: >-
If true, the input timestamps or durations should be used when computing elapsed time
for each edge along the matched path rather than the routing algorithm estimates.
default: false
trace_options:
$ref: '#/components/schemas/mapMatchTraceOptions'
linear_references:
type: boolean
description: >-
If true, the response will include a `linear_references` value that contains an array of
base64-encoded [OpenLR location references](https://www.openlr-association.com/fileadmin/user_upload/openlr-whitepaper_v1.5.pdf),
one for each graph edge of the road network matched by the trace.
default: false
elevation_interval:
$ref: '#/components/schemas/elevation_interval'
example:
{
"encoded_polyline": "_grbgAh~{nhF?lBAzBFvBHxBEtBKdB?fB@dBZdBb@hBh@jBb@x@\\|@x@pB\\x@v@hBl@nBPbCXtBn@|@z@ZbAEbAa@~@q@z@QhA]pAUpAVhAPlAWtASpAAdA[dASdAQhAIlARjANnAZhAf@n@`A?lB^nCRbA\\xB`@vBf@tBTbCFbARzBZvBThBRnBNrBP`CHbCF`CNdCb@vBX`ARlAJfADhA@dAFdAP`AR`Ah@hBd@bBl@rBV|B?vB]tBCvBBhAF`CFnBXtAVxAVpAVtAb@|AZ`Bd@~BJfA@fAHdADhADhABjAGzAInAAjAB|BNbCR|BTjBZtB`@lBh@lB\\|Bl@rBXtBN`Al@g@t@?nAA~AKvACvAAlAMdAU`Ac@hAShAI`AJ`AIdAi@bAu@|@k@p@]p@a@bAc@z@g@~@Ot@Bz@f@X`BFtBXdCLbAf@zBh@fBb@xAb@nATjAKjAW`BI|AEpAHjAPdAAfAGdAFjAv@p@XlAVnA?~A?jAInAPtAVxAXnAf@tBDpBJpBXhBJfBDpAZ|Ax@pAz@h@~@lA|@bAnAd@hAj@tAR~AKxAc@xAShA]hAIdAAjA]~A[v@BhB?dBSv@Ct@CvAI~@Oz@Pv@dAz@lAj@~A^`B^|AXvAVpAXdBh@~Ap@fCh@hB\\zBN`Aj@xBFdA@jALbAPbAJdAHdAJbAHbAHfAJhALbA\\lBTvBAdC@bC@jCKjASbC?`CM`CDpB\\xAj@tB\\fA\\bAVfAJdAJbAXz@L|BO`AOdCDdA@~B\\z@l@v@l@v@l@r@j@t@b@x@b@r@z@jBVfCJdAJdANbCPfCF|BRhBS~BS`AYbAe@~BQdA",
"shape_match": "map_snap",
"costing": "pedestrian",
"units": "miles",
"linear_references": true
}
traceAttributesRequest:
allOf:
- $ref: '#/components/schemas/baseTraceRequest'
- type: object
properties:
filters:
description: >-
If present, provides either a whitelist or a blacklist of keys to include/exclude in the response.
This key is optional, and if omitted from the request, all available info will be returned.
allOf:
- $ref: '#/components/schemas/traceAttributeFilterOptions'
elevation_interval:
$ref: '#/components/schemas/elevation_interval'
example:
{
"encoded_polyline": "_grbgAh~{nhF?lBAzBFvBHxBEtBKdB?fB@dBZdBb@hBh@jBb@x@\\|@x@pB\\x@v@hBl@nBPbCXtBn@|@z@ZbAEbAa@~@q@z@QhA]pAUpAVhAPlAWtASpAAdA[dASdAQhAIlARjANnAZhAf@n@`A?lB^nCRbA\\xB`@vBf@tBTbCFbARzBZvBThBRnBNrBP`CHbCF`CNdCb@vBX`ARlAJfADhA@dAFdAP`AR`Ah@hBd@bBl@rBV|B?vB]tBCvBBhAF`CFnBXtAVxAVpAVtAb@|AZ`Bd@~BJfA@fAHdADhADhABjAGzAInAAjAB|BNbCR|BTjBZtB`@lBh@lB\\|Bl@rBXtBN`Al@g@t@?nAA~AKvACvAAlAMdAU`Ac@hAShAI`AJ`AIdAi@bAu@|@k@p@]p@a@bAc@z@g@~@Ot@Bz@f@X`BFtBXdCLbAf@zBh@fBb@xAb@nATjAKjAW`BI|AEpAHjAPdAAfAGdAFjAv@p@XlAVnA?~A?jAInAPtAVxAXnAf@tBDpBJpBXhBJfBDpAZ|Ax@pAz@h@~@lA|@bAnAd@hAj@tAR~AKxAc@xAShA]hAIdAAjA]~A[v@BhB?dBSv@Ct@CvAI~@Oz@Pv@dAz@lAj@~A^`B^|AXvAVpAXdBh@~Ap@fCh@hB\\zBN`Aj@xBFdA@jALbAPbAJdAHdAJbAHbAHfAJhALbA\\lBTvBAdC@bC@jCKjASbC?`CM`CDpB\\xAj@tB\\fA\\bAVfAJdAJbAXz@L|BO`AOdCDdA@~B\\z@l@v@l@v@l@r@j@t@b@x@b@r@z@jBVfCJdAJdANbCPfCF|BRhBS~BS`AYbAe@~BQdA",
"shape_match": "map_snap",
"costing": "pedestrian",
"units": "miles"
}
searchQuery:
type: object
properties:
text:
$ref: '#/components/schemas/searchText'
focus.point.lat:
$ref: '#/components/schemas/searchFocusLat'
focus.point.lon:
$ref: '#/components/schemas/searchFocusLon'
boundary.rect.min_lat:
$ref: '#/components/schemas/searchBoundaryRectMinLat'
boundary.rect.max_lat:
$ref: '#/components/schemas/searchBoundaryRectMaxLat'
boundary.rect.min_lon:
$ref: '#/components/schemas/searchBoundaryRectMinLon'
boundary.rect.max_lon:
$ref: '#/components/schemas/searchBoundaryRectMaxLon'
boundary.circle.lat:
$ref: '#/components/schemas/searchBoundaryCircleLat'
boundary.circle.lon:
$ref: '#/components/schemas/searchBoundaryCircleLon'
boundary.circle.radius:
$ref: '#/components/schemas/searchBoundaryCircleRadius'
boundary.country:
$ref: '#/components/schemas/searchBoundaryCountry'
boundary.gid:
$ref: '#/components/schemas/searchBoundaryGID'
layers:
$ref: '#/components/schemas/searchLayers'
sources:
$ref: '#/components/schemas/searchSources'
size:
$ref: '#/components/schemas/limit'
lang:
$ref: '#/components/schemas/peliasLang'
searchStructuredQuery:
type: object
properties:
address:
$ref: '#/components/schemas/searchAddress'
neighbourhood:
$ref: '#/components/schemas/searchNeighborhood'
borough:
$ref: '#/components/schemas/searchBorough'
locality:
$ref: '#/components/schemas/searchLocality'
county:
$ref: '#/components/schemas/searchCounty'
region:
$ref: '#/components/schemas/searchRegion'
postalCode:
$ref: '#/components/schemas/postalCode'
country:
$ref: '#/components/schemas/searchCountry'
focus.point.lat:
$ref: '#/components/schemas/searchFocusLat'
focus.point.lon:
$ref: '#/components/schemas/searchFocusLon'
boundary.rect.min_lat:
$ref: '#/components/schemas/searchBoundaryRectMinLat'
boundary.rect.max_lat:
$ref: '#/components/schemas/searchBoundaryRectMaxLat'
boundary.rect.min_lon:
$ref: '#/components/schemas/searchBoundaryRectMinLon'
boundary.rect.max_lon:
$ref: '#/components/schemas/searchBoundaryRectMaxLon'
boundary.circle.lat:
$ref: '#/components/schemas/searchBoundaryCircleLat'
boundary.circle.lon:
$ref: '#/components/schemas/searchBoundaryCircleLon'
boundary.circle.radius:
$ref: '#/components/schemas/searchBoundaryCircleRadius'
boundary.country:
$ref: '#/components/schemas/searchBoundaryCountry'
boundary.gid:
$ref: '#/components/schemas/searchBoundaryGID'
layers:
$ref: '#/components/schemas/searchLayers'
sources:
$ref: '#/components/schemas/searchSources'
size:
$ref: '#/components/schemas/limit'
lang:
$ref: '#/components/schemas/peliasLang'
bulkSearchRequest:
type: array
items:
title: BulkRequest
type: object
properties:
endpoint:
type: string
enum:
- /v1/search
- /v1/search/structured
query:
oneOf:
- $ref: '#/components/schemas/searchQuery'
- $ref: '#/components/schemas/searchStructuredQuery'
example:
[
{ "endpoint": "/v1/search", "query": { "text": "Põhja pst 27" } },
{
"endpoint": "/v1/search/structured",
"query": {
"address": "Põhja pst 27",
"country": "EE",
"locality": "Tallinn",
"layers": [ "coarse", "address" ]
}
}
]
tzResponse:
type: object
properties:
tz_id:
type: string
description: >-
The canonical time zone ID. In the event that multiple time zones could
be returned, the first one from the Unicode CLDR timezone.xml is returned.
base_utc_offset:
type: integer
description: The base offset, in seconds, from UTC that is normally in effect for this time zone.
dst_offset:
type: integer
description: >-
The special offset, in seconds, from UTC that is in effect for this time zone as
of the queried timestamp (defaults to now). If no additional offsets are in effect,
this value is zero. This typically reflects Daylight Saving Time, but may indicate
other special offsets. To get the total offset
in effect, add `dst_offset` and `utc_offset` together.
required:
- tz_id
- base_utc_offset
- dst_offset
example:
{
"tz_id": "Europe/Zurich",
"base_utc_offset": 3600,
"dst_offset": 3600
}
maneuverSignElement:
type: object
properties:
text:
type: string
description: The interchange sign text (varies based on the context; see the `maneuverSign` schema).
is_route_number:
type: boolean
description: True if the sign is a route number.
consecutive_count:
type: integer
description: The frequency of this sign element within a set a consecutive signs.
required:
- text
maneuverSign:
type: object
properties:
exit_number_elements:
type: array
description: A list of exit number elements. This is typically just a single value.
items:
$ref: '#/components/schemas/maneuverSignElement'
exit_branch_elements:
type: array
description: >-
A list of exit branch elements. The text is a subsequent road name or route number after the sign.
items:
$ref: '#/components/schemas/maneuverSignElement'
exit_toward_elements:
type: array
description: >-
A list of exit name elements. The text is the interchange identifier (used more frequently outside
the US).
items:
$ref: '#/components/schemas/maneuverSignElement'
exit_name_elements:
type: array
description: >-
A list of exit name elements. The text is the location where the road ahead goes
(typically a city, but occasionally a road name or route number).
items:
$ref: '#/components/schemas/maneuverSignElement'
travelMode:
type: string
enum:
- drive
- pedestrian
- bicycle
- transit
edgeSign:
type: object
properties:
exit_number:
type: array
items:
type: string
description: An exit number.
example: 91B
exit_branch:
type: array
items:
type: string
description: A subsequent road name or route number after the sign.
example: I 95 North
exit_toward:
type: array
items:
type: string
description: The interchange identifier (used more frequently outside the US).
example: New York
exit_name:
type: array
items:
type: string
description: >-
The location where the road ahead goes (typically a city, but occasionally a road name or route number).
example: Gettysburg Pike
traversability:
type: string
description: The directions in which the edge is traversable.
enum:
- forward
- backward
- both
edgeUse:
type: string
enum:
- road
- ramp
- turn_channel
- track
- driveway
- alley
- parking_aisle
- emergency_access
- drive_through
- culdesac
- living_street
- service_road
- cycleway
- mountain_bike
- sidewalk
- footway
- steps
- path
- pedestrian
- pedestrian_crossing
- bridleway
- rest_area
- service_area
- other
- ferry
- rail-ferry
- rail
- bus
- egress_connection
- platform_connection
- transit_connection
description: The use for the edge.
intersectingEdge:
type: object
properties:
begin_heading:
type: integer
description: The direction at the beginning of an edge. The units are degrees clockwise from north.
from_edge_name_consistency:
type: boolean
description: >-
True if this intersecting edge at the end node has consistent names with the path from the other edge.
to_edge_name_consistency:
type: boolean
description: >-
True if this intersecting edge at the end node has consistent names with the path to the other edge.
driveability:
$ref: '#/components/schemas/traversability'
cyclability:
$ref: '#/components/schemas/traversability'
walkability:
$ref: '#/components/schemas/traversability'
use:
$ref: '#/components/schemas/edgeUse'
road_class:
$ref: '#/components/schemas/roadClass'
nodeType:
type: string
enum:
- street_intersection
- gate
- bollard
- toll_booth
- multi_use_transit_stop
- bike_share
- parking
- motor_way_junction
- border_control
endNode:
type: object
description: The node at the end of this edge
properties:
intersecting_edges:
type: array
items:
$ref: '#/components/schemas/intersectingEdge'
description: A set of edges intersecting this node.
elapsed_time:
type: number
format: double
description: The elapsed time along the path to arrive at this node.
admin_index:
type: integer
description: The index into the `admins` list in which this node lies.
type:
$ref: '#/components/schemas/nodeType'
fork:
type: boolean
description: True if this node is a fork.
time_zone:
type: string
description: The canonical TZDB identifier for the node's time zone.
example: America/New_York
transitInfo:
type: object
description: Public transit info (not currently supported).
additionalProperties: true
routeSummary:
type: object
properties:
time:
type: number
format: double
description: The estimated travel time, in seconds
length:
type: number
format: double
description: The estimated travel distance, in `units` (km or mi)
min_lat:
type: number
format: double
description: The minimum latitude of the bounding box containing the route.
max_lat:
type: number
format: double
description: The maximum latitude of the bounding box containing the route.
min_lon:
type: number
format: double
description: The minimum longitude of the bounding box containing the route.
max_lon:
type: number
format: double
description: The maximum longitude of the bounding box containing the route.
required:
- time
- length
- min_lat
- min_lon
- max_lat
- max_lon
routeManeuver:
type: object
properties:
type:
type: integer
description: |
The type of route maneuver.
| Code | Type |
|------|-------------------------------------|
| 0 | None |
| 1 | Start |
| 2 | Start right |
| 3 | Start left |
| 4 | Destination |
| 5 | Destination right |
| 6 | Destination left |
| 7 | Becomes |
| 8 | Continue |
| 9 | Slight right |
| 10 | Right |
| 11 | Sharp right |
| 12 | U-turn right |
| 13 | U-turn left |
| 14 | Sharp left |
| 15 | Left |
| 16 | Slight left |
| 17 | Ramp straight |
| 18 | Ramp right |
| 19 | Ramp left |
| 20 | Exit right |
| 21 | Exit left |
| 22 | Stay straight |
| 23 | Stay right |
| 24 | Stay left |
| 25 | Merge |
| 26 | Enter roundabout |
| 27 | Exit roundabout |
| 28 | Enter ferry |
| 29 | Exit ferry |
| 30 | Transit |
| 31 | Transit transfer |
| 32 | Transit remain on |
| 33 | Transit connection start |
| 34 | Transit connection transfer |
| 35 | Transit connection destination |
| 36 | Post-transit connection destination |
| 37 | Merge right |
| 38 | Merge left |
instruction:
type: string
description: The written maneuver instruction.
verbal_transition_alert_instruction:
type: string
description: Text suitable for use as a verbal navigation alert.
verbal_pre_transition_instruction:
type: string
description: Text suitable for use as a verbal navigation alert immediately prior to the maneuver transition.
verbal_post_transition_instruction:
type: string
description: Text suitable for use as a verbal navigation alert immediately after to the maneuver transition.
street_names:
type: array
description: A list of street names that are consistent along the entire maneuver.
items:
type: string
example: A1
begin_street_names:
type: array
description: >-
A list of street names at the beginning of the maneuver, if they are different from the names at the end.
items:
type: string
example: A1
time:
type: number
format: double
description: The estimated time to complete the entire maneuver, in seconds.
length:
type: number
format: double
description: The length of the maneuver, in `units`.
begin_shape_index:
type: integer
description: The index into the list of shape points for the start of the maneuver.
end_shape_index:
type: integer
description: The index into the list of shape points for the end of the maneuver.
toll:
type: boolean
description: True any portion of the maneuver is subject to a toll.
default: false
rough:
type: boolean
description: True any portion of the maneuver is unpaved or has portions of rough pavement.
default: false
gate:
type: boolean
description: True if a gate is encountered in the course of this maneuver.
default: false
ferry:
type: boolean
description: True if a ferry is encountered in the course of this maneuver.
default: false
sign:
$ref: '#/components/schemas/maneuverSign'
roundabout_exit_count:
type: integer
description: The exit number of the roundabout to take after entering.
depart_instruction:
type: integer
description: The written departure time instruction (typically used in a transit maneuver).
example: "Depart: 8:04 AM from Seoul Station"
verbal_depart_instruction:
type: integer
description: Text suitable for use as a verbal departure time instruction (typically used in a transit maneuver).
example: "Depart at 8:04 AM from Seoul Station"
arrive_instruction:
type: integer
description: The written arrival time instruction (typically used in a transit maneuver).
example: "Arrive: 8:06 AM at City Hall"
verbal_arrive_instruction:
type: integer
description: Text suitable for use as a verbal departure time instruction (typically used in a transit maneuver).
example: "Arrive at 8:06 AM at City Hall"
transit_info:
$ref: '#/components/schemas/transitInfo'
verbal_multi_cue:
type: boolean
description: >-
True if the `verbal_pre_transition_instruction` has been appended with the verbal instruction
of the next maneuver.
default: false
travel_mode:
$ref: '#/components/schemas/travelMode'
travel_type:
type: string
description: >-
The type of travel over the maneuver. This can be thought of as a specialization of the travel mode. For
example, vehicular travel may be via car, motorcycle, etc.; and travel via bicycle may be via a road bike,
mountain bike, etc.
enum:
- car
- motorcycle
- bus
- tractor_trailer
- motor_scooter
- foot
- wheelchair
- segway
- road
- cross
- hybrid
- mountain
- tram
- metro
- rail
- ferry
- cable_car
- gondola
- funicular
- golf_cart
- low_speed_vehicle
bss_maneuver_type:
type: string
description: Describes a bike share action when using bikeshare routing.
enum:
- NoneAction
- RentBikeAtBikeShare
- ReturnBikeAtBikeShare
required:
- type
- instruction
- time
- length
- cost
- begin_shape_index
- end_shape_index
- travel_mode
- travel_type
routeLeg:
type: object
properties:
maneuvers:
type: array
items:
$ref: '#/components/schemas/routeManeuver'
minItems: 1
shape:
type: string
description: >-
An encoded polyline (https://developers.google.com/maps/documentation/utilities/polylinealgorithm) with
6 digits of decimal precision.
summary:
$ref: '#/components/schemas/routeSummary'
elevation_interval:
type: number
format: float
description: >-
The sampling distance between elevation values along the route.
This echoes the request parameter having the same name (converted to `units` if necessary).
elevation:
type: array
items:
type: number
format: float
description: >-
An array of elevation values sampled every `elevation_interval`.
Units are either metric or imperial depending on the value of `units`.
required:
- maneuvers
- shape
- summary
routeTrip:
type: object
properties:
status:
type: integer
description: The response status code
status_message:
type: string
description: The response status message
units:
$ref: '#/components/schemas/valhallaLongUnits'
language:
$ref: '#/components/schemas/valhallaLanguages'
locations:
type: array
items:
$ref: '#/components/schemas/routingResponseWaypoint'
legs:
type: array
items:
$ref: '#/components/schemas/routeLeg'
summary:
$ref: '#/components/schemas/routeSummary'
required:
- status
- status_message
- units
- language
- locations
- legs
- summary
routeResponse:
type: object
required:
- trip
properties:
id:
$ref: '#/components/schemas/requestId'
trip:
$ref: '#/components/schemas/routeTrip'
alternates:
type: array
items:
type: object
properties:
trip:
$ref: '#/components/schemas/routeTrip'
example:
{
"trip": {
"locations": [
{
"type": "break",
"lat": 60.534715,
"lon": -149.543469,
"original_index": 0
},
{
"type": "break",
"lat": 60.53499,
"lon": -149.54858,
"original_index": 1
}
],
"legs": [
{
"maneuvers": [
{
"type": 1,
"instruction": "Drive west on AK 1/Seward Highway.",
"verbal_pre_transition_instruction": "Drive west on Alaska 1, Seward Highway. Then You will arrive at your destination.",
"verbal_post_transition_instruction": "Continue for 900 feet.",
"street_names": [
"AK 1",
"Seward Highway"
],
"time": 11.487,
"length": 0.176,
"cost": 15.508,
"begin_shape_index": 0,
"end_shape_index": 9,
"verbal_multi_cue": true,
"travel_mode": "drive",
"travel_type": "car"
},
{
"type": 4,
"instruction": "You have arrived at your destination.",
"verbal_transition_alert_instruction": "You will arrive at your destination.",
"verbal_pre_transition_instruction": "You have arrived at your destination.",
"time": 0.0,
"length": 0.0,
"cost": 0.0,
"begin_shape_index": 9,
"end_shape_index": 9,
"travel_mode": "drive",
"travel_type": "car"
}
],
"summary": {
"has_time_restrictions": false,
"min_lat": 60.534715,
"min_lon": -149.54858,
"max_lat": 60.535008,
"max_lon": -149.543469,
"time": 11.487,
"length": 0.176,
"cost": 15.508
},
"shape": "wzvmrBxalf|GcCrX}A|Nu@jI}@pMkBtZ{@x^_Afj@Inn@`@veB"
}
],
"summary": {
"has_time_restrictions": false,
"min_lat": 60.534715,
"min_lon": -149.54858,
"max_lat": 60.535008,
"max_lon": -149.543469,
"time": 11.487,
"length": 0.176,
"cost": 15.508
},
"status_message": "Found route between points",
"status": 0,
"units": "miles",
"language": "en-US"
}
}
nearestRoadsResponse:
type: array
items:
$ref: '#/components/schemas/locateObject'
example:
[
{
"input_lon": 24.742595,
"input_lat": 59.436884,
"nodes": [ ],
"edges": [
{
"predicted_speeds": [ ],
"linear_reference": "KxGYOypEIXriAAAcABo6Uow=",
"edge_info": {
"speed_limit": 0,
"shape": "{zvjpBwtden@zG`H~EdG",
"names": [
"Rataskaevu"
],
"bike_network": {
"mountain": false,
"local": false,
"regional": false,
"national": false
},
"mean_elevation": 36,
"way_id": 4853850
},
"edge_id": {
"id": 1800,
"value": 60404861586,
"tile_id": 860498,
"level": 2
},
"edge": {
"sidewalk_left": false,
"sidewalk_right": false,
"lane_count": 1,
"not_thru": false,
"forward": false,
"bike_network": false,
"round_about": false,
"access": {
"truck": true,
"pedestrian": true,
"wheelchair": true,
"taxi": true,
"HOV": true,
"emergency": false,
"motorcycle": true,
"car": true,
"moped": true,
"bus": true,
"bicycle": true,
"golf_cart": true
},
"bridge": false,
"tunnel": false,
"destination_only": false,
"seasonal": false,
"classification": {
"internal": false,
"link": false,
"surface": "paved",
"use": "living_street",
"classification": "service_other"
},
"toll": false,
"has_sign": false,
"country_crossing": false,
"part_of_complex_restriction": false,
"cycle_lane": "none",
"end_restriction": {
"truck": false,
"pedestrian": false,
"wheelchair": false,
"taxi": false,
"HOV": false,
"emergency": false,
"motorcycle": false,
"car": false,
"moped": false,
"bus": false,
"bicycle": false
},
"geo_attributes": {
"curvature": 5,
"max_down_slope": -7.00,
"max_up_slope": 0.00,
"weighted_grade": -6.67,
"length": 32
},
"start_restriction": {
"truck": false,
"pedestrian": false,
"wheelchair": false,
"taxi": false,
"HOV": false,
"emergency": false,
"motorcycle": false,
"car": false,
"moped": false,
"bus": false,
"bicycle": false
},
"traffic_signal": false,
"access_restriction": false,
"truck_route": false,
"speeds": {
"predicted": false,
"constrained_flow": 0,
"free_flow": 0,
"type": "classified",
"default": 20
},
"end_node": {
"id": 2895,
"value": 97146964626,
"tile_id": 860498,
"level": 2
}
},
"inbound_reach": 50,
"distance": 2.2,
"percent_along": 0.54802,
"side_of_street": "neither",
"outbound_reach": 50,
"correlated_lon": 24.742630,
"live_speed": { },
"correlated_lat": 59.436875
},
{
"predicted_speeds": [ ],
"linear_reference": "KxGYSCpELHryAP/l/+k6QnM=",
"edge_info": {
"speed_limit": 0,
"shape": "{zvjpBwtden@zG`H~EdG",
"names": [
"Rataskaevu"
],
"bike_network": {
"mountain": false,
"local": false,
"regional": false,
"national": false
},
"mean_elevation": 36,
"way_id": 4853850
},
"edge_id": {
"id": 7368,
"value": 247235938962,
"tile_id": 860498,
"level": 2
},
"edge": {
"sidewalk_left": false,
"sidewalk_right": false,
"lane_count": 1,
"not_thru": false,
"forward": true,
"bike_network": false,
"round_about": false,
"access": {
"truck": true,
"pedestrian": true,
"wheelchair": true,
"taxi": true,
"HOV": true,
"emergency": false,
"motorcycle": true,
"car": true,
"moped": true,
"bus": true,
"bicycle": true
},
"bridge": false,
"tunnel": false,
"destination_only": false,
"seasonal": false,
"classification": {
"internal": false,
"link": false,
"surface": "paved",
"use": "living_street",
"classification": "service_other"
},
"toll": false,
"has_sign": false,
"country_crossing": false,
"part_of_complex_restriction": false,
"cycle_lane": "none",
"end_restriction": {
"truck": false,
"pedestrian": false,
"wheelchair": false,
"taxi": false,
"HOV": false,
"emergency": false,
"motorcycle": false,
"car": false,
"moped": false,
"bus": false,
"bicycle": false
},
"geo_attributes": {
"curvature": 5,
"max_down_slope": 0.00,
"max_up_slope": 7.00,
"weighted_grade": 6.67,
"length": 32
},
"start_restriction": {
"truck": false,
"pedestrian": false,
"wheelchair": false,
"taxi": false,
"HOV": false,
"emergency": false,
"motorcycle": false,
"car": false,
"moped": false,
"bus": false,
"bicycle": false
},
"traffic_signal": false,
"access_restriction": false,
"truck_route": false,
"speeds": {
"predicted": false,
"constrained_flow": 0,
"free_flow": 0,
"type": "classified",
"default": 20
},
"end_node": {
"id": 819,
"value": 27487963794,
"tile_id": 860498,
"level": 2
}
},
"inbound_reach": 50,
"distance": 2.2,
"percent_along": 0.45198,
"side_of_street": "neither",
"outbound_reach": 50,
"correlated_lon": 24.742630,
"live_speed": { },
"correlated_lat": 59.436875
}
]
}
]
mapMatchRouteResponse:
allOf:
- $ref: '#/components/schemas/routeResponse'
- type: object
properties:
linear_references:
type: array
items:
type: string
description: >-
A base64-encoded [OpenLR location reference](https://www.openlr-association.com/fileadmin/user_upload/openlr-whitepaper_v1.5.pdf),
for a graph edge of the road network matched by the trace.
example:
{
"trip": {
"locations": [
{
"type": "break",
"lat": 37.807744,
"lon": -122.4197
},
{
"type": "break",
"lat": 37.803694,
"lon": -122.428416
}
],
"legs": [
{
"maneuvers": [
{
"type": 1,
"instruction": "Walk west on the walkway.",
"verbal_pre_transition_instruction": "Walk west on the walkway.",
"verbal_post_transition_instruction": "Continue for 200 feet.",
"time": 44.733,
"length": 0.039,
"cost": 44.733,
"begin_shape_index": 0,
"end_shape_index": 1,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 15,
"instruction": "Turn left.",
"verbal_transition_alert_instruction": "Turn left.",
"verbal_pre_transition_instruction": "Turn left. Then Turn right onto Jefferson Street.",
"verbal_post_transition_instruction": "Continue for 20 feet.",
"time": 4.941,
"length": 0.004,
"cost": 4.941,
"begin_shape_index": 1,
"end_shape_index": 2,
"verbal_multi_cue": true,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 10,
"instruction": "Turn right onto Jefferson Street.",
"verbal_transition_alert_instruction": "Turn right onto Jefferson Street.",
"verbal_pre_transition_instruction": "Turn right onto Jefferson Street.",
"verbal_post_transition_instruction": "Continue for 80 feet.",
"street_names": [
"Jefferson Street"
],
"time": 16.941,
"length": 0.014,
"cost": 21.941,
"begin_shape_index": 2,
"end_shape_index": 3,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 15,
"instruction": "Turn left onto the walkway.",
"verbal_transition_alert_instruction": "Turn left onto the walkway.",
"verbal_pre_transition_instruction": "Turn left onto the walkway. Then Turn right onto the walkway.",
"verbal_post_transition_instruction": "Continue for 20 feet.",
"time": 4.941,
"length": 0.004,
"cost": 9.941,
"begin_shape_index": 3,
"end_shape_index": 4,
"verbal_multi_cue": true,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 10,
"instruction": "Turn right onto the walkway.",
"verbal_transition_alert_instruction": "Turn right onto the walkway.",
"verbal_pre_transition_instruction": "Turn right onto the walkway. Then Turn left onto Hyde Street.",
"verbal_post_transition_instruction": "Continue for 30 feet.",
"time": 6.352,
"length": 0.005,
"cost": 6.352,
"begin_shape_index": 4,
"end_shape_index": 5,
"verbal_multi_cue": true,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 15,
"instruction": "Turn left onto Hyde Street.",
"verbal_transition_alert_instruction": "Turn left onto Hyde Street.",
"verbal_pre_transition_instruction": "Turn left onto Hyde Street.",
"verbal_post_transition_instruction": "Continue for 300 feet.",
"street_names": [
"Hyde Street"
],
"time": 58.588,
"length": 0.051,
"cost": 63.588,
"begin_shape_index": 5,
"end_shape_index": 10,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 10,
"instruction": "Turn right onto the walkway.",
"verbal_transition_alert_instruction": "Turn right onto the walkway.",
"verbal_pre_transition_instruction": "Turn right onto the walkway. Then Turn left onto the walkway.",
"verbal_post_transition_instruction": "Continue for 30 feet.",
"time": 6.352,
"length": 0.005,
"cost": 11.352,
"begin_shape_index": 10,
"end_shape_index": 11,
"rough": true,
"verbal_multi_cue": true,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 15,
"instruction": "Turn left onto the walkway.",
"verbal_transition_alert_instruction": "Turn left onto the walkway.",
"verbal_pre_transition_instruction": "Turn left onto the walkway.",
"verbal_post_transition_instruction": "Continue for 400 feet.",
"time": 93.176,
"length": 0.082,
"cost": 93.176,
"begin_shape_index": 11,
"end_shape_index": 17,
"rough": true,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 15,
"instruction": "Turn left onto the walkway.",
"verbal_transition_alert_instruction": "Turn left onto the walkway.",
"verbal_pre_transition_instruction": "Turn left onto the walkway. Then Turn right onto Beach Street.",
"verbal_post_transition_instruction": "Continue for 40 feet.",
"time": 7.764,
"length": 0.006,
"cost": 7.764,
"begin_shape_index": 17,
"end_shape_index": 18,
"rough": true,
"verbal_multi_cue": true,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 10,
"instruction": "Turn right onto Beach Street.",
"verbal_transition_alert_instruction": "Turn right onto Beach Street.",
"verbal_pre_transition_instruction": "Turn right onto Beach Street.",
"verbal_post_transition_instruction": "Continue for 500 feet.",
"street_names": [
"Beach Street"
],
"time": 110.705,
"length": 0.095,
"cost": 115.705,
"begin_shape_index": 18,
"end_shape_index": 24,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 15,
"instruction": "Turn left onto Polk Street.",
"verbal_transition_alert_instruction": "Turn left onto Polk Street.",
"verbal_pre_transition_instruction": "Turn left onto Polk Street.",
"verbal_post_transition_instruction": "Continue for 300 feet.",
"street_names": [
"Polk Street"
],
"time": 68.058,
"length": 0.059,
"cost": 73.058,
"begin_shape_index": 24,
"end_shape_index": 27,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 10,
"instruction": "Turn right onto the walkway.",
"verbal_transition_alert_instruction": "Turn right onto the walkway.",
"verbal_pre_transition_instruction": "Turn right onto the walkway.",
"verbal_post_transition_instruction": "Continue for 400 feet.",
"time": 98.0,
"length": 0.084,
"cost": 103.0,
"begin_shape_index": 27,
"end_shape_index": 32,
"rough": true,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 15,
"instruction": "Turn left onto Van Ness Avenue.",
"verbal_transition_alert_instruction": "Turn left onto Van Ness Avenue.",
"verbal_pre_transition_instruction": "Turn left onto Van Ness Avenue.",
"verbal_post_transition_instruction": "Continue for 400 feet.",
"street_names": [
"Van Ness Avenue"
],
"time": 83.294,
"length": 0.073,
"cost": 98.294,
"begin_shape_index": 32,
"end_shape_index": 38,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 10,
"instruction": "Turn right onto the walkway.",
"verbal_transition_alert_instruction": "Turn right onto the walkway.",
"verbal_pre_transition_instruction": "Turn right onto the walkway. Then Turn left onto the walkway.",
"verbal_post_transition_instruction": "Continue for 30 feet.",
"time": 7.058,
"length": 0.006,
"cost": 12.058,
"begin_shape_index": 38,
"end_shape_index": 39,
"rough": true,
"verbal_multi_cue": true,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 15,
"instruction": "Turn left onto the walkway.",
"verbal_transition_alert_instruction": "Turn left onto the walkway.",
"verbal_pre_transition_instruction": "Turn left onto the walkway. Then Turn right onto Bay Street.",
"verbal_post_transition_instruction": "Continue for 50 feet.",
"time": 9.882,
"length": 0.008,
"cost": 9.882,
"begin_shape_index": 39,
"end_shape_index": 40,
"rough": true,
"verbal_multi_cue": true,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 10,
"instruction": "Turn right onto Bay Street.",
"verbal_transition_alert_instruction": "Turn right onto Bay Street.",
"verbal_pre_transition_instruction": "Turn right onto Bay Street.",
"verbal_post_transition_instruction": "Continue for 900 feet.",
"street_names": [
"Bay Street"
],
"time": 194.823,
"length": 0.171,
"cost": 199.823,
"begin_shape_index": 40,
"end_shape_index": 45,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 15,
"instruction": "Turn left onto Gough Street.",
"verbal_transition_alert_instruction": "Turn left onto Gough Street.",
"verbal_pre_transition_instruction": "Turn left onto Gough Street. Then You will arrive at your destination.",
"verbal_post_transition_instruction": "Continue for 20 feet.",
"street_names": [
"Gough Street"
],
"time": 3.302,
"length": 0.002,
"cost": 8.302,
"begin_shape_index": 45,
"end_shape_index": 46,
"verbal_multi_cue": true,
"travel_mode": "pedestrian",
"travel_type": "foot"
},
{
"type": 4,
"instruction": "You have arrived at your destination.",
"verbal_transition_alert_instruction": "You will arrive at your destination.",
"verbal_pre_transition_instruction": "You have arrived at your destination.",
"time": 0.0,
"length": 0.0,
"cost": 0.0,
"begin_shape_index": 46,
"end_shape_index": 46,
"travel_mode": "pedestrian",
"travel_type": "foot"
}
],
"summary": {
"has_time_restrictions": false,
"min_lat": 37.803694,
"min_lon": -122.428418,
"max_lat": 37.807771,
"max_lon": -122.419706,
"time": 818.918,
"length": 0.716,
"cost": 883.918
},
"shape": "uhrbgAt~{nhFrDhk@rBWfAbPvBWXfElAQhAi@dA]d[oDvIaAs@~Dp@n@r@r@^\\jAnQfDdh@lBtY`Eg@VzDXxDxAdPrD~j@zBf]TpD|C_@`\\uD|QaCZtE`Cp\\|A|UdCz^N`ClDJj@dJdDo@vGw@dKmAzWcDRdFpFq@d@dHpH`kAVbEXhEdKj_BpAO"
}
],
"linear_references": [
"C6jyLBrisjr3Af+4//g6BA==",
"C6jyCxrirjr3AAAA//s6Bw==",
"C6jyDBriqyKUAP/j//0iAg==",
"C6jx/xriqTr3AAAA//w6Ag==",
"C6jx/xripjr0AP/2AAE6Hg==",
"C6jx+xripiKUAQAM/8kiHw==",
"C6jyARrijCKPAAAC/+8iBg==",
"C6jyAxrihDrvAP/0AAM6BQ==",
"C6jx/hrihTrzAP/5//o6Bw==",
"C6jx+xrigjr1AP/h//06Bw==",
"C6jx7RrigDr3Af++//k6Bw==",
"C6jxzxrifDr3AP/T//w6Ag==",
"C6jxuxrieTr3AAAA//g6Bw==",
"C6jxvBridTLSAP/1AAAyBw==",
"C6jxtxridDLSAP/2AAEyBg==",
"C6jxsxridDLWAf+d//MyBw==",
"C6jxhRribjLXAP/P//oyAg==",
"C6jxbxriazLXAP/1//8yHw==",
"C6jxaxriajLXAP////kyHw==",
"C6jxaxriZjLTAAAJ/9MyHw==",
"C6jxbxriUTLPAAAG/+IyBw==",
"C6jxcxriQzrvAP/z//86Bw==",
"C6jxbhriQjryAP/P//s6Bw==",
"C6jxVxriPzr3AP/b//w6Bw==",
"C6jxRhriPTr3AP/N//o6Aw==",
"C6jxLxriOjr3AP/4AAA6Aw==",
"C6jxLBriOTLXAP/9//kyBQ==",
"C6jxKxriNSKTAP/u//8iHw==",
"C6jxIxriNCKWAAAE/+siHw==",
"C6jxJRriKiKPAAAE/+0iHw==",
"C6jxJxriISKPAAAI/9kiAw==",
"C6jxKxriDjrvAP/0AAA6AQ==",
"C6jxJhriDjrzAAAB//Q6Bw==",
"C6jxJxriCBpxAv9s/+8aBw==",
"C6jw4xrh/xp3Av9a/+0aBQ==",
"C6jwlhrh9jLXAAAA//0yBQ=="
],
"summary": {
"has_time_restrictions": false,
"min_lat": 37.803694,
"min_lon": -122.428418,
"max_lat": 37.807771,
"max_lon": -122.419706,
"time": 818.918,
"length": 0.716,
"cost": 883.918
},
"status_message": "Found route between points",
"status": 0,
"units": "miles",
"language": "en-US"
}
}
matrixResponse:
type: object
properties:
id:
$ref: '#/components/schemas/requestId'
sources:
type: array
items:
$ref: '#/components/schemas/coordinate'
description: >-
The list of starting locations determined by snapping to the nearest appropriate point on the road network for the costing model.
All locations appear in the same order as the input.
minItems: 1
targets:
type: array
items:
$ref: '#/components/schemas/coordinate'
description: >-
The list of ending locations determined by snapping to the nearest appropriate point on the road network for the costing model.
All locations appear in the same order as the input.
minItems: 1
sources_to_targets:
type: array
items:
type: array
items:
$ref: '#/components/schemas/matrixDistance'
description: >-
The matrix of starting and ending locations, along with the computed distance and travel time.
The array is row-ordered. This means that the time and distance from the first location to all others
forms the first row of the array, followed by the time and distance from the second source location to all
target locations, etc.
minItems: 1
warnings:
type: array
items:
$ref: '#/components/schemas/warning'
units:
$ref: '#/components/schemas/valhallaLongUnits'
required:
- sources
- targets
- sources_to_targets
- units
example:
{
"targets": [
[
{
"lon": -73.990508,
"lat": 40.744014
},
{
"lon": -73.979713,
"lat": 40.739735
},
{
"lon": -73.985015,
"lat": 40.752522
},
{
"lon": -73.983704,
"lat": 40.750117
},
{
"lon": -73.993519,
"lat": 40.750552
}
]
],
"sources_to_targets": [
[
{
"distance": 0.000,
"time": 0,
"to_index": 0,
"from_index": 0
},
{
"distance": 1.115,
"time": 806,
"to_index": 1,
"from_index": 0
},
{
"distance": 1.278,
"time": 909,
"to_index": 2,
"from_index": 0
},
{
"distance": 1.112,
"time": 792,
"to_index": 3,
"from_index": 0
},
{
"distance": 1.220,
"time": 869,
"to_index": 4,
"from_index": 0
}
]
],
"sources": [
[
{
"lon": -73.990508,
"lat": 40.744014
}
]
],
"units": "kilometers"
}
isochroneResponse:
type: object
required:
- features
- type
properties:
id:
type: string
features:
type: array
items:
$ref: '#/components/schemas/isochroneFeature'
type:
type: string
enum:
- FeatureCollection
example:
{
"features": [
{
"properties": {
"fill": "#ff0000",
"fillOpacity": 0.33,
"fill-opacity": 0.33,
"fillColor": "#ff0000",
"color": "#ff0000",
"contour": 15,
"opacity": 0.33,
"metric": "time"
},
"geometry": {
"coordinates": [
[
-73.985021,
40.753501
],
[
-73.983892,
40.751630
],
[
-73.982508,
40.751546
],
[
-73.981969,
40.751014
],
[
-73.977881,
40.739014
],
[
-73.979577,
40.738083
],
[
-73.980361,
40.737014
],
[
-73.988508,
40.734670
],
[
-73.990508,
40.733708
],
[
-73.991514,
40.734008
],
[
-73.994628,
40.733894
],
[
-73.995388,
40.734134
],
[
-73.995662,
40.734860
],
[
-73.996508,
40.735006
],
[
-73.998508,
40.734576
],
[
-74.003292,
40.746014
],
[
-74.004016,
40.749014
],
[
-74.002508,
40.749907
],
[
-73.993508,
40.751786
],
[
-73.987508,
40.753970
],
[
-73.985021,
40.753501
]
],
"type": "LineString"
},
"type": "Feature"
}
],
"type": "FeatureCollection"
}
isochroneFeature:
type: object
properties:
properties:
$ref: '#/components/schemas/isochroneProperties'
geometry:
type: object
# Bit of a cop-out for now since many client generators choke on the complexity of GeoJSON
additionalProperties: true
type:
type: string
enum:
- Feature
isochroneProperties:
type: object
properties:
fillColor:
type: string
opacity:
type: number
format: float
fill:
type: string
fillOpacity:
type: number
format: float
color:
type: string
contour:
type: number
format: float
metric:
type: string
enum:
- time
- distance
heightResponse:
type: object
properties:
id:
$ref: '#/components/schemas/requestId'
shape:
type: array
items:
$ref: '#/components/schemas/coordinate'
encoded_polyline:
type: string
description: The input polyline.
height:
type: array
description: >-
The list of heights for each point, in meters. Present only if `range` is `false`.
Null values indicate missing data.
items:
type: number
format: float
range_height:
type: array
description: >-
The list of ranges and heights for each point in the shape, where each entry is an array of length 2.
Present only if `range` is `true`.
In each pair, the first element represents the range or distance along the input locations. It is the
cumulative distance along the previous coordinates in the shape up to the current coordinate.
This value for the first coordinate in the shape will always be 0.
The second element in the pair represents the height or elevation at the associated coordinate. The height
is null if no height data exists for a given location.
Both values are expressed in meters.
items:
type: array
items:
type: number
format: float
minItems: 2
maxItems: 2
example:
{
"id": "kesklinn",
"shape": [
{
"lat": 59.436884,
"lon": 24.742595
}
],
"height": [
37
]
}
traceAttributesBaseResponse:
type: object
properties:
edges:
type: array
nullable: true
items:
$ref: '#/components/schemas/traceEdge'
description: The list of edges matched along the path.
admins:
type: array
items:
$ref: '#/components/schemas/adminRegion'
description: >-
The set of administrative regions matched along the path. Rather than repeating this information
for every end node, the admins in this list are referenced by index.
matched_points:
type: array
items:
$ref: '#/components/schemas/matchedPoint'
description: >-
List of match results when using the map_snap shape match algorithm. There is a one-to-one correspondence
with the input set of latitude, longitude coordinates and this list of match results.
osm_changeset:
type: integer
shape:
type: string
description: >-
The encoded polyline (https://developers.google.com/maps/documentation/utilities/polylinealgorithm)
of the matched path.
confidence_score:
type: number
format: double
minimum: 0
maximum: 1
traceAttributesResponse:
allOf:
- $ref: '#/components/schemas/traceAttributesBaseResponse'
- type: object
properties:
id:
$ref: '#/components/schemas/requestId'
units:
$ref: '#/components/schemas/valhallaLongUnits'
alternate_paths:
type: array
items:
$ref: '#/components/schemas/traceAttributesBaseResponse'
description: Alternate paths, if any, that were not classified as the best match.
bulkSearchResponse:
type: object
properties:
status:
type: integer
response:
$ref: '#/components/schemas/peliasResponse'
msg:
type: string
description: An error message describing what went wrong (if the status is not 200).
required:
- status
locateObject:
type: object
properties:
id:
$ref: '#/components/schemas/requestId'
input_lat:
type: number
format: double
description: The input (searched) latitude.
input_lon:
type: number
format: double
description: The input (searched) longitude.
nodes:
type: array
nullable: true
items:
$ref: '#/components/schemas/locateNode'
edges:
type: array
nullable: true
items:
$ref: '#/components/schemas/locateEdge'
locateNode:
allOf:
- $ref: '#/components/schemas/coordinate'
- type: object
properties:
traffic_signal:
type: boolean
type:
$ref: '#/components/schemas/nodeType'
node_id:
$ref: '#/components/schemas/nodeId'
access:
$ref: '#/components/schemas/access'
edge_count:
type: integer
administrative:
$ref: '#/components/schemas/administrative'
intersection_type:
type: string
enum:
- regular
- false
- dead-end
- fork
density:
type: integer
local_edge_count:
type: integer
mode_change:
type: boolean
nodeId:
type: object
properties:
id:
type: integer
format: int64
value:
type: integer
format: int64
tile_id:
type: integer
format: int64
level:
type: integer
access:
type: object
properties:
golf_cart:
type: boolean
wheelchair:
type: boolean
taxi:
type: boolean
HOV:
type: boolean
truck:
type: boolean
emergency:
type: boolean
pedestrian:
type: boolean
car:
type: boolean
bus:
type: boolean
bicycle:
type: boolean
motorcycle:
type: boolean
moped:
type: boolean
administrative:
type: object
properties:
iso_3166-1:
type: string
description: The ISO 3166-1 alpha-2 country code of the administrative region.
country:
type: string
description: The full country name.
iso_3166-2:
type: string
description: >-
The ISO 3166-2 code identifying the principal subdivision (ex: provinces or states) within
a country.
state:
type: string
description: The full state or province name.
locateEdge:
type: object
properties:
edge_id:
$ref: '#/components/schemas/nodeId'
way_id:
type: integer
description: The OSM way ID associated with this edge (absent in verbose response; see the edge info).
correlated_lat:
type: number
format: double
correlated_lon:
type: number
format: double
percent_along:
type: number
format: double
side_of_street:
type: string
enum:
- left
- right
- neither
linear_reference:
type: string
description: >-
A base64-encoded [OpenLR location reference](https://www.openlr-association.com/fileadmin/user_upload/openlr-whitepaper_v1.5.pdf),
for a graph edge of the road network matched by the query.
outbound_reach:
type: integer
heading:
type: number
format: float
inbound_reach:
type: integer
distance:
type: number
format: float
predicted_speeds:
type: array
items:
type: integer
description: >-
Predicted speed information based on historical data. If available, this will include 2016 entries.
Each entry represents 5 minutes, where the first entry represents midnight on Monday, the second entry
represents 00:05 on Monday, etc.
edge_info:
$ref: '#/components/schemas/locateEdgeInfo'
edge:
$ref: '#/components/schemas/locateDetailedEdge'
warnings:
type: array
items:
type: string
required:
- correlated_lat
- correlated_lon
- side_of_street
- percent_along
locateEdgeInfo:
type: object
properties:
mean_elevation:
type: number
format: float
description: The mean elevation, in meters, relative to sea level.
shape:
type: string
description: >-
An encoded polyline (https://developers.google.com/maps/documentation/utilities/polylinealgorithm).
Note that the polyline is always encoded with 6 digits of precision, whereas most implementations default
to 5.
names:
type: array
items:
type: string
description: A list of names that the edge goes by.
bike_network:
$ref: '#/components/schemas/bikeNetwork'
way_id:
type: integer
description: The OSM way ID associated with this edge.
required:
- way_id
- shape
locateDetailedEdge:
type: object
properties:
sidewalk_left:
type: boolean
description: Is there a sidewalk to the left of the edge?
sidewalk_right:
type: boolean
description: Is there a sidewalk to the right of the edge?
lane_count:
type: integer
stop_sign:
type: boolean
description: Is there a stop sign at end of the directed edge?
sac_scale:
type: string
enum:
- none
- hiking
- mountain hiking
- demanding mountain hiking
- alpine hiking
- demanding alpine hiking
- difficult alpine hiking
yield_sign:
type: boolean
description: Is there a yield sign at end of the directed edge?
not_thru:
type: boolean
description: Does the edge lead to a "no-through" region?
forward:
type: boolean
description: Is the edge info forward? If false, then reverse is implied.
end_node:
$ref: '#/components/schemas/nodeId'
truck_route:
type: boolean
description: Is the edge part of a truck route/network?
speeds:
$ref: '#/components/schemas/speeds'
bike_network:
type: boolean
description: Is the edge part of a bicycle network?
round_about:
type: boolean
description: Is the edge part of a roundabout?
traffic_signal:
type: boolean
description: Is there a traffic signal at the end of the directed edge?
access_restriction:
type: boolean
description: Is there a general restriction or access condition?
destination_only:
type: boolean
description: Is the edge destination only? If so, it will not be routed through.
geo_attributes:
$ref: '#/components/schemas/geoAttributes'
start_restriction:
$ref: '#/components/schemas/restrictions'
cycle_lane:
type: string
description: >-
Indication of the type of cycle lane (if any) present along an edge.
enum:
- none
- shared
- dedicated
- separated
end_restriction:
$ref: '#/components/schemas/restrictions'
seasonal:
type: boolean
description: Is access seasonal (ex. no access in winter)?
country_crossing:
type: boolean
description: Does the edge cross into a new country?
part_of_complex_restriction:
type: boolean
description: Is the edge part of a complex restriction?
has_sign:
type: boolean
description: Do exit signs exist for the edge?
access:
$ref: '#/components/schemas/restrictions'
bridge:
type: boolean
description: Is the edge part of a bridge?
classification:
$ref: '#/components/schemas/highwayClassification'
toll:
type: boolean
description: Is the edge a toll road?
tunnel:
type: boolean
description: Is the edge a tunnel?
bikeNetwork:
type: object
properties:
mountain:
type: boolean
local:
type: boolean
regional:
type: boolean
national:
type: boolean
speeds:
type: object
properties:
predicted:
type: boolean
description: Does this edge have predicted (historical) speed records?
constrained_flow:
type: integer
description: Speed when there is no traffic, in kph.
free_flow:
type: integer
description: Speed when there is heavy traffic, in kph.
type:
type: string
enum:
- classified
- tagged
description: >-
The type of speed which is used when setting default speeds. When `tagged`, the explicit `max_speed`
tags from OpenStreetMap are being used. When `classified`, the values are being inferred from the
highway classification.
default:
type: integer
description: >-
The default speed used for calculations. NOTE: Values greater than 250 are used for special cases
and should not be treated as literal.
geoAttributes:
type: object
properties:
curvature:
type: integer
description: Curvature factor.
max_down_slope:
type: number
format: float
description: >-
The maximum downward slope. Uses 1 degree precision for slopes to -16 degrees, and 4 degree
precision afterwards (up to a max of -76 degrees).
max_up_slope:
type: number
format: float
description: >-
The maximum upward slope. Uses 1 degree precision for slopes to 16 degrees, and 4 degree
precision afterwards (up to a max of 76 degrees).
weighted_grade:
type: number
format: float
description: The weighted estimate of the grade.
length:
type: integer
description: The length of the edge, in meters.
restrictions:
type: object
properties:
golf_cart:
type: boolean
truck:
type: boolean
pedestrian:
type: boolean
wheelchair:
type: boolean
taxi:
type: boolean
HOV:
type: boolean
emergency:
type: boolean
motorcycle:
type: boolean
car:
type: boolean
moped:
type: boolean
bus:
type: boolean
bicycle:
type: boolean
highwayClassification:
type: object
properties:
internal:
type: boolean
description: Is the edge internal to an intersection?
link:
type: boolean
description: Is the edge a ramp or turn channel?
surface:
type: string
description: >-
A representation of the smoothness of the highway. This is used for costing and access checks based on
the vehicle type.
enum:
- paved_smooth
- paved
- paved_rough
- compacted
- dirt
- gravel
- path
- impassable
use:
type: string
enum:
- road
- ramp
- turn_channel
- track
- driveway
- alley
- parking_aisle
- emergency_access
- drive_through
- culdesac
- living_street
- service_road
- cycleway
- mountain_bike
- sidewalk
- footway
- elevator
- steps
- escalator
- path
- pedestrian
- bridleway
- pedestrian_crossing
- rest_area
- service_area
- other
- rail
- ferry
- rail-ferry
- bus
- egress_connection
- platform_connnection
- transit_connection
- construction
classification:
type: string
description: >-
The classification/importance of the road/path. Used for a variety of purposes including
fallback speed estimation and access for certain vehicle types.
enum:
- motorway
- trunk
- primary
- secondary
- tertiary
- unclassified
- residential
- service_other
geocodingObject:
type: object
properties:
attribution:
type: string
format: uri
description: >-
A URL containing attribution information. If you are not using Stadia Maps and our
standard attribution already for your basemaps, you must include this attribution link
somewhere in your website/app.
query:
type: object
additionalProperties: true
description: >-
Technical details of the query. This is most useful for debugging during development.
See the full example for the list of properties; these should be self-explanatory, so we
don't enumerate them in the spec.
warnings:
type: array
items:
type: string
description: >-
An array of non-critical warnings. This is normally for informational/debugging purposes and
not a serious problem.
errors:
type: array
items:
type: string
description: >-
An array of more serious errors (for example, omitting a required parameter). Don’t ignore these.
geoJSONGeometryBase:
type: object
required:
- type
properties:
type:
type: string
enum:
- Point
- MultiPoint
- LineString
- MultiLineString
- Polygon
- MultiPolygon
geoJSONPoint:
allOf:
- $ref: '#/components/schemas/geoJSONGeometryBase'
- type: object
required:
- coordinates
properties:
coordinates:
type: array
minItems: 2
maxItems: 3
items:
type: number
format: double
geoJSONLineString:
allOf:
- $ref: '#/components/schemas/geoJSONGeometryBase'
- type: object
required:
- coordinates
properties:
coordinates:
type: array
items:
type: array
items:
type: number
format: double
minItems: 2
maxItems: 3
geoJSONPolygon:
allOf:
- $ref: '#/components/schemas/geoJSONGeometryBase'
- type: object
required:
- coordinates
properties:
coordinates:
type: array
items:
type: array
items:
type: array
items:
type: number
format: double
minItems: 2
maxItems: 3
geoJSONGeometry:
oneOf:
- $ref: '#/components/schemas/geoJSONPoint'
- $ref: '#/components/schemas/geoJSONLineString'
- $ref: '#/components/schemas/geoJSONPolygon'
discriminator:
propertyName: type
mapping:
Point: '#/components/schemas/geoJSONPoint'
LineString: '#/components/schemas/geoJSONLineString'
Polygon: '#/components/schemas/geoJSONPolygon'
peliasGeoJSONProperties:
type: object
additionalProperties: true
properties:
gid:
type: string
description: >-
A scoped GID for this result. This can be passed to the place
endpoint. Note that these are not always stable. For Geonames and Who's on First,
these are usually stable, but for other sources like OSM, no stability is guaranteed.
source_id:
type: string
description: >-
An ID referencing the original data source (specified via source) for the result. These IDs are specific
to the source that they originated from. For example, in the case of OSM, these typically look like
way/123 or point/123.
label:
type: string
description: >-
A full, human-readable label. However, you may not necessarily want to use this; be sure to read the docs
for name, locality, and region before making a decision. This field is mostly localized. The order of
components is generally locally correct (ex: for an address in South Korea, the house number appears after
the street name). However, components will use a request language equivalent if one exists (ex: Seoul
instead of 서울 if lang=en).
layer:
$ref: '#/components/schemas/peliasLayer'
name:
type: string
description: >-
The name of the place, the street address including house number, or label of similar relevance.
If your app is localized to a specific region, you may get better display results by combining name,
locality OR region (or neither?), and postal code together in the local format. Experiment with what
works best for your use case.
accuracy:
type: string
enum:
- point
- centroid
description: >-
The accuracy of the geographic coordinates in the result. This value is a property of the result
itself and won't change based on the query.
A point result means that the record can reasonably be represented by a single geographic point.
Addresses, venues, or interpolated addresses usually have point accuracy.
Larger areas, such as a city or country, cannot be represented by a single point, so a centroid
is given instead.
addendum:
type: object
additionalProperties: true
description: >-
Optional additional information from the underlying data source (ex: OSM). This includes select
fields. The most useful fields are mapped in the definition here, but others may be available.
properties:
osm:
type: object
additionalProperties: true
properties:
website:
type: string
format: uri
wikipedia:
type: string
wikidata:
type: string
phone:
type: string
continent:
type: string
continent_gid:
type: string
country:
type: string
country_gid:
type: string
neighbourhood:
type: string
neighbourhood_gid:
type: string
borough:
type: string
borough_gid:
type: string
postalcode:
type: string
street:
type: string
housenumber:
type: string
locality:
type: string
description: >-
The city, village, town, etc. that the place / address is part of. Note that values may not always
match postal or local conventions perfectly.
locality_gid:
type: string
county:
type: string
description: >-
Administrative divisions between localities and regions. Useful for disambiguating nearby
results with similar names.
region:
type: string
description: >-
Typically the first administrative division within a country.
For example, a US state or a Canadian province.
region_a:
type: string
description: The abbreviation for the region.
peliasGeoJSONFeature:
type: object
required:
- type
- geometry
properties:
type:
type: string
enum:
- Feature
geometry:
$ref: '#/components/schemas/geoJSONPoint'
properties:
$ref: '#/components/schemas/peliasGeoJSONProperties'
bbox:
type: array
minItems: 4
maxItems: 4
items:
type: number
format: double
description: >-
An array of 4 floating point numbers representing the (W, S, E, N) extremes of the features found.
peliasResponse:
type: object
properties:
geocoding:
allOf:
- $ref: '#/components/schemas/geocodingObject'
bbox:
type: array
minItems: 4
maxItems: 4
items:
type: number
format: double
description: >-
An array of 4 floating point numbers representing the (W, S, E, N) extremes of the features found.
features:
type: array
items:
$ref: '#/components/schemas/peliasGeoJSONFeature'
required:
- geocoding
- features
example:
{
"geocoding": {
"version": "0.2",
"attribution": "https://stadiamaps.com/attribution",
"query": {
"text": "1600 Pennsylvania Ave NW",
"size": 10,
"private": false,
"lang": {
"name": "English",
"iso6391": "en",
"iso6393": "eng",
"via": "default",
"defaulted": true
},
"querySize": 20,
"parser": "libpostal",
"parsed_text": {
"housenumber": "1600",
"street": "pennsylvania ave nw"
}
},
"engine": {
"name": "Pelias",
"author": "Mapzen",
"version": "1.0"
},
"timestamp": 1679043782383
},
"type": "FeatureCollection",
"features": [
{
"type": "Feature",
"geometry": {
"type": "Point",
"coordinates": [
-77.036547,
38.897675
]
},
"properties": {
"id": "us/dc/statewide:aa53d4bd0fe295be",
"gid": "openaddresses:address:us/dc/statewide:aa53d4bd0fe295be",
"layer": "address",
"source": "openaddresses",
"source_id": "us/dc/statewide:aa53d4bd0fe295be",
"country_code": "US",
"name": "1600 Pennsylvania Avenue NW",
"housenumber": "1600",
"street": "Pennsylvania Avenue NW",
"postalcode": "20500",
"confidence": 1,
"match_type": "exact",
"accuracy": "point",
"country": "United States",
"country_gid": "whosonfirst:country:85633793",
"country_a": "USA",
"region": "District of Columbia",
"region_gid": "whosonfirst:region:85688741",
"region_a": "DC",
"county": "District of Columbia",
"county_gid": "whosonfirst:county:1377370667",
"county_a": "DI",
"locality": "Washington",
"locality_gid": "whosonfirst:locality:85931779",
"neighbourhood": "White House Grounds",
"neighbourhood_gid": "whosonfirst:neighbourhood:1108724059",
"continent": "North America",
"continent_gid": "whosonfirst:continent:102191575",
"label": "1600 Pennsylvania Avenue NW, Washington, DC, USA"
}
}
],
"bbox": [
-77.036547,
38.897675,
-77.036547,
38.897675
]
}
peliasLayer:
type: string
enum:
- venue
- address
- street
- country
- macroregion
- region
- macrocounty
- county
- locality
- localadmin
- borough
- neighbourhood
- postalcode
- coarse
- dependency
- macrohood
- marinearea
- disputed
- empire
- continent
- ocean
description: |
Our database is organized into several layers (in the GIS sense of the term) as follows:
- `venue`: Points of interest, businesses, and things with walls
- `address`: Places with a street address
- `street`: Streets, roads, highways
- `county`: Places that issue passports, nations, nation-states
- `macroregion`: A related group of regions (mostly in Europe)
- `region`: The first administrative division within a country (usually states and provinces)
- `macrocounty`: A related group of counties (mostly in Europe)
- `county`: Official governmental areas; usually bigger than a locality, but almost always smaller than a region
- `locality`: Towns, hamlets, cities, etc.
- `localadmin`: Local administrative boundaries
- `borough`: Local administrative boundaries within cities (not widely used, but present in places such as NYC and Mexico City)
- `neighbourhood`: Social communities and neighborhoods (note the British spelling in the API!)
- `postalcode`: Postal codes used by mail services (note: not used for reverse geocoding)
- `coarse`: An alias for simultaneously using all administrative layers (everything except `venue` and `address`)
- `marinearea`: Places with fishes and boats.
- `ocean`: A really big marine area.
peliasSource:
type: string
enum:
- openstreetmap
- openaddresses
- whosonfirst
- geonames
description: >-
Our database contains info from multiple sources. These identifiers can be used to either
limit search results or to determine the relevance of a result.
warning:
type: object
properties:
text:
type: string
code:
type: integer
searchText:
type: string
description: The place name (address, venue name, etc.) to search for.
example: 1600 Pennsylvania Ave NW
searchFocusLat:
type: number
description: The latitude of the point to focus the search on. This will bias
results toward the focus point. Requires `focus.point.lon`.
format: double
minimum: -90
maximum: 90
searchFocusLon:
type: number
description: The longitude of the point to focus the search on. This will bias
results toward the focus point. Requires `focus.point.lat`.
format: double
minimum: -180
maximum: 180
searchBoundaryRectMinLat:
type: number
description: Defines the min latitude component of a bounding box to limit the
search to. Requires all other `boundary.rect` parameters to be specified.
format: double
minimum: -90
maximum: 90
searchBoundaryRectMaxLat:
type: number
description: Defines the max latitude component of a bounding box to limit the
search to. Requires all other `boundary.rect` parameters to be specified.
format: double
minimum: -90
maximum: 90
searchBoundaryRectMinLon:
type: number
description: Defines the min longitude component of a bounding box to limit
the search to. Requires all other `boundary.rect` parameters to be specified.
format: double
minimum: -180
maximum: 180
searchBoundaryRectMaxLon:
type: number
description: Defines the max longitude component of a bounding box to limit
the search to. Requires all other `boundary.rect` parameters to be specified.
format: double
minimum: -180
maximum: 180
searchBoundaryCircleLat:
type: number
description: The latitude of the center of a circle to limit the search to.
Requires `boundary.circle.lon`.
format: double
minimum: -90
maximum: 90
searchBoundaryCircleLon:
type: number
description: The longitude of the center of a circle to limit the search to.
Requires `boundary.circle.lat`.
format: double
minimum: -180
maximum: 180
searchBoundaryCircleRadius:
type: number
description: The radius of the circle (in kilometers) to limit the search to.
Defaults to 50km if unspecified.
format: double
searchBoundaryCountry:
type: array
items:
type: string
description: 'A list of countries to limit the search to. These may be either
full names (ex: Canada), or an ISO 3116-1 alpha-2 or alpha-3 code. Prefer
ISO codes when possible.'
searchBoundaryGID:
type: string
description: The Pelias GID of an area to limit the search to.
searchLayers:
type: array
description: A list of layers to limit the search to.
items:
$ref: '#/components/schemas/peliasLayer'
searchSources:
type: array
description: A list of sources to limit the search to.
items:
$ref: '#/components/schemas/peliasSource'
searchAddress:
type: string
description: A street name, optionally with a house number.
example: 11 Wall Street
searchNeighborhood:
type: string
description: Varies by area, but has a locally specific meaning (NOT always
an official administrative unit).
example: Financial District
searchBorough:
type: string
description: A unit within a city (not widely used, but present in places like
NYC and Mexico City).
example: Manhattan
searchLocality:
type: string
description: The city, village, town, etc. that the place/address is part of.
example: New York
searchCounty:
type: string
description: Administrative divisions between localities and regions. Not commonly
used as input to structured geocoding.
example: New York County
searchRegion:
type: string
description: Typically the first administrative division within a country. For
example, a US state or a Canadian province.
example: New York
postalCode:
type: string
description: A mail sorting code.
example: 10005
searchCountry:
type: string
description: 'A full name (ex: Canada), or a 2 or 3 character ISO code. Prefer
ISO codes when possible.'
example: USA
reverseLat:
type: number
description: The latitude of the point at which to perform the search.
example: 48.848268
format: double
minimum: -90
maximum: 90
reverseLon:
type: number
description: The longitude of the point at which to perform the search.
example: 2.294471
format: double
minimum: -180
maximum: 180
placeIDs:
type: array
description: A list of Pelias GIDs to search for.
items:
type: string
limit:
type: integer
description: The maximum number of results to return.
peliasLang:
type: string
description: A BCP47 language tag which specifies a preference for localization
of results. By default, results are in the default locale of the source data,
but specifying a language will attempt to localize the results. Note that
while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only
the `language` portion, an ISO 639 code, will be considered. So `en-US` and
`en-GB` will both be treated as English.
osrmBaseApiResponse:
type: object
required:
- code
properties:
code:
type: string
enum:
- Ok
- InvalidUrl
- InvalidService
- InvalidVersion
- InvalidOptions
- InvalidQuery
- InvalidValue
- NoSegment
- TooBig
- NoRoute
- NoTable
- NotImplemented
- NoTrips
message:
type: string
data_version:
type: string
osrmRouteResponse:
allOf:
- $ref: '#/components/schemas/osrmBaseApiResponse'
- type: object
properties:
waypoints:
type: array
items:
$ref: '#/components/schemas/osrmWaypoint'
routes:
type: array
items:
$ref: '#/components/schemas/osrmRoute'
osrmRoute:
type: object
required:
- distance
- duration
- geometry
- legs
properties:
distance:
type: number
format: double
description: The distance traveled by the route, in meters.
duration:
type: number
format: double
description: The estimated travel time, in number of seconds.
geometry:
type: string
description: >-
An encoded polyline (https://developers.google.com/maps/documentation/utilities/polylinealgorithm).
weight:
type: number
format: double
description: >-
The total cost of the route computed by the routing engine.
weight_name:
type: string
description: The costing model used for the route.
legs:
type: array
items:
$ref: '#/components/schemas/osrmRouteLeg'
osrmRouteLeg:
type: object
required:
- distance
- duration
- steps
properties:
distance:
type: number
format: double
description: The distance traveled by the route, in meters.
duration:
type: number
format: double
description: The estimated travel time, in number of seconds.
weight:
type: number
format: double
description: >-
The total cost of the leg computed by the routing engine.
summary:
type: string
steps:
type: array
items:
$ref: '#/components/schemas/osrmRouteStep'
annotation:
$ref: '#/components/schemas/osrmAnnotation'
via_waypoints:
type: array
nullable: true
description: >-
Indicates which waypoints are passed through rather than creating a new leg.
items:
$ref: '#/components/schemas/osrmViaWaypoint'
admins:
type: array
description: Administrative regions visited along the leg.
items:
$ref: '#/components/schemas/osrmAdmin'
osrmRouteStep:
type: object
description: >-
A maneuver such as a turn or merge, followed by travel along a single road or path.
required:
- distance
- duration
- geometry
- mode
- maneuver
properties:
distance:
type: number
format: double
description: The distance traveled by the route, in meters.
duration:
type: number
format: double
description: The estimated travel time, in number of seconds.
geometry:
type: string
description: >-
An encoded polyline (https://developers.google.com/maps/documentation/utilities/polylinealgorithm) with
6 digits of decimal precision.
weight:
type: number
format: double
name:
type: string
description: "The name of the segment (ex: road) being traversed"
ref:
type: string
description: A reference number of code for the segment being traversed.
pronunciation:
type: string
description: >-
Pronunciation of the name (if available).
The format of this varies by implementation/vendor.
destinations:
type: string
exits:
type: string
mode:
type: string
description: The mode of travel.
maneuver:
$ref: '#/components/schemas/osrmStepManeuver'
intersections:
type: array
items:
$ref: '#/components/schemas/osrmIntersection'
rotary_name:
type: string
description: The name of the traffic circle.
rotary_pronunciation:
type: string
description: >-
Pronunciation of the rotary name (if available).
The format of this varies by implementation/vendor.
driving_side:
type: string
enum:
- left
- right
description: The side of the road on which driving is legal for this step.
voiceInstructions:
type: array
items:
$ref: '#/components/schemas/osrmVoiceInstruction'
description: >-
A list of announcements which should be spoken at various points along the maneuver.
bannerInstructions:
type: array
items:
$ref: '#/components/schemas/osrmBannerInstruction'
description: >-
A list of announcements which should be displayed prominently on screen at various points along the maneuver.
speedLimitSign:
type: string
enum:
- mutcd
- vienna
description: >-
The style of speed limit signs used along the step.
speedLimitUnit:
type: string
description: >-
The unit of measure that is used locally along the step.
This may be different from the unit used in maxspeed annotations,
and is provided so that apps can localize their display.
osrmAnnotation:
type: object
properties:
distance:
type: array
items:
type: number
format: double
description: The distance, in meters, between each pair of coordinates.
duration:
type: array
items:
type: number
format: double
description: The duration between each pair of coordinates, in seconds.
weight:
type: array
items:
type: integer
speed:
type: array
items:
type: number
format: double
description: >-
The estimated speed of travel between each pair of coordinates in meters/sec.
maxspeed:
type: array
items:
$ref: '#/components/schemas/osrmSpeedLimit'
osrmStepManeuver:
type: object
required:
- location
- bearing_before
- bearing_after
- type
properties:
location:
$ref: '#/components/schemas/osrmCoordinate'
instruction:
type: string
description: >-
A human-readable instruction for the maneuver.
bearing_before:
type: integer
description: >-
The clockwise angle from true north to the direction of travel immediately before the maneuver.
bearing_after:
type: integer
description: >-
The clockwise angle from true north to the direction of travel immediately after the maneuver.
type:
type: string
enum:
- turn
- new name
- depart
- arrive
- merge
- ramp
- on ramp
- off ramp
- fork
- end of road
- use lane
- continue
- roundabout
- rotary
- roundabout turn
- notification
modifier:
$ref: '#/components/schemas/osrmGuidanceModifier'
exit:
type: integer
description: The exit number to take (for roundabouts, rotaries, and number of intersections).
osrmIntersection:
type: object
description: >-
Detailed information about intersections that the route traverses.
For every step, the first intersection is at the location of the maneuver.
Additional intersections will be provided for every road or path traversed
until the next step.
required:
- location
- bearings
- entry
properties:
location:
$ref: '#/components/schemas/osrmCoordinate'
bearings:
type: array
items:
type: integer
description: >-
A list of bearing values that are available for travel through the intersection.
classes:
type: array
items:
type: string
enum:
- toll
- ferry
- restricted
- motorway
- tunnel
description: The classes of roads exiting the intersection.
entry:
type: array
items:
type: boolean
description: >-
A list of entry flags, which map 1:1 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.
in:
type: integer
description: >-
An 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: integer
description: >-
An index into bearings/entry array.
Used to calculate 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.
This is not supplied for arrive maneuvers.
lanes:
type: array
items:
$ref: '#/components/schemas/osrmLane'
description: >-
Available turn lanes at the intersection.
May be omitted if no lane information is available for the intersection.
admin_index:
type: integer
description: >-
The index into the admin boundaries list on the route leg.
duration:
type: number
format: double
description: >-
The estimated duration, in seconds, to traverse the intersection.
turn_duration:
type: number
format: double
description: >-
The estimated duration, in seconds, to complete the turn.
turn_weight:
type: number
format: double
geometry_index:
type: integer
description: >-
The index of the intersection in the leg geometry.
weight:
type: number
format: double
osrmVoiceInstruction:
type: object
required:
- distanceAlongGeometry
- announcement
properties:
distanceAlongGeometry:
type: number
format: double
description: How far (in meters) from the upcoming maneuver the instruction should be announced.
announcement:
type: string
description: The plain-text announcement.
ssmlAnnouncement:
type: string
description: >-
The announcement in Speech Synthesis Markup Language (SSML).
Supported TTS engines include Amazon Polly and Apple's AVSpeechSynthesizer.
osrmBannerInstruction:
type: object
required:
- distanceAlongGeometry
- primary
properties:
distanceAlongGeometry:
type: number
format: double
description: How far (in meters) from the upcoming maneuver the instruction should start being displayed.
primary:
$ref: '#/components/schemas/osrmBannerContent'
secondary:
$ref: '#/components/schemas/osrmBannerContent'
osrmBannerContent:
type: object
required:
- text
properties:
text:
type: string
type:
type: string
enum:
- turn
- new name
- depart
- arrive
- merge
- on ramp
- off ramp
- fork
- end of road
- continue
- roundabout
- rotary
- roundabout turn
- notification
- exit roundabout
- exit rotary
modifier:
$ref: '#/components/schemas/osrmGuidanceModifier'
components:
type: array
items:
$ref: '#/components/schemas/osrmBannerComponent'
description: >-
A list of objects with additional context that allow for visual layout improvements
beyond what's possible with plain text.
osrmLane:
type: object
properties:
indications:
type: array
items:
type: string
enum:
- none
- uturn
- sharp right
- right
- slight right
- straight
- slight left
- left
- sharp left
description: >-
A list of 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).
valid:
type: boolean
description: True if the lane is a valid choice for the current maneuver.
required:
- indications
- valid
osrmWaypoint:
type: object
properties:
name:
type: string
location:
$ref: '#/components/schemas/osrmCoordinate'
distance:
type: number
format: double
description: The distance of the snapped point from the original location.
hint:
type: string
required:
- location
- distance
osrmViaWaypoint:
type: object
properties:
distance_from_start:
type: number
format: double
description: The distance from the start of the leg, in meters.
geometry_index:
type: integer
description: The index of the waypoint's location in the route geometry.
waypoint_index:
type: integer
description: The index of the associated waypoint.
required:
- distance_from_start
- geometry_index
- waypoint_index
osrmCoordinate:
type: array
items:
type: number
format: double
minItems: 2
maxItems: 2
description: A (longitude, latitude) coordinate pair.
osrmAdmin:
type: object
properties:
iso_3166_1:
type: string
description: The ISO 3166-1 two-character code for the admin region.
iso_3166_1_alpha3:
type: string
description: The ISO 3166-1 three-character code for the admin region.
osrmSpeedLimit:
type: object
properties:
speed:
type: integer
unit:
type: string
enum:
- km/h
- mph
description: >-
The unit of measure for the speed.
Always included if speed is present.
unknown:
type: boolean
description: True if the speed limit is not known.
none:
type: boolean
description: "True if there is no explicit speed limit (ex: some Autobahn sections)"
description: >-
The speed limit between the pair of coordinates.
osrmBannerComponent:
type: object
properties:
text:
type: string
type:
type: string
enum:
- text
- icon
- delimiter
- exit-number
- exit
- lane
osrmGuidanceModifier:
type: string
nullable: true
enum:
- uturn
- sharp right
- right
- slight right
- straight
- slight left
- left
- sharp left
description: >-
An optional value indicating the directional change of the maneuver
(further clarifying type).
elevation_interval:
type: number
format: float
description: >-
If greater than zero, attempts to include elevation along the route at regular intervals.
The "native" internal resolution is 30m, so we recommend you use this when possible.
This number is interpreted as either meters or feet depending on the unit parameter.
Elevation for route sections containing a bridge or tunnel is interpolated linearly.
This doesn't always match the true elevation of the bridge/tunnel,
but it prevents sharp artifacts from the surrounding terrain.
This functionality is unique to the routing endpoints and is not available via the elevation API.
NOTE: This has no effect on the OSRM response format.
default: 0.0
parameters:
searchText:
name: text
in: query
schema:
$ref: '#/components/schemas/searchText'
description: The place name (address, venue name, etc.) to search for.
required: true
searchFocusLat:
name: focus.point.lat
in: query
schema:
$ref: '#/components/schemas/searchFocusLat'
description: The latitude of the point to focus the search on. This will bias
results toward the focus point. Requires `focus.point.lon`.
required: false
searchFocusLon:
name: focus.point.lon
in: query
schema:
$ref: '#/components/schemas/searchFocusLon'
description: The longitude of the point to focus the search on. This will bias
results toward the focus point. Requires `focus.point.lat`.
required: false
searchBoundaryRectMinLat:
name: boundary.rect.min_lat
in: query
schema:
$ref: '#/components/schemas/searchBoundaryRectMinLat'
description: Defines the min latitude component of a bounding box to limit the
search to. Requires all other `boundary.rect` parameters to be specified.
required: false
searchBoundaryRectMaxLat:
name: boundary.rect.max_lat
in: query
schema:
$ref: '#/components/schemas/searchBoundaryRectMaxLat'
description: Defines the max latitude component of a bounding box to limit the
search to. Requires all other `boundary.rect` parameters to be specified.
required: false
searchBoundaryRectMinLon:
name: boundary.rect.min_lon
in: query
schema:
$ref: '#/components/schemas/searchBoundaryRectMinLon'
description: Defines the min longitude component of a bounding box to limit
the search to. Requires all other `boundary.rect` parameters to be specified.
required: false
searchBoundaryRectMaxLon:
name: boundary.rect.max_lon
in: query
schema:
$ref: '#/components/schemas/searchBoundaryRectMaxLon'
description: Defines the max longitude component of a bounding box to limit
the search to. Requires all other `boundary.rect` parameters to be specified.
required: false
searchBoundaryCircleLat:
name: boundary.circle.lat
in: query
schema:
$ref: '#/components/schemas/searchBoundaryCircleLat'
description: The latitude of the center of a circle to limit the search to.
Requires `boundary.circle.lon`.
searchBoundaryCircleLon:
name: boundary.circle.lon
in: query
schema:
$ref: '#/components/schemas/searchBoundaryCircleLon'
description: The longitude of the center of a circle to limit the search to.
Requires `boundary.circle.lat`.
searchBoundaryCircleRadius:
name: boundary.circle.radius
in: query
schema:
$ref: '#/components/schemas/searchBoundaryCircleRadius'
description: The radius of the circle (in kilometers) to limit the search to.
Defaults to 50km if unspecified.
searchBoundaryCountry:
name: boundary.country
in: query
schema:
$ref: '#/components/schemas/searchBoundaryCountry'
description: 'A list of countries to limit the search to. These may be either
full names (ex: Canada), or an ISO 3116-1 alpha-2 or alpha-3 code. Prefer
ISO codes when possible.'
style: form
explode: false
searchBoundaryGID:
name: boundary.gid
in: query
schema:
$ref: '#/components/schemas/searchBoundaryGID'
description: The Pelias GID of an area to limit the search to.
searchLayers:
name: layers
in: query
schema:
$ref: '#/components/schemas/searchLayers'
description: A list of layers to limit the search to.
style: form
explode: false
searchSources:
name: sources
in: query
schema:
$ref: '#/components/schemas/searchSources'
description: A list of sources to limit the search to.
style: form
explode: false
searchAddress:
name: address
in: query
schema:
$ref: '#/components/schemas/searchAddress'
description: A street name, optionally with a house number.
required: false
searchNeighborhood:
name: neighbourhood
in: query
schema:
$ref: '#/components/schemas/searchNeighborhood'
description: Varies by area, but has a locally specific meaning (NOT always
an official administrative unit).
required: false
searchBorough:
name: borough
in: query
schema:
$ref: '#/components/schemas/searchBorough'
description: A unit within a city (not widely used, but present in places like
NYC and Mexico City).
required: false
searchLocality:
name: locality
in: query
schema:
$ref: '#/components/schemas/searchLocality'
description: The city, village, town, etc. that the place/address is part of.
required: false
searchCounty:
name: county
in: query
schema:
$ref: '#/components/schemas/searchCounty'
description: Administrative divisions between localities and regions. Not commonly
used as input to structured geocoding.
required: false
searchRegion:
name: region
in: query
schema:
$ref: '#/components/schemas/searchRegion'
description: Typically the first administrative division within a country. For
example, a US state or a Canadian province.
required: false
searchPostalCode:
name: postalcode
in: query
schema:
$ref: '#/components/schemas/postalCode'
description: A mail sorting code.
required: false
searchCountry:
name: country
in: query
schema:
$ref: '#/components/schemas/searchCountry'
description: 'A full name (ex: Canada), or a 2 or 3 character ISO code. Prefer
ISO codes when possible.'
required: false
reverseLat:
name: point.lat
in: query
schema:
$ref: '#/components/schemas/reverseLat'
description: The latitude of the point at which to perform the search.
required: true
reverseLon:
name: point.lon
in: query
schema:
$ref: '#/components/schemas/reverseLon'
description: The longitude of the point at which to perform the search.
required: true
placeIDs:
name: ids
in: query
schema:
$ref: '#/components/schemas/placeIDs'
description: A list of Pelias GIDs to search for.
required: true
style: form
explode: false
size:
name: size
in: query
schema:
$ref: '#/components/schemas/limit'
description: The maximum number of results to return.
peliasLang:
name: lang
in: query
schema:
$ref: '#/components/schemas/peliasLang'
description: A BCP47 language tag which specifies a preference for localization
of results. By default, results are in the default locale of the source data,
but specifying a language will attempt to localize the results. Note that
while a `langtag` (in RFC 5646 terms) can contain script, region, etc., only
the `language` portion, an ISO 639 code, will be considered. So `en-US` and
`en-GB` will both be treated as English.
Confidently create beautiful maps for all your users with our tools. Choose your style from our library or build your own. With a rich palette of choices to fit any context and support for dozens of languages and scripts, you can deliver a quality experience for your customers no matter what part of the globe they call home. ~ https://stadiamaps.com/