Stadia Maps Routing API

openapi: 3.2.0
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 Routing 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: Routing
paths:
  /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
  /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
components:
  schemas:
    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
    warning:
      type: object
      properties:
        text:
          type: string
        code:
          type: integer
    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
    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
    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.
    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.
    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
    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'
    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
    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
    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
    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
    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
    requestId:
      type: string
      description: An identifier to disambiguate requests (echoed by the server).
      example: kesklinn
    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
    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
    isochroneFeature:
      type: object
      properties:
        properties:
          $ref: '#/components/schemas/isochroneProperties'
        geometry:
          type: object
          additionalProperties: true
        type:
          type: string
          enum:
          - Feature
    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
    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.
    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'
    osrmBannerComponent:
      type: object
      properties:
        text:
          type: string
        type:
          type: string
          enum:
          - text
          - icon
          - delimiter
      

# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stadia-maps/refs/heads/main/openapi/stadia-maps-routing-api-openapi.yml