Documentation

Matrix

Last updated October 2, 2026

Compute travel times and distances between every source and every target. Useful for ranking candidates by travel time before planning a full route.

GETPOSThttps://transit.land/api/v2/routing/valhalla/sources_to_targets

Calculate a time-distance matrix from multiple source locations to multiple target locations. Useful for solving optimization problems.

Request

The request object, url-encoded. Identical to the POST body. Encode spaces as %20, or send the JSON without spaces. The API does not decode + as a space and rejects the request as unparseable.

expansion_max_distanceoptional integer

Maximum path distance in meters for an expansion. Currently this is implemented for the timedistancematrix algorithm. Source-target pairs whose cheapest path distance exceeds this limit will be returned as unreachable (with null time and distance).

Default:0

matrix_locationsoptional integer

Early-exit after finding this many targets. Only valid for TDMatrix algorithm.

shape_formatoptional string

Not all formats are supported by all endpoints, e.g. no_shape is not valid for isochrone.

Default:polyline6Allowed:polyline6, polyline5, geojson, no_shapeExample:polyline6

sourcesarray of objectsrequired

sources.date_timeoptional string: Per-location ISO 8601 datetime override, in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06.
sources.display_latoptional number: Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
sources.display_lonoptional number: Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
sources.headingoptional integer: Preferred approach heading in degrees.
sources.heading_toleranceoptional integer: How close in degrees a given street's angle must be in order for it to be considered as in the same direction of the heading parameter. The default value is service configuration dependent (60 by default).
sources.latnumberrequired
sources.lonnumberrequired
sources.minimum_reachabilityoptional integer: Minimum number of reachable edges for a snap candidate. The default and max values are service configuration dependent (50 and 100 by default, respectively).
Default:50
sources.nameoptional string: Label echoed in the response.
sources.node_snap_toleranceoptional number: Snap-to-node distance tolerance in meters. The default value is service dependent (5 by default).
sources.preferred_layeroptional integer: If set, edges whose layer does not match this value are discarded from candidate search. Note that this is a "soft" filter, meaning if no other candidates are found, Valhalla will fall back to including edges that did not match this filter.
sources.preferred_sideoptional string: Preferred side of road to snap to.
Default:eitherAllowed:same, opposite, eitherExample:opposite
sources.radiusoptional integer: Candidate search radius in meters: all viable edge candidates within the radius are correlated. If none are found, the best one outside the radius is correlated. The default is service dependent, and defaults to 0 (only the closest edge is considered as candidate). The max value is service configuration dependent (200 by default).
sources.rank_candidatesoptional boolean: Rank snap candidates by distance to input.
Default:true
sources.search_cutoffoptional integer: Hard cutoff for candidate search in meters. Default is service configuration dependent (35000 by default).
sources.search_filteroptional object: Optional filters to exclude candidate edges based on their attribution.
sources.streetoptional string: Street address hint for snapping.
sources.street_side_cutoffoptional string: Allowed:motorway, trunk, primary, secondary, tertiary, unclassified, residential, service_otherExample:primary
sources.street_side_max_distanceoptional integer: The max distance in meters that the input coordinates or display ll can be from the edge centerline for them to be used for determining the side of street. Beyond this distance the side of street is set to none. The default value is service configuration dependent (1000 by default).
sources.street_side_toleranceoptional integer: If your input coordinate is less than this tolerance away from the edge centerline then we set your side of street to none otherwise your side of street will be left or right depending on direction of travel. The default value is service configuration dependent (5 by default).
sources.typeoptional string: First and last location are always forced to break.
Default:breakExample:break
Values
break Stop here; starts or ends a route leg. Allows U-turns.
through Pass through without stopping. No U-turn; keeps direction of travel.
via Waypoint with a maneuver instruction but no leg-break. Allows U-turns.
break_through Like `break` but does not allow U-turns at the location.
sources.waitingoptional number: Waiting time in seconds at this stop (break/break_through only, not origin/destination).

Values
`break`	Stop here; starts or ends a route leg. Allows U-turns.
`through`	Pass through without stopping. No U-turn; keeps direction of travel.
`via`	Waypoint with a maneuver instruction but no leg-break. Allows U-turns.
`break_through`	Like `break` but does not allow U-turns at the location.

targetsarray of objectsrequired

