Dispatch4

Dispatches_Documents5

Dispatches_Routes2

Geofence11

Map-Data_Road-Editor8

Map-Data_Road-Editor_Areas1

Map-Data_Road-Segment1

Optimization4

Places5

Places_Geocoding5

Places_Multi-Geocode5

Routing12

Tracking_Asset11

Tracking_Monitor5

Tracking_Namespace2

Tracking_Search4

Tracking_Subscribe1

Tracking_Trip6

Tracking_Webhook3

Routing

Create Asynchronous Distance Matrix

Create a massive distance matrix task

post/mdm/create

Query parameters

keystring 32 character alphanumeric string required

Example:key=API_KEY

A key is a unique identifier that is required to authenticate a request to the API.

option'flexible' required

Example:option=flexible

Use this option to switch to truck-specific routing or time based routing or if you want to choose between the fastest and shortest route types.

spliter'od_number_spliter' | 'straight_distance_spliter' | 'location_spliter'

Specify a spliter to split the matrix by. It accepts 2 values:

od_number_spliter:
straight_distance_spliter:

Please note it is an internal, debug field only.

debug field. choose specific spliter to split matrix.

Request body

originsstring required

origins are the starting point of your route. Ensure that origins are routable land locations. Multiple origins should be separated by a pipe symbol (|).

Format: latitude_1,longitude_1|latitude_2,longitude_2|…

destinationsstring

destinations are the ending coordinates of your route. Ensure that destinations are routable land locations. Multiple destinations should be separated by a pipe symbol (|).

In case destinations are not provided or if it is left empty, then the input value of origins will be copied to destinations to create the OD matrix pairs.

Format: latitude_1,longitude_1|latitude_2,longitude_2|…

area'singapore' | 'usa' | 'india'

Provide the country that the coordinates belong to.

the input coordinates area.

mode'car' | 'truck'

Set which driving mode the service should use to determine a route.

For example, if you use car, the API will return a route that a car can take. Using truck will return a route a truck can use, taking into account appropriate truck routing restrictions.

Setting this will ensure the route avoids the object(s) specified as input. Multiple values should be separated by a pipe (|). If none is provided along with other values, an error is returned as a valid route is not feasible.

Note:
- This parameter is effective only when route_type=fastest.
- When this parameter is not provided in the input, ferries are set to be avoided by default. When avoid input is provided, only the mentioned objects are avoided.
- When using avoid=bbox users also need to specify the boundaries of the bounding box to be avoid. Multiple bounding boxes can be specified simultaneously. Please note that bounding box is a hard filter and if it blocks all possible routes between given locations, a 4xx error is returned.
  - Format: bbox: min_latitude,min_longtitude,max_latitude,max_longitude.
  - Example: avoid=bbox: 34.0635,-118.2547, 34.0679,-118.2478 | bbox: 34.0521,-118.2342, 34.0478,-118.2437
- When using avoid=sharp_turn, default range of permissible turn angles is [120,240].

departure_timeinteger

This is a number in UNIX epoch timestamp in seconds format that can be used to provide the departure time. The response will return the distance and duration of the route based on typical traffic for at the given start time.If no input is provided for this parameter then the traffic conditions at the time of making the request are considered.

Please note that when route_type is set to shortest then the departure_time will be ineffective as the service will return the result for the shortest path possible irrespective of the traffic conditions.

route_type'fastest' | 'shortest'

Set the route type that needs to be returned. Please note that route_type is effective only when option=flexible.

truck_sizestring

This defines the dimensions of a truck in centimeters (cm) in the format of "height,width,length". This parameter is effective only when mode=truck and option=flexible. Maximum dimensions are as follows:

Height = 1000 cm Width = 5000 cm Length = 5000 cm

truck_weightinteger

This parameter defines the weight of the truck including trailers and shipped goods in kilograms (kg). This parameter is effective only when mode=truck and option=flexible.

origins_approach'unrestricted' | 'curb'

Specify the side of the road from which to approach origins points. Please note that the given approach will be applied to all the points provided as origins.

destinations_approach'unrestricted' | 'curb'

Specify the side of the road from which to approach destinations points. Please note that the given approach will be applied to all the destinations.

hazmat_type'general' | 'circumstantial' | 'explosive' | 'harmful_to_water'

Specify the type of hazardous material being carried and the service will avoid roads which are not suitable for the type of goods specified. Multiple values can be separated using a pipe operator | .

Please note that this parameter is effective only when mode=truck.

cross_borderboolean

