Directions API

Introduction

NextBillion.ai’s Directions API is a service that computes a route between two places offering a comprehensive suite of features to optimize your navigation experience:

• Optimal Routing: Get the best driving directions based on real-time traffic conditions, with options for the fastest or shortest routes.
• Advanced Trip Planning: Plan your journeys in advance by setting a departure time to receive optimal routes and estimated times of arrival (ETAs).
• Diverse Driving Modes: Obtain safe and legal directions tailored for various modes of transport, including walking, cycling, motorbiking, cars, and trucks.
• Route Customization: Avoid or exclude routes with specific maneuvers or road objects, such as tolls, right/left turns, U-turns, highways or service roads.
• Truck-Specific Routing: Cater to unique truck routing needs by considering factors like truck weight and dimensions, weight distribution per axle, hazardous cargo, emission classification, layover regulations, and many more specialized features.

NextBillion.ai’s Directions API is available in two versions, designed to suit a wide range of business needs. The Flexible version provides the most advanced set of features, customization options, and routing capabilities. It is ideal for complex or specialized use cases where precision and tailored solutions matter most. The Fast version, on the other hand, is optimized for speed and efficiency. With a streamlined feature set, it delivers rapid results and is best suited for high-volume, standard routing scenarios where quick responses are a priority.

We will cover both these endpoints in depth in the following sections.

Directions Flexible API

The Directions Flexible API is designed for scenarios where precision, customization, and advanced routing constraints are critical. The routes are calculated based on live and historical traffic conditions. It also supports comprehensive truck-specific features (such as truck size, hazardous cargo, and emissions class), and advanced routing preferences like avoiding tolls, sharp turns, or restricted roads. With the ability to optimize for the fastest or shortest path, provide alternative routes, and handle multiple travel modes—from walking and biking to motorbikes, cars, and trucks—the Flexible endpoint offers a high degree of versatility.

To use the Directions Flexible API service set the option parameter to “flexible”. The Flexible endpoint supports both HTTPS GET and POST methods. Request URL, parameters and response schemas are the same for both methods.

Request Parameters

POST Request

The parameters and their properties for the Directions Flexible POST version 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

Directions Fast API

The Directions Fast API is designed to serve high-volume, real-time routing scenarios and prioritizing low latency. It offers essential routing features for common use cases. The Fast endpoint considers historical traffic for timely routing and avoids any delays under usual circumstances. It supports car and truck modes with default truck routing parameters. Additional options include avoiding highways, tolls, and ferries, providing alternative routes, and supporting intervening waypoints. It also offers curbside approach routing, ideal for ride-hailing, delivery, or fleet applications needing precise pickup/drop-off.

Directions Fast API service can take input using both HTTPS GET and POST requests. Request URL, parameters and response schema are exactly the same for both methods.

Request Parameters

POST Request

The parameters and their properties for the Directions Fast POST version are the same as listed in the Request Parameter section. The key is passed as a request parameter and the rest of the parameters should be included in the Request Body.

Response Schema

API Query Limits

• Following are the maximum number of waypoints allowed in a single request for both Fast and Flexible methods:
  • 50 when using HTTPS GET
  • 200 when using HTTPS POST
• 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