MapMetrics Atlas API Docs

Appearance

Matrix Service ​

The time distance matrix service takes a sources and targets to list locations. This allows you to set the source (origin) locations separately from the target (destination) locations. The set of origins may be disjoint (not overlapping) with the set of destinations. In other words, the target locations do not have to include any locations from source locations. The time-distance matrix can return a row matrix, a column matrix, or a general matrix of computed time and distance, depending on your input for the sources and targets parameters. The general case is a row ordered matrix with the time and distance from each source location to each target location. A row vector is considered a one_to_many time-distance matrix where there is one source location and multiple target locations. The time and distance from the source location to all target locations is returned. A column matrix represents a many_to_one time-distance matrix where there are many sources and one target. Another special case is when the source location list is the same as the target location list. Here, a diagonal (square matrix with [0,0.00] on the diagonal elements) matrix is returned. The is special case is often used as the input to optimized routing problems.

Required Parameters ​

  • Query Param:
    • token → Required /matrix/?token=YOUR_TOKEN (Authorization, otherwise 401 Token required error will occur)
  • Body JSON:
    • sources → Required (List of source coordinates)
    • targets → Optional (List of target coordinates, defaults to sources if omitted)
    • costing → Required (Travel mode, e.g. pedestrian, auto, bicycle)

Examples (Copy & Paste) ​

One-to-Many ​

json
{ "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" }

Many-to-One ​

json
{ "sources": [ { "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 } ], "targets": [ { "lat": 40.750552, "lon": -73.993519 } ], "costing": "pedestrian" }

Many-to-Many ​

json
{ "sources": [ { "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 } ], "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" }

Costing parameter ​

The Time-Distance Matrix service uses the auto, bicycle, pedestrian and bikeshare and other costing models available in the route service. Exception: multimodal costing is not supported for the time-distance matrix service at this time.

Other Request Option ​

OptionDescription
verboseIf true, it will output a flat list of objects for distances & durations explicitly specifying the source & target indices. If false, will return more compact, nested row-major distances & durations arrays and not echo sources and targets.
Default: true.
shape_formatSpecifies the optional format for the path shape of each connection. One of polyline6, polyline5, geojson, or no_shape (default).

Outputs of the matrix service ​

Depending on the verbose (default: true) request parameter, the result of the Time-Distance Matrix service is different. In both ("verbose": true and "verbose": false) cases, these parameters are present:

ItemDescription
algorithmThe algorithm used to compute the results. Can be "timedistancematrix", "costmatrix", or "timedistancebssmatrix".
unitsDistance units for output. Allowable unit types are "miles" and "kilometers". If no unit type is specified in the input, the units default to "kilometers".
warnings (optional)This array may contain warning objects informing about deprecated request parameters, clamped values etc.

Verbose mode ("verbose": true) ​

The following parameters are only present in "verbose": true mode:

ItemDescription
sourcesThe sources passed to the request.
targetsThe targets passed to the request.
sources_to_targetsAn array of time and distance between the sources and the targets. The array is row-ordered, meaning the time and distance from the first location to all others forms the first row of the array, followed by the time and distance from the second source location to all target locations, etc. The Object contained in the arrays contains the following fields:
  • distance: The computed distance between each set of points. Distance will always be 0.00 for the first element of the time-distance array for one_to_many, the last element in a many_to_one, and the first and last elements of a many_to_many.
  • time: The computed time between each set of points. Time will always be 0 for the first element of the time-distance array for one_to_many, the last element in a many_to_one, and the first and last elements of a many_to_many.
  • to_index: The destination index into the locations array.
  • from_index: The origin index into the locations array.
When a user will arrive at/depart from this location. See the part above where we explain how time dependent matrices work for further context. Note: If the time is above the setting max_time_dep_distance_matrix this is skipped.

Concise mode ("verbose": false) ​

ItemDescription
sources_to_targetReturns an object with durations and distances as row-ordered contents of the values above.