targets.date_timeoptional string: Per-location ISO 8601 datetime override, in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06.
targets.display_latoptional number: Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
targets.display_lonoptional number: Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
targets.headingoptional integer: Preferred approach heading in degrees.
targets.heading_toleranceoptional integer: How close in degrees a given street's angle must be in order for it to be considered as in the same direction of the heading parameter. The default value is service configuration dependent (60 by default).
targets.latnumberrequired
targets.lonnumberrequired
targets.minimum_reachabilityoptional integer: Minimum number of reachable edges for a snap candidate. The default and max values are service configuration dependent (50 and 100 by default, respectively).
Default:50
targets.nameoptional string: Label echoed in the response.
targets.node_snap_toleranceoptional number: Snap-to-node distance tolerance in meters. The default value is service dependent (5 by default).
targets.preferred_layeroptional integer: If set, edges whose layer does not match this value are discarded from candidate search. Note that this is a "soft" filter, meaning if no other candidates are found, Valhalla will fall back to including edges that did not match this filter.
targets.preferred_sideoptional string: Preferred side of road to snap to.
Default:eitherAllowed:same, opposite, eitherExample:opposite
targets.radiusoptional integer: Candidate search radius in meters: all viable edge candidates within the radius are correlated. If none are found, the best one outside the radius is correlated. The default is service dependent, and defaults to 0 (only the closest edge is considered as candidate). The max value is service configuration dependent (200 by default).
targets.rank_candidatesoptional boolean: Rank snap candidates by distance to input.
Default:true
targets.search_cutoffoptional integer: Hard cutoff for candidate search in meters. Default is service configuration dependent (35000 by default).
targets.search_filteroptional object: Optional filters to exclude candidate edges based on their attribution.
targets.streetoptional string: Street address hint for snapping.
targets.street_side_cutoffoptional string: Allowed:motorway, trunk, primary, secondary, tertiary, unclassified, residential, service_otherExample:primary
targets.street_side_max_distanceoptional integer: The max distance in meters that the input coordinates or display ll can be from the edge centerline for them to be used for determining the side of street. Beyond this distance the side of street is set to none. The default value is service configuration dependent (1000 by default).
targets.street_side_toleranceoptional integer: If your input coordinate is less than this tolerance away from the edge centerline then we set your side of street to none otherwise your side of street will be left or right depending on direction of travel. The default value is service configuration dependent (5 by default).
targets.typeoptional string: First and last location are always forced to break.
Default:breakExample:break
Values
break Stop here; starts or ends a route leg. Allows U-turns.
through Pass through without stopping. No U-turn; keeps direction of travel.
via Waypoint with a maneuver instruction but no leg-break. Allows U-turns.
break_through Like `break` but does not allow U-turns at the location.
targets.waitingoptional number: Waiting time in seconds at this stop (break/break_through only, not origin/destination).

Values
`break`	Stop here; starts or ends a route leg. Allows U-turns.
`through`	Pass through without stopping. No U-turn; keeps direction of travel.
`via`	Waypoint with a maneuver instruction but no leg-break. Allows U-turns.
`break_through`	Like `break` but does not allow U-turns at the location.

verboseoptional boolean

Include detailed per-cell metadata in the response.

Default:true

costingstringrequired

multimodal is not available. The street graph has no transit; use transit routing at /otp/plan.

Allowed:auto, bicycle, pedestrian, truck, bus, taxi, motor_scooter, motorcycle, bikeshare, auto_pedestrianExample:auto

costing_optionsoptional object

Costing options keyed by costing model name.

costing_options.autooptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.bicycleoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.bikeshareoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.busoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.motor_scooteroptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.motorcycleoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.pedestrianoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.taxioptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.
costing_options.truckoptional object: Options shared by all costing models. Parsed in src/sif/dynamiccost.cc.

date_timeoptional object

date_time.typeoptional integer: 0=current, 1=depart_at, 2=arrive_by, 3=invariant
Allowed:0, 1, 2, 3
date_time.valueoptional string: ISO 8601 local datetime string in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06. Required for types 1, 2, 3.

exclude_locationsoptional array of objects

A set of locations to exclude or avoid within a route.