Specify if crossing an international border is expected for operations near border areas. When set to false, the API will prohibit routes going back & forth between countries. Consequently, routes within the same country will be preferred if they are feasible for the given set of destination or waypoints . When set to true, the routes will be allowed to go back & forth between countries as needed.

This feature is available in North America region only. Please get in touch with support@nextbillion.ai to enquire/enable other areas.

truck_axle_loadnumber

Specify the total load per axle (including the weight of trailers and shipped goods) of the truck, in tonnes. When used, the service will return routes which are legally allowed to carry the load specified per axle.

Please note this parameter is effective only when mode=truck.

Example request

{
  "avoid": "\"avoid\"=\"highway|toll\"",
  "route_type": "\"route_type\"=\"fastest\"",
  "truck_size": "\"truck_size\"=200,210,600",
  "origins_approach": "\"originis_approach\"=\"unrestricted\"",
  "destinations_approach": "\"destinations_approach\"=\"unrestricted\"",
  "hazmat_type": "\"hazmat_type\"=\"explosive | harmful_to_water\""
}

Response

task_idstring

A unique ID which can be used in the Asynchronous Distance Matrix GET method to retrieve the final result.

codestring

A string indicating the state of the response. On successful responses, the value will be Ok. Indicative error messages/codes are returned in case of errors. See the API Error Codes section below for more information.

messagestring

Returns the error message in case a request fails. This field will not be present in the response, if a request is successfully submitted.

warningstring[]

Display the warnings, if any, for the given input parameters and values. In case there are no warnings then this field would not be present in the response.

Changes

Changed in 3 of the 15 revisions of this API.6378

Jul 31, 20257ee76f0ff6792126See the full diff
- ▲
  removed the enum value bbox of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value car of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value circumstantial of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value curb of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value curb of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value explosive of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value fastest of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value ferry of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value general of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value harmful_to_water of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value highway of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value left_turn of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value none of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value right_turn of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value service_road of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value sharp_turn of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value shortest of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value toll of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value truck of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value unrestricted of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value unrestricted of the request property
  request-property-enum-value-removed
- ○
  the request property default value changed from ferry to ferry
  request-property-default-value-changed
- ○
  the request property default value changed from unrestricted to unrestricted
  request-property-default-value-changed
- ○
  the request property default value changed from car to car
  request-property-default-value-changed
- ○
  the request property default value changed from unrestricted to unrestricted
  request-property-default-value-changed
- ○
  the request property default value changed from fastest to fastest
  request-property-default-value-changed
- ○
  added the new bbox enum value to the request property
  request-property-enum-value-added
- ○
  added the new car enum value to the request property
  request-property-enum-value-added
- ○
  added the new circumstantial enum value to the request property
  request-property-enum-value-added
- ○
  added the new curb enum value to the request property
  request-property-enum-value-added
- ○
  added the new curb enum value to the request property
  request-property-enum-value-added
- ○
  added the new explosive enum value to the request property
  request-property-enum-value-added
- ○
  added the new fastest enum value to the request property
  request-property-enum-value-added
- ○
  added the new ferry enum value to the request property
  request-property-enum-value-added
- ○
  added the new general enum value to the request property
  request-property-enum-value-added
- ○
  added the new harmful_to_water enum value to the request property
  request-property-enum-value-added
- ○
  added the new highway enum value to the request property
  request-property-enum-value-added
- ○
  added the new left_turn enum value to the request property
  request-property-enum-value-added
- ○
  added the new none enum value to the request property
  request-property-enum-value-added
- ○
  added the new right_turn enum value to the request property
  request-property-enum-value-added
- ○
  added the new service_road enum value to the request property
  request-property-enum-value-added
- ○
  added the new sharp_turn enum value to the request property
  request-property-enum-value-added
- ○
  added the new shortest enum value to the request property
  request-property-enum-value-added
- ○
  added the new toll enum value to the request property
  request-property-enum-value-added
- ○
  added the new truck enum value to the request property
  request-property-enum-value-added
- ○
  added the new unrestricted enum value to the request property
  request-property-enum-value-added
- ○
  added the new unrestricted enum value to the request property
  request-property-enum-value-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jul 31, 2025a800b73f11c12126See the full diff
- ▲
  removed the enum value bbox of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value car of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value circumstantial of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value curb of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value curb of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value explosive of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value fastest of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value ferry of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value general of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value harmful_to_water of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value highway of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value left_turn of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value none of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value right_turn of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value service_road of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value sharp_turn of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value shortest of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value toll of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value truck of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value unrestricted of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value unrestricted of the request property
  request-property-enum-value-removed
- ○
  the request property default value changed from ferry to ferry
  request-property-default-value-changed
