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 Roads 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: Roads
paths:
/nearest_roads/v1:
post:
tags:
- Roads
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
components:
schemas:
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
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
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
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
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
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.
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'
nodeId:
type: object
properties:
id:
type: integer
format: int64
value:
type: integer
format: int64
tile_id:
type: integer
format: int64
level:
type: integer
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
distanceUnit:
type: string
enum:
- km
- mi
default: km
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
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
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
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
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
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
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.'
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
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.
nodeType:
type: string
enum:
- street_intersection
- gate
- bollard
- toll_booth
- multi_use_transit_stop
- bike_share
- parking
- motor_way_junction
- border_control
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.'
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.
requestId:
type: string
description: An identifier to disambiguate requests (echoed by the server).
example: kesklinn
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
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?
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
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
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
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stadia-maps/refs/heads/main/openapi/stadia-maps-roads-api-openapi.yml