exclude_locations.date_timeoptional string: Per-location ISO 8601 datetime override, in the format YYYY-MM-DDTHH:MM, e.g. 2016-07-03T08:06.
exclude_locations.display_latoptional number: Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
exclude_locations.display_lonoptional number: Latitude of the map location in degrees. If provided the lat and lon parameters will be treated as the routing location and the display_lat and display_lon will be used to determine the side of street. Both display_lat and display_lon must be provided and valid to achieve the desired effect.
exclude_locations.headingoptional integer: Preferred approach heading in degrees.
exclude_locations.heading_toleranceoptional integer: How close in degrees a given street's angle must be in order for it to be considered as in the same direction of the heading parameter. The default value is service configuration dependent (60 by default).
exclude_locations.latnumberrequired
exclude_locations.lonnumberrequired
exclude_locations.minimum_reachabilityoptional integer: Minimum number of reachable edges for a snap candidate. The default and max values are service configuration dependent (50 and 100 by default, respectively).
Default:50
exclude_locations.nameoptional string: Label echoed in the response.
exclude_locations.node_snap_toleranceoptional number: Snap-to-node distance tolerance in meters. The default value is service dependent (5 by default).
exclude_locations.preferred_layeroptional integer: If set, edges whose layer does not match this value are discarded from candidate search. Note that this is a "soft" filter, meaning if no other candidates are found, Valhalla will fall back to including edges that did not match this filter.
exclude_locations.preferred_sideoptional string: Preferred side of road to snap to.
Default:eitherAllowed:same, opposite, eitherExample:opposite
exclude_locations.radiusoptional integer: Candidate search radius in meters: all viable edge candidates within the radius are correlated. If none are found, the best one outside the radius is correlated. The default is service dependent, and defaults to 0 (only the closest edge is considered as candidate). The max value is service configuration dependent (200 by default).
exclude_locations.rank_candidatesoptional boolean: Rank snap candidates by distance to input.
Default:true
exclude_locations.search_cutoffoptional integer: Hard cutoff for candidate search in meters. Default is service configuration dependent (35000 by default).
exclude_locations.search_filteroptional object: Optional filters to exclude candidate edges based on their attribution.
exclude_locations.streetoptional string: Street address hint for snapping.
exclude_locations.street_side_cutoffoptional string: Allowed:motorway, trunk, primary, secondary, tertiary, unclassified, residential, service_otherExample:primary
exclude_locations.street_side_max_distanceoptional integer: The max distance in meters that the input coordinates or display ll can be from the edge centerline for them to be used for determining the side of street. Beyond this distance the side of street is set to none. The default value is service configuration dependent (1000 by default).
exclude_locations.street_side_toleranceoptional integer: If your input coordinate is less than this tolerance away from the edge centerline then we set your side of street to none otherwise your side of street will be left or right depending on direction of travel. The default value is service configuration dependent (5 by default).
exclude_locations.typeoptional string: First and last location are always forced to break.
Default:breakExample:break
Values
break Stop here; starts or ends a route leg. Allows U-turns.
through Pass through without stopping. No U-turn; keeps direction of travel.
via Waypoint with a maneuver instruction but no leg-break. Allows U-turns.
break_through Like `break` but does not allow U-turns at the location.
exclude_locations.waitingoptional number: Waiting time in seconds at this stop (break/break_through only, not origin/destination).

Values
`break`	Stop here; starts or ends a route leg. Allows U-turns.
`through`	Pass through without stopping. No U-turn; keeps direction of travel.
`via`	Waypoint with a maneuver instruction but no leg-break. Allows U-turns.
`break_through`	Like `break` but does not allow U-turns at the location.

exclude_polygonsoptional array or object

Array of coordinate rings [[lon,lat],…] or a GeoJSON FeatureCollection. Roads intersecting these rings will be avoided during path finding. Takes one of the 2 forms listed below.

array of arraysarray of arrays: Array of closed coordinate rings. All edges intersecting any ring are excluded.
objectobject: GeoJSON FeatureCollection. Each Feature may carry a properties.levels array to restrict exclusion to specific building/indoor levels in pedestrian routing.

formatoptional string

Not all formats are supported by all endpoints, e.g. geotiff is isochrone-only.

Default:jsonAllowed:json, gpx, osrm, pbf, geotiff, mvtExample:json

idoptional string

Arbitrary request identifier echoed in the response.

languageoptional string

BCP47 locale for narrative output. See locales/ for supported values.

Default:en-US

linear_cost_factorsoptional array of objects

Customized cost factors that influence path finding, specified as an array of JSON objects. Objects can be either a GeoJSON linestring feature and a "factor" property or a plain object with a "shape" key, whose value needs to be an encoded polyline (with 6 digit precision), and a "factor" key whose value needs to be float. Valhalla will perform an edge walk (see the map matching documentation for more info) to match the geometry onto edges and use those factors in costing. Edges with factors larger than 1 will be increasingly avoided, while edges with factors smaller than 1 increasingly favored.

object with shape, factorobject
object with type, geometry, propertiesobject

unitsoptional string

Default:kmAllowed:km, miles, mi

Response

algorithmstring

Which matrix algorithm answered the request.

Example:costmatrix

sourcesarray of objects

The requested sources, snapped to the network. Verbose form only.

sources.latnumber (double): Latitude of the snapped location.
sources.lonnumber (double): Longitude of the snapped location.

sources_to_targetsarray or object

The matrix itself. Its shape follows the request's verbose flag, which defaults to true: verbose gives one row per source holding a cell per target, while verbose: false gives two parallel arrays-of-arrays instead. Takes one of the 2 forms listed below.

