openapi: 3.0.3
info:
description: '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. '
version: 7.1.0
title: Stadia Maps Routes API
contact:
name: Stadia Maps Support
url: https://www.stadiamaps.com
email: support@stadiamaps.com
servers:
- url: https://api.stadiamaps.com
- url: https://api-eu.stadiamaps.com
tags:
- name: Routes
paths:
/optimized_route/v1:
post:
tags:
- Routes
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
components:
schemas:
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
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
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.
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
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
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
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'
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
length: 0
cost: 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
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
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
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
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
minimum: 0
maximum: 1
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'
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
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'
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'
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
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'
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
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
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).
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'
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
travelMode:
type: string
enum:
- drive
- pedestrian
- bicycle
- transit
distanceUnit:
type: string
enum:
- km
- mi
default: km
valhallaLongUnits:
type: string
enum:
- miles
- kilometers
default: kilometers
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
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
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
osrmBannerComponent:
type: object
properties:
text:
type: string
type:
type: string
enum:
- text
- icon
- delimiter
- exit-number
- exit
- lane
transitInfo:
type: object
description: Public transit info (not currently supported).
additionalProperties: true
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
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.
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.
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
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
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 in
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stadia-maps/refs/heads/main/openapi/stadia-maps-routes-api-openapi.yml