Asynchronous Distance Matrix API

NextBillion.ai’s Asynchronous Distance Matrix API computes distances and ETAs between a large set of origins and destinations — could be for one-to-many or many-to-many scenarios. The API call returns the ETAs and distances for each origin and destination pair.

For example, if a set has Origins {A,B} and Destinations {C,D,E} we can get the following matrix of results with distance (meters) and time (seconds) for each.

As the name suggests, Asynchronous Distance Matrix API returns the result asynchronously. In the first step, users submit an HTTPS POST request containing the origin and destination coordinates. On successfully submitting the request the service would return a unique task ID. In the next step, the users can use this task ID to retrieve the result via an HTTPS GET request.

The Asynchronous Distance Matrix API has 2 versions - Fast and Flexible. We will be talking about both these services below.

Asynchronous Distance Matrix Fast

The Fast version of Asynchronous Distance Matrix returns the ETAs and distances between all combinations of provided origin and destination pairs for the given driving mode. To utilize the service users can make a POST request with the required fields of key and origins. Additionally, users can customize their request by including other optional parameters as listed in the table below.

Request Parameters

POST Request Body

Response Schema

Asynchronous Distance Matrix Flexible

The Flexible version of Asynchronous Distance Matrix allows users to make use of a few additional parameters like - truck specific constraints, add a departure time for the service to utilize the typical traffic conditions at the time, and add a preference for the fastest or the shortest route type. Users can send a HTTP POST request containing the mandatory parameters of key, origins and option along with other optional attributes to create a distance matrix task.

It is worth highlighting that to use the flexible version of the API users need to set the option parameter to flexible. Also, the Flexible-only attributes are not available in the Fast version and will be ineffective, if used.

Request Parameters

POST Request Body

Response Schema

Sample POST Request

Let’s take a look at an example POST request, where we:

• Add just one pair of origin and destination for simplicity.
• Set mode=truck to get the ETA and distance of a route pliable by a truck
• Define the dimensions and weight of the truck.
• Add option=flexible to ensure that truck parameters are effective

1
curl --location 'https://api.nextbillion.io/mdm/create?key=<your_api_key>&option=flexible' \
2
--header 'Content-Type: application/json' \
3
--data '{
4
"origins":"13.03394916,77.58855989",
5
"destinations":"13.03935192,77.58939313",
6
"mode":"truck",
7
"truck_size":"100,220,213",
8
"truck_weight":5000
9
}'

Sample POST Response

Here is the response that we receive on submitting the POST request. The ID received in the response will be used in subsequent sample examples for HTTPS GET method.

1
{
2
"code":"Ok",
3
"task_id":"aW5kaWEtdHJ1Y2stZmxleGlibGUtMjYzZTRiZjgtNjFjOS0zNDZmLThkOTQtMWM2YTZhNWFmYjQ0"
4
}

Asynchronous Distance Matrix GET Method

Use this method to retrieve the Distance Matrix solution link for the tasks created using either of the Asynchronous Distance Matrix POST methods.

Request Parameters

Response Schema

Sample GET Request

Let’s retrieve the result for the request submitted in the POST request example. We add the API Key and the id received from the response of the POST method.

1
curl --location 'https://api.nextbillion.io/mdm/status?key=<your_api_key>&id=aW5kaWEtdHJ1Y2stZmxleGlibGUtMjYzZTRiZjgtNjFjOS0zNDZmLThkOTQtMWM2YTZhNWFmYjQ0'

Sample GET Response

Once the service is done with processing the request, following response is returned:

1
{
2
"code":"Ok",
3
"status":"task fully succeeded",
4
"result_link":"https://oregon-cdn.nextbillion.io/mdm/api-auto-oregon/aW5kaWEtdHJ1Y2stZmxleGlibGUtMjYzZTRiZjgtNjFjOS0zNDZmLThkOTQtMWM2YTZhNWFmYjQ0/result.csv"
5
}

Read the Distance Matrix Results

Users can then copy the result link from the GET response and open it in a browser. The CSV file that the browser accesses contains the result of Asynchronous Distance Matrix request and the information is arranged as per the following column nomenclature and order

1
origin index, destination index, origin location, destination location, durations, distances

Following is a sample result for reference:

1
0, 0, 35.04651100,-106.64643000, 35.04651100,-106.64643000, 0, 0
2
0, 1, 35.04651100,-106.64643000, 40.76000000,-73.97000000, 131583, 3218636
3
0, 2, 35.04651100,-106.64643000, 41.13955180,-73.71247900, 133768, 3306569
4
0, 3, 35.04651100,-106.64643000, 41.79,-72.74, 137815, 3414733
5
1, 0, 40.76000000,-73.97000000, 35.04651100,-106.64643000, 130598, 3218029
6
1, 1, 40.76000000,-73.97000000, 40.76000000,-73.97000000, 0, 0
7
1, 2, 40.76000000,-73.97000000, 41.13955180,-73.71247900, 3700, 63364
8
1, 3, 40.76000000,-73.97000000, 41.79,-72.74, 8756, 185748

API Query Limits

1. For both Asynchronous Distance Matrix Fast & Flexible methods, NextBillion.ai allows a default limit of up to 4000 x 4000 Origin and Destination set
2. Maximum dimensions allowed for truck_size are 5000 cm for length, 5000 cm for width, 1000 cm for height.
3. Maximum weight allowed for truck_weight (including the trailer and shipped goods) is 100,000 kg
4. NextBillion.ai allows a maximum rate limit of 10 queries per second for the POST method and 50 queries per second for the GET method for continuous requests. Note: We can increase the quota if needed, on request. Contact [email protected] for more details.

API Error Codes