Distance Matrix API

Introduction

NextBillion.ai’s Distance Matrix API computes distances and ETAs between a set of origins and destinations — could be for one-to-many or many-to-many scenarios. The API call returns a matrix of 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.

CDE

A

A -> CA -> DA -> E

B

B -> CB -> DB -> E

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

Distance Matrix Fast API

GET

https://api.nextbillion.io/distancematrix/json?key={your_api_key}


The Fast version returns the ETAs and distances in real time. The results returned take into account the typical traffic conditions at the time.

Distance Matrix Fast API supports both HTTPS GET and POST methods. The parameters, request URL and response schema are exactly the same for both methods. However, an important difference between these methods is the size of the origins and destinations sets that can be shared in the input. We cover both of them in the sections below.

GET Request

To utilize the Distance Matrix API and obtain estimated times of arrival (ETAs) and distances, users can make a GET request with the following required parameters: key, origins and destinations. Additionally, users can customize their request by including other optional parameters as listed in the table below.

It is recommended to use the GET method when the total number of locations including both origins and destinations is less than 100.

Request Parameters

Loading..

POST Request

The parameters and their properties for the POST method of Distance Matrix Fast service are the same as listed in the Request Parameters section. The key is passed as query parameters and the rest of the parameters should be included in the Request Body. An example of a POST request is added in the Sample Queries - Distance Matrix Fast section below.

We recommend using the POST method, when the total number of locations including both origins and destinations is more than 100.

Response Schema

Loading..

Distance Matrix Flexible API

GET

https://api.nextbillion.io/distancematrix/json?option=flexible&key={your_api_key}


The Flexible version returns the ETAs and distances taking into consideration additional parameters like truck specific routes, specific departure time and the typical traffic conditions at the time, and a preference for the fastest or the shortest route type.

To use the Distance Matrix Flexible API service please set the option parameter to flexible. Please note some request parameters available in the Fast version are not available in the Flexible version and vice-versa.

Distance Matrix Flexible API supports both HTTPS GET and POST methods. The parameters, request URL and response schema are exactly the same for both methods. However, an important difference between these methods is the size of the origins and destinations sets that can be shared in the input. We cover both of them in the sections below.

GET Request

To utilize the Distance Matrix API and obtain estimated times of arrival (ETAs) and distances, users can make a GET request with the following required parameters: key, origins and destinations. Additionally, users can customize their request by including other optional parameters as listed in the table below.

It is recommended to use the GET method when the total number of locations including both origins and destinations is less than 50. Please check API Query Limits section to know more about the limits of Distance Matrix Flexible API.

Request Parameters

Loading..

POST Request

The parameters and their properties for the POST method of Distance Matrix Flexible service are the same as listed in the Request Parameters section. The key and option are passed as query parameters and the rest of the parameters should be included in the Request Body. An example of a POST request is added in the Sample Queries - Distance Matrix Fast section below.

When the total number of locations including both origins and destinations is more than 50, we recommend using the POST method. Please check API Query Limits section to know more about the limits of Distance Matrix Flexible API.

Response Schema

Loading..

API Query Limits

  • For the Distance Matrix Fast version, NextBillion.ai allows a default limit of up to 1000x1000 Origin x Destination set. We can support up to a maximum size of 5000x5000 matrix. For higher limits please check with your NextBillion.ai account manager, sales representative or reach out at [email protected]

  • For the Distance Matrix Flexible version, NextBillion.ai allows a default limit of up to

    1. 50x50 Origin x Destination set i.e. 2500 elements

    2. Total straight line distance of 8000km between all the points in a request.

    For higher limits please check with your NextBillion.ai account manager, sales representative or reach out at [email protected]

  • The HTTPS GET method of the Fast version can handle up to a total of 100 locations and a total of 50 locations for the Flexible version, in a single request. In case of large matrix sizes where the total number of locations is more, using the HTTPS POST method is recommended.

  • Maximum dimensions allowed for truck_size are 5000 cm for length, 5000 cm for width, 1000 cm for height.

  • Maximum weight allowed for truck_weight (including the trailer and shipped goods) is 100,000 kg

  • NextBillion.ai allows a maximum rate limit of 6000 queries per minute or 100 queries/second for continuous requests. Note: We can increase the quota if needed, on request. Contact [email protected] for more details.

API Error Codes

Response CodeDescriptionAdditional Notes
200Normal success case.

Normal success case.

400Input validation failed.

There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request.

401APIKEY not supplied or invalid.

This error occurs when the wrong API key is passed in the request or the key is missing altogether

403APIKEY is valid but does not have access to requested resources.

You might be querying for a geographical region which is not valid for your account, or requesting a service which is not enabled for you.

404Requested host/path not found.

This error occurs when a malformed hostname is used.

413Request entity too large

This error is caused when the length of input request URI or the request body is too large. Please modify the request. Reach out to [email protected] if the issue still persists.

422Could not process the request.

Unroutable coordinates provided in the request, please check API response for more details.

429Too many requests.

QPM limit or distance matrix size quota reached.

500Internal Service error.

There was an internal issue with NextBillion.ai services. You can reach out to [email protected] for an explanation.