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.
The Distance Matrix API has 2 versions - Fast and Flexible. We will be talking about both these services below.
Distance Matrix Fast API
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, destinations and option. The 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 otherwise the requests can result in error due to URL length exceeding limitations.
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.
In case of a large number of locations, we recommend using the POST method to avoid exceeding the URL length limitations of the GET method which could lead to error states.
Response Schema
Loading..Distance Matrix Flexible API
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 100 otherwise the requests can result in error due to URL length exceeding limitations.
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.
In case of a large number of locations, we recommend using the POST method to avoid exceeding the URL length limitations of the GET method which could lead to error states.
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
-
50x50 Origin x Destination set i.e. 2500 elements
-
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]
-
-
It is not recommended to provide more than a total of 100 locations across
originsanddestinationsinputs when using the HTTP GET method, lest the maximum URL length restrictions will cause the request to return an error. In case of huge matrix sizes, using the HTTP POST method is recommended. -
Maximum dimensions allowed for
truck_sizeare 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.
