Stadia Maps Match 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 Match 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: Match
paths:
  /map_match/v1:
    post:
      tags:
      - Match
      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
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
    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.
    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
    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
    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
    requestId:
      type: string
      description: An identifier to disambiguate requests (echoed by the server).
      example: kesklinn
    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
    distanceUnit:
      type: string
      enum:
      - km
      - mi
      default: km
    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
    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
    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.
    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
    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.
    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
    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.\nThe default speeds are as follows based on bicycle type:\n  * Road - 25kph\n  * Cross - 20kph\n  * Hybrid - 18kph\n  * 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
    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
    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:

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