- ○
  the request property default value changed from unrestricted to unrestricted
  request-property-default-value-changed
- ○
  the request property default value changed from car to car
  request-property-default-value-changed
- ○
  the request property default value changed from unrestricted to unrestricted
  request-property-default-value-changed
- ○
  the request property default value changed from fastest to fastest
  request-property-default-value-changed
- ○
  added the new bbox enum value to the request property
  request-property-enum-value-added
- ○
  added the new car enum value to the request property
  request-property-enum-value-added
- ○
  added the new circumstantial enum value to the request property
  request-property-enum-value-added
- ○
  added the new curb enum value to the request property
  request-property-enum-value-added
- ○
  added the new curb enum value to the request property
  request-property-enum-value-added
- ○
  added the new explosive enum value to the request property
  request-property-enum-value-added
- ○
  added the new fastest enum value to the request property
  request-property-enum-value-added
- ○
  added the new ferry enum value to the request property
  request-property-enum-value-added
- ○
  added the new general enum value to the request property
  request-property-enum-value-added
- ○
  added the new harmful_to_water enum value to the request property
  request-property-enum-value-added
- ○
  added the new highway enum value to the request property
  request-property-enum-value-added
- ○
  added the new left_turn enum value to the request property
  request-property-enum-value-added
- ○
  added the new none enum value to the request property
  request-property-enum-value-added
- ○
  added the new right_turn enum value to the request property
  request-property-enum-value-added
- ○
  added the new service_road enum value to the request property
  request-property-enum-value-added
- ○
  added the new sharp_turn enum value to the request property
  request-property-enum-value-added
- ○
  added the new shortest enum value to the request property
  request-property-enum-value-added
- ○
  added the new toll enum value to the request property
  request-property-enum-value-added
- ○
  added the new truck enum value to the request property
  request-property-enum-value-added
- ○
  added the new unrestricted enum value to the request property
  request-property-enum-value-added
- ○
  added the new unrestricted enum value to the request property
  request-property-enum-value-added
Jul 30, 2025b79d96775b132126See the full diff
- ▲
  removed the enum value bbox of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value car of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value circumstantial of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value curb of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value curb of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value explosive of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value fastest of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value ferry of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value general of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value harmful_to_water of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value highway of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value left_turn of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value none of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value right_turn of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value service_road of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value sharp_turn of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value shortest of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value toll of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value truck of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value unrestricted of the request property
  request-property-enum-value-removed
- ▲
  removed the enum value unrestricted of the request property
  request-property-enum-value-removed
- ○
  the request property default value changed from ferry to ferry
  request-property-default-value-changed
- ○
  the request property default value changed from unrestricted to unrestricted
  request-property-default-value-changed
- ○
  the request property default value changed from car to car
  request-property-default-value-changed
- ○
  the request property default value changed from unrestricted to unrestricted
  request-property-default-value-changed
- ○
  the request property default value changed from fastest to fastest
  request-property-default-value-changed
- ○
  added the new bbox enum value to the request property
  request-property-enum-value-added
- ○
  added the new car enum value to the request property
  request-property-enum-value-added
- ○
  added the new circumstantial enum value to the request property
  request-property-enum-value-added
- ○
  added the new curb enum value to the request property
  request-property-enum-value-added
- ○
  added the new curb enum value to the request property
  request-property-enum-value-added
- ○
  added the new explosive enum value to the request property
  request-property-enum-value-added
- ○
  added the new fastest enum value to the request property
  request-property-enum-value-added
- ○
  added the new ferry enum value to the request property
  request-property-enum-value-added
- ○
  added the new general enum value to the request property
  request-property-enum-value-added
- ○
  added the new harmful_to_water enum value to the request property
  request-property-enum-value-added
- ○
  added the new highway enum value to the request property
  request-property-enum-value-added
- ○
  added the new left_turn enum value to the request property
  request-property-enum-value-added
- ○
  added the new none enum value to the request property
  request-property-enum-value-added
- ○
  added the new right_turn enum value to the request property
  request-property-enum-value-added
- ○
  added the new service_road enum value to the request property
  request-property-enum-value-added
- ○
  added the new sharp_turn enum value to the request property
  request-property-enum-value-added
- ○
  added the new shortest enum value to the request property
  request-property-enum-value-added
- ○
  added the new toll enum value to the request property
  request-property-enum-value-added
- ○
  added the new truck enum value to the request property
  request-property-enum-value-added
- ○
  added the new unrestricted enum value to the request property
  request-property-enum-value-added
- ○
  added the new unrestricted enum value to the request property
  request-property-enum-value-added

Full history