Sign in

v1

latestOpenAPI 3.1.02026-08-0420183200.9 KB
Routing

Match a recorded route to the road network.

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.

post/map_match/v1

Request body

idstring

An identifier to disambiguate requests (echoed by the server).

encoded_polylinestring

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 default 5!

costing'auto' | 'auto_traffic' | 'auto_traffic_premium' | 'bus' | 'bus_traffic' | 'bus_traffic_premium' | 'taxi' | 'taxi_traffic' | 'taxi_traffic_premium' | 'truck' | 'truck_traffic' | 'truck_traffic_premium' | 'bicycle' | 'bikeshare' | 'motor_scooter' | 'motorcycle' | 'pedestrian' | 'low_speed_vehicle' required
shape_match'edge_walk' | 'map_snap' | 'walk_or_snap'

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.

units'km' | 'mi'
language'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'
directions_type'none' | 'maneuvers' | 'instructions'

The level of directional narrative to include. Locations and times will always be returned, but narrative generation verbosity can be controlled with this parameter.

format'json' | 'osrm'

The output response format. The default JSON format is extremely compact and ideal for web or data-constrained use cases where you want to fetch additional attributes on demand in small chunks. The OSRM format is much richer and is configurable with significantly more info for turn-by-turn navigation use cases.

banner_instructionsboolean

Optionally includes helpful banners with timing information for turn-by-turn navigation. This is only available in the OSRM format.

voice_instructionsboolean

Optionally includes voice instructions with timing information for turn-by-turn navigation. This is only available in the OSRM format.

begin_timeinteger

The timestamp at the start of the trace. Combined with durations, this provides a way to include timing information for an encoded_polyline trace.

durationsinteger

A list of durations (in seconds) between each successive pair of points in a polyline.

use_timestampsboolean

If true, the input timestamps or durations should be used when computing elapsed time for each edge along the matched path rather than the routing algorithm estimates.

linear_referencesboolean

If true, the response will include a linear_references value that contains an array of base64-encoded OpenLR location references, one for each graph edge of the road network matched by the trace.

elevation_intervalnumber float

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.

Example request

{
  "costing": "pedestrian",
  "encoded_polyline": "_grbgAh~{nhF?lBAzBFvBHxBEtBKdB?fB@dBZdBb@hBh@jBb@x@\\|@x@pB\\x@v@hBl@nBPbCXtBn@|@z@ZbAEbAa@~@q@z@QhA]pAUpAVhAPlAWtASpAAdA[dASdAQhAIlARjANnAZhAf@n@`A?lB^nCRbA\\xB`@vBf@tBTbCFbARzBZvBThBRnBNrBP`CHbCF`CNdCb@vBX`ARlAJfADhA@dAFdAP`AR`Ah@hBd@bBl@rBV|B?vB]tBCvBBhAF`CFnBXtAVxAVpAVtAb@|AZ`Bd@~BJfA@fAHdADhADhABjAGzAInAAjAB|BNbCR|BTjBZtB`@lBh@lB\\|Bl@rBXtBN`Al@g@t@?nAA~AKvACvAAlAMdAU`Ac@hAShAI`AJ`AIdAi@bAu@|@k@p@]p@a@bAc@z@g@~@Ot@Bz@f@X`BFtBXdCLbAf@zBh@fBb@xAb@nATjAKjAW`BI|AEpAHjAPdAAfAGdAFjAv@p@XlAVnA?~A?jAInAPtAVxAXnAf@tBDpBJpBXhBJfBDpAZ|Ax@pAz@h@~@lA|@bAnAd@hAj@tAR~AKxAc@xAShA]hAIdAAjA]~A[v@BhB?dBSv@Ct@CvAI~@Oz@Pv@dAz@lAj@~A^`B^|AXvAVpAXdBh@~Ap@fCh@hB\\zBN`Aj@xBFdA@jALbAPbAJdAHdAJbAHbAHfAJhALbA\\lBTvBAdC@bC@jCKjASbC?`CM`CDpB\\xAj@tB\\fA\\bAVfAJdAJbAXz@L|BO`AOdCDdA@~B\\z@l@v@l@v@l@r@j@t@b@x@b@r@z@jBVfCJdAJdANbCPfCF|BRhBS~BS`AYbAe@~BQdA",
  "linear_references": true,
  "shape_match": "map_snap",
  "units": "miles"
}

