--- title: "Create Asynchronous Distance Matrix" method: POST path: "/mdm/create" tags: ["Routing"] --- # Create Asynchronous Distance Matrix `POST /mdm/create` Create a massive distance matrix task ## Query parameters - `key` string, 32 character alphanumeric string, required - `option` 'flexible', required - `spliter` 'od_number_spliter' | 'straight_distance_spliter' | 'location_spliter' ## Request body - object - `origins` string, 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|… - `destinations` string — 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. - `avoid` 'toll' | 'ferry' | 'highway' | 'sharp_turn' | 'service_road' | 'bbox' | 'left_turn' | 'right_turn' | 'none' — 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_time` integer — 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_size` string — 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_weight` integer — 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_border` boolean — 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](mailto:support@nextbillion.ai) to enquire/enable other areas. - `truck_axle_load` number — 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. ## Response `200` - object - `task_id` string — A unique ID which can be used in the Asynchronous Distance Matrix GET method to retrieve the final result. - `code` string — 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](#api-error-codes) section below for more information. - `message` string — Returns the error message in case a request fails. This field will not be present in the response, if a request is successfully submitted. - `warning` string[] — 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. --- [API](https://skmtc.net/nextbillion-ai/apis/one-spec-service.md) · [All operations](https://skmtc.net/nextbillion-ai/apis/one-spec-service/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nextbillion-ai/one-spec-service/versions/b647f1808dda/schema)