Distance Matrix API

Introduction

NextBillion.ai’s Distance Matrix API is a powerful tool for computing 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 offers the following features for customizing computations:

• Scalable Computations: Compute ETAs and distances for 1,000 x 1,000 points, with the ability to increase the limit to 5,000 x 5,000 for high-volume use cases.
• Real-time and Historical Traffic: Generate distance and ETA matrices based on both real-time and historical traffic conditions.
• Customizable Route Preferences: Choose from preferences for avoiding or excluding routes with tolls, highways, left turns, right turns, service roads. Alternatively, always calculate routes with curbside stops, or prefer routes for specific truck types.
• Support for multiple travel modes: Compute routes suitable for various travel modes: walk, bicycle, motorbike, car, and truck.
• Truck-Specific Features: Incorporate truck-specific parameters such as weight, size, axle load distribution, hazardous cargo, and emission classification.
• Optimal Route Selection: Choose between "fastest" and "shortest" route types to obtain corresponding ETAs and distances.

NextBillion.ai’s Distance Matrix API has 2 versions - Fast and Flexible. Each of them is designed for different types of use cases. Let’s dive-deeper into each of them in the following sections.

Distance Matrix Flexible API

The Distance Matrix Flexible API offers ETAs and distances that account for real-time traffic conditions. It also supports truck-specific features such as truck weight, size, hazardous cargo, and emission classification. Users can set a specific departure time to simulate typical traffic conditions and choose between the 'fastest' or 'shortest' route type, or routes that always arrive curbside. These features prove highly beneficial in addressing business challenges requiring accuracy, customizations and support for advanced constraints across diverse industries, including NEMT, ride-hailing, logistics, and waste management.

In order to use the Distance Matrix Flexible API service, set the option parameter to “flexible”. The Flexible endpoint provides support for both HTTPS GET and POST methods. The parameters, request endpoint and response schema are the same for both methods.

Request Parameters

POST Request

The parameters and their properties for the POST method of Distance Matrix Flexible API are the same as listed in the Request Parameter section. The key and option are passed as Query Parameters and the rest of the parameters should be included in the Request Body.

Response Schema

Distance Matrix Fast API

The Distance Matrix Fast API is designed for high-volume calculations, prioritizing low latency and rapid responses. The Fast version takes into account the usual traffic conditions at the time of making the request to calculate the ETAs and distances. It supports common routing capabilities like - support for car and truck modes, avoid tolls & highways and curbside stop routing - essential for typical applications.

Request Parameters

POST Request

The parameters and their properties for the POST method of Distance Matrix Fast service are the same as listed in the Request Parameter section. The key is passed as query parameters and the rest of the parameters should be included in the Request Body.

Response Schema

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]

• It is not recommended to provide more than a total of 100 locations across origins and destinations inputs 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_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

• When using avoid=bbox, the maximum perimeter allowed for the bounding box is 500 kilometers.

• 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