Response

The matched route(s), which looks more or less like a normal route response, optionally with a linear_references key.

idstring

An identifier to disambiguate requests (echoed by the server).

linear_referencesstring[]

Example response

{
  "trip": {
    "language": "en-US",
    "legs": [
      {
        "maneuvers": [
          {
            "begin_shape_index": 0,
            "cost": 44.733,
            "end_shape_index": 1,
            "instruction": "Walk west on the walkway.",
            "length": 0.039,
            "time": 44.733,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 1,
            "verbal_post_transition_instruction": "Continue for 200 feet.",
            "verbal_pre_transition_instruction": "Walk west on the walkway."
          },
          {
            "begin_shape_index": 1,
            "cost": 4.941,
            "end_shape_index": 2,
            "instruction": "Turn left.",
            "length": 0.004,
            "time": 4.941,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 15,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 20 feet.",
            "verbal_pre_transition_instruction": "Turn left. Then Turn right onto Jefferson Street.",
            "verbal_transition_alert_instruction": "Turn left."
          },
          {
            "begin_shape_index": 2,
            "cost": 21.941,
            "end_shape_index": 3,
            "instruction": "Turn right onto Jefferson Street.",
            "length": 0.014,
            "street_names": [
              "Jefferson Street"
            ],
            "time": 16.941,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 10,
            "verbal_post_transition_instruction": "Continue for 80 feet.",
            "verbal_pre_transition_instruction": "Turn right onto Jefferson Street.",
            "verbal_transition_alert_instruction": "Turn right onto Jefferson Street."
          },
          {
            "begin_shape_index": 3,
            "cost": 9.941,
            "end_shape_index": 4,
            "instruction": "Turn left onto the walkway.",
            "length": 0.004,
            "time": 4.941,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 15,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 20 feet.",
            "verbal_pre_transition_instruction": "Turn left onto the walkway. Then Turn right onto the walkway.",
            "verbal_transition_alert_instruction": "Turn left onto the walkway."
          },
          {
            "begin_shape_index": 4,
            "cost": 6.352,
            "end_shape_index": 5,
            "instruction": "Turn right onto the walkway.",
            "length": 0.005,
            "time": 6.352,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 10,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 30 feet.",
            "verbal_pre_transition_instruction": "Turn right onto the walkway. Then Turn left onto Hyde Street.",
            "verbal_transition_alert_instruction": "Turn right onto the walkway."
          },
          {
            "begin_shape_index": 5,
            "cost": 63.588,
            "end_shape_index": 10,
            "instruction": "Turn left onto Hyde Street.",
            "length": 0.051,
            "street_names": [
              "Hyde Street"
            ],
            "time": 58.588,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 15,
            "verbal_post_transition_instruction": "Continue for 300 feet.",
            "verbal_pre_transition_instruction": "Turn left onto Hyde Street.",
            "verbal_transition_alert_instruction": "Turn left onto Hyde Street."
          },
          {
            "begin_shape_index": 10,
            "cost": 11.352,
            "end_shape_index": 11,
            "instruction": "Turn right onto the walkway.",
            "length": 0.005,
            "rough": true,
            "time": 6.352,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 10,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 30 feet.",
            "verbal_pre_transition_instruction": "Turn right onto the walkway. Then Turn left onto the walkway.",
            "verbal_transition_alert_instruction": "Turn right onto the walkway."
          },
          {
            "begin_shape_index": 11,
            "cost": 93.176,
            "end_shape_index": 17,
            "instruction": "Turn left onto the walkway.",
            "length": 0.082,
            "rough": true,
            "time": 93.176,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 15,
            "verbal_post_transition_instruction": "Continue for 400 feet.",
            "verbal_pre_transition_instruction": "Turn left onto the walkway.",
            "verbal_transition_alert_instruction": "Turn left onto the walkway."
          },
          {
            "begin_shape_index": 17,
            "cost": 7.764,
            "end_shape_index": 18,
            "instruction": "Turn left onto the walkway.",
            "length": 0.006,
            "rough": true,
            "time": 7.764,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 15,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 40 feet.",
            "verbal_pre_transition_instruction": "Turn left onto the walkway. Then Turn right onto Beach Street.",
            "verbal_transition_alert_instruction": "Turn left onto the walkway."
          },
          {
            "begin_shape_index": 18,
            "cost": 115.705,
            "end_shape_index": 24,
            "instruction": "Turn right onto Beach Street.",
            "length": 0.095,
            "street_names": [
              "Beach Street"
            ],
            "time": 110.705,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 10,
            "verbal_post_transition_instruction": "Continue for 500 feet.",
            "verbal_pre_transition_instruction": "Turn right onto Beach Street.",
            "verbal_transition_alert_instruction": "Turn right onto Beach Street."
          },
          {
            "begin_shape_index": 24,
            "cost": 73.058,
            "end_shape_index": 27,
            "instruction": "Turn left onto Polk Street.",
            "length": 0.059,
            "street_names": [
              "Polk Street"
            ],
            "time": 68.058,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 15,
            "verbal_post_transition_instruction": "Continue for 300 feet.",
            "verbal_pre_transition_instruction": "Turn left onto Polk Street.",
            "verbal_transition_alert_instruction": "Turn left onto Polk Street."
          },
          {
            "begin_shape_index": 27,
            "cost": 103,
            "end_shape_index": 32,
            "instruction": "Turn right onto the walkway.",
            "length": 0.084,
            "rough": true,
            "time": 98,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 10,
            "verbal_post_transition_instruction": "Continue for 400 feet.",
            "verbal_pre_transition_instruction": "Turn right onto the walkway.",
            "verbal_transition_alert_instruction": "Turn right onto the walkway."
          },
          {
            "begin_shape_index": 32,
            "cost": 98.294,
            "end_shape_index": 38,
            "instruction": "Turn left onto Van Ness Avenue.",
            "length": 0.073,
            "street_names": [
              "Van Ness Avenue"
            ],
            "time": 83.294,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 15,
            "verbal_post_transition_instruction": "Continue for 400 feet.",
            "verbal_pre_transition_instruction": "Turn left onto Van Ness Avenue.",
            "verbal_transition_alert_instruction": "Turn left onto Van Ness Avenue."
          },
          {
            "begin_shape_index": 38,
            "cost": 12.058,
            "end_shape_index": 39,
            "instruction": "Turn right onto the walkway.",
            "length": 0.006,
            "rough": true,
            "time": 7.058,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 10,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 30 feet.",
            "verbal_pre_transition_instruction": "Turn right onto the walkway. Then Turn left onto the walkway.",
            "verbal_transition_alert_instruction": "Turn right onto the walkway."
          },
          {
            "begin_shape_index": 39,
            "cost": 9.882,
            "end_shape_index": 40,
            "instruction": "Turn left onto the walkway.",
            "length": 0.008,
            "rough": true,
            "time": 9.882,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 15,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 50 feet.",
            "verbal_pre_transition_instruction": "Turn left onto the walkway. Then Turn right onto Bay Street.",
            "verbal_transition_alert_instruction": "Turn left onto the walkway."
          },
          {
            "begin_shape_index": 40,
            "cost": 199.823,
            "end_shape_index": 45,
            "instruction": "Turn right onto Bay Street.",
            "length": 0.171,
            "street_names": [
              "Bay Street"
            ],
            "time": 194.823,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 10,
            "verbal_post_transition_instruction": "Continue for 900 feet.",
            "verbal_pre_transition_instruction": "Turn right onto Bay Street.",
            "verbal_transition_alert_instruction": "Turn right onto Bay Street."
          },
          {
            "begin_shape_index": 45,
            "cost": 8.302,
            "end_shape_index": 46,
            "instruction": "Turn left onto Gough Street.",
            "length": 0.002,
            "street_names": [
              "Gough Street"
            ],
            "time": 3.302,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 15,
            "verbal_multi_cue": true,
            "verbal_post_transition_instruction": "Continue for 20 feet.",
            "verbal_pre_transition_instruction": "Turn left onto Gough Street. Then You will arrive at your destination.",
            "verbal_transition_alert_instruction": "Turn left onto Gough Street."
          },
          {
            "begin_shape_index": 46,
            "cost": 0,
            "end_shape_index": 46,
            "instruction": "You have arrived at your destination.",
            "length": 0,
            "time": 0,
            "travel_mode": "pedestrian",
            "travel_type": "foot",
            "type": 4,
            "verbal_pre_transition_instruction": "You have arrived at your destination.",
            "verbal_transition_alert_instruction": "You will arrive at your destination."
          }
        ],
        "shape": "uhrbgAt~{nhFrDhk@rBWfAbPvBWXfElAQhAi@dA]d[oDvIaAs@~Dp@n@r@r@^\\jAnQfDdh@lBtY`Eg@VzDXxDxAdPrD~j@zBf]TpD|C_@`\\uD|QaCZtE`Cp\\|A|UdCz^N`ClDJj@dJdDo@vGw@dKmAzWcDRdFpFq@d@dHpH`kAVbEXhEdKj_BpAO",
        "summary": {
          "cost": 883.918,
          "has_time_restrictions": false,
          "length": 0.716,
          "max_lat": 37.807771,
          "max_lon": -122.419706,
          "min_lat": 37.803694,
          "min_lon": -122.428418,
          "time": 818.918
        }
      }
    ],
    "linear_references": [
      "C6jyLBrisjr3Af+4//g6BA==",
      "C6jyCxrirjr3AAAA//s6Bw==",
      "C6jyDBriqyKUAP/j//0iAg==",
      "C6jx/xriqTr3AAAA//w6Ag==",
      "C6jx/xripjr0AP/2AAE6Hg==",
      "C6jx+xripiKUAQAM/8kiHw==",
      "C6jyARrijCKPAAAC/+8iBg==",
      "C6jyAxrihDrvAP/0AAM6BQ==",
      "C6jx/hrihTrzAP/5//o6Bw==",
      "C6jx+xrigjr1AP/h//06Bw==",
      "C6jx7RrigDr3Af++//k6Bw==",
      "C6jxzxrifDr3AP/T//w6Ag==",
      "C6jxuxrieTr3AAAA//g6Bw==",
      "C6jxvBridTLSAP/1AAAyBw==",
      "C6jxtxridDLSAP/2AAEyBg==",
      "C6jxsxridDLWAf+d//MyBw==",
      "C6jxhRribjLXAP/P//oyAg==",
      "C6jxbxriazLXAP/1//8yHw==",
      "C6jxaxriajLXAP////kyHw==",
      "C6jxaxriZjLTAAAJ/9MyHw==",
      "C6jxbxriUTLPAAAG/+IyBw==",
      "C6jxcxriQzrvAP/z//86Bw==",
      "C6jxbhriQjryAP/P//s6Bw==",
      "C6jxVxriPzr3AP/b//w6Bw==",
      "C6jxRhriPTr3AP/N//o6Aw==",
      "C6jxLxriOjr3AP/4AAA6Aw==",
      "C6jxLBriOTLXAP/9//kyBQ==",
      "C6jxKxriNSKTAP/u//8iHw==",
      "C6jxIxriNCKWAAAE/+siHw==",
      "C6jxJRriKiKPAAAE/+0iHw==",
      "C6jxJxriISKPAAAI/9kiAw==",
      "C6jxKxriDjrvAP/0AAA6AQ==",
      "C6jxJhriDjrzAAAB//Q6Bw==",
      "C6jxJxriCBpxAv9s/+8aBw==",
      "C6jw4xrh/xp3Av9a/+0aBQ==",
      "C6jwlhrh9jLXAAAA//0yBQ=="
    ],
    "locations": [
      {
        "lat": 37.807744,
        "lon": -122.4197,
        "type": "break"
      },
      {
        "lat": 37.803694,
        "lon": -122.428416,
        "type": "break"
      }
    ],
    "status": 0,
    "status_message": "Found route between points",
    "summary": {
      "cost": 883.918,
      "has_time_restrictions": false,
      "length": 0.716,
      "max_lat": 37.807771,
      "max_lon": -122.419706,
      "min_lat": 37.803694,
      "min_lon": -122.428418,
      "time": 818.918
    },
    "units": "miles"
  }
}