array of arraysarray of arrays

Verbose form. One row per source, each holding one cell per target.

sources_to_targets.begin_headingnumber

Compass bearing on departure, in degrees.

sources_to_targets.begin_latnumber (double)

Latitude where the route leaves the source.

sources_to_targets.begin_lonnumber (double)

Longitude where the route leaves the source.

sources_to_targets.costnullable number

Cost of the route under the request's costing model, the value the search minimizes.

sources_to_targets.date_timestring

The request's date_time plus the travel time, as local YYYY-MM-DDTHH:MM. Present only when the search starts from the locations that carry the request's date_time: for a depart_at request searched forward from the sources, it is the arrival time at the target. Absent for pairs beyond the time-dependent distance limit, and for depart_at requests with more sources than targets, which are searched from the targets.

sources_to_targets.distancenullable number

Distance in the response's units, or null when no route exists between the pair.

sources_to_targets.end_headingnumber

Compass bearing on arrival, in degrees.

sources_to_targets.end_latnumber (double)

Latitude where the route reaches the target.

sources_to_targets.end_lonnumber (double)

Longitude where the route reaches the target.

sources_to_targets.from_indexinteger

Index into sources.

sources_to_targets.shapestring or object

The route between the pair: an encoded polyline at precision 6, or 5 with shape_format: polyline5, or a GeoJSON geometry with shape_format: geojson. Present only when the request sets shape_format and the engine uses its CostMatrix algorithm. Takes one of the 2 forms listed below.

sources_to_targets.timenullable integer

Travel time in seconds, or null when no route exists between the pair.

sources_to_targets.time_zone_namestring

IANA time zone of date_time, e.g. America/Los_Angeles. Present with date_time.

sources_to_targets.time_zone_offsetstring

UTC offset of date_time, as +HH:MM or -HH:MM. Present with date_time.

sources_to_targets.to_indexinteger

Index into targets.

objectobject

Compact form, returned when verbose is false.

targetsarray of objects

The requested targets, snapped to the network. Verbose form only.

targets.latnumber (double): Latitude of the snapped location.
targets.lonnumber (double): Longitude of the snapped location.

unitsstring

Units the distances are expressed in.

Allowed:kilometers, miles

curl --get "https://transit.land/api/v2/routing/valhalla/sources_to_targets" \
  -H "apikey: YOUR_API_KEY" \
  --data-urlencode 'json={"costing":"auto","sources":[{"lat":37.7793,"lon":-122.4193},{"lat":37.7817,"lon":-122.4108}],"targets":[{"lat":37.7817,"lon":-122.4108},{"lat":37.7844,"lon":-122.4079}]}'

Example response

{
  "sources_to_targets": [
    [
      {
        "from_index": 0,
        "to_index": 0,
        "time": 130,
        "distance": 1.053,
        "cost": 247.47,
        "begin_heading": 350.9,
        "end_heading": 83,
        "begin_lat": 37.779214,
        "begin_lon": -122.419983,
        "end_lat": 37.782246,
        "end_lon": -122.410884
      },
      {
        "from_index": 0,
        "to_index": 1,
        "time": 196,
        "distance": 1.546,
        "cost": 405.357,
        "begin_heading": 350.9,
        "end_heading": 134.8,
        "begin_lat": 37.779214,
        "begin_lon": -122.419983,
        "end_lat": 37.784135,
        "end_lon": -122.408233
      }
    ],
    [
      {
        "from_index": 1,
        "to_index": 0,
        "time": 160,
        "distance": 1.221,
        "cost": 300,
        "begin_heading": 83,
        "end_heading": 83,
        "begin_lat": 37.782246,
        "begin_lon": -122.410884,
        "end_lat": 37.782246,
        "end_lon": -122.410884
      },
      {
        "from_index": 1,
        "to_index": 1,
        "time": 70,
        "distance": 0.495,
        "cost": 177.063,
        "begin_heading": 83,
        "end_heading": 314.8,
        "begin_lat": 37.782246,
        "begin_lon": -122.410884,
        "end_lat": 37.784135,
        "end_lon": -122.408233
      }
    ]
  ],
  "sources": [
    {
      "lat": 37.779214,
      "lon": -122.419983
    },
    {
      "lat": 37.782246,
      "lon": -122.410884
    }
  ],
  "targets": [
    {
      "lat": 37.782246,
      "lon": -122.410884
    },
    {
      "lat": 37.784135,
      "lon": -122.408233
    }
  ],
  "units": "kilometers",
  "algorithm": "costmatrix"
}

See the Routing Platform overview for API access, travel modes, and the machine-readable schema.

Reference: Valhalla matrix API reference