Navigation API

Introduction

NextBillion.ai offers a Navigation API that calculates routes between two locations and provides precise turn-by-turn directions for smooth navigation. This API can also serve as an input for your navigation application, enabling interactive route visualization. Alternatively, for a complete turn-by-turn navigation experience, you can directly utilize NextBillion.ai’s Navigation SDK.

Navigation API has two versions, both of which can be utilized for different use cases. First is the Flexible version, which offers an advanced feature set - including truck specific features and traffic aware routing - to meet complex as well as customized navigation requirements. The second version is called the Fast, which combines low-latency and efficiency to solve high-volume, standard navigation requirements.

Let’s go through each of these versions one-by-one in the following sections.

Navigation Flexible API

The Navigation Flexible API is designed for scenarios demanding precision, customization, and advanced navigation constraints. It calculates routes using live and historical traffic data, and supports comprehensive truck-specific parameters (including size, weight, and hazardous cargo). The API also allows for powerful routing preferences such as avoiding tolls, sharp turns, or restricted roads.

With its versatility, the Flexible endpoint can optimize for the fastest or shortest path, provide alternative routes, and handle multiple travel modes, from walking and biking to motorbikes, cars, and trucks.

To access the Navigation Flexible API, set the option parameter to "flexible". This endpoint supports both HTTPS GET and POST methods, with identical request URL, parameters, and response schemas for both

Request Parameters

POST Request

The parameters and their properties for the Navigation Flexible POST method are the same as listed in the Request Parameter section. The key and option parameters are passed as a request parameter 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 - Navigation Flexible section below.

Response Schema

Sample Queries-Navigation Flexible

GET Request Example 1

Let’s create a basic navigation flexible request for a trip

• being made by a truck

• between a given origin and a destination

• at a specific departure_time

Request

1
https://api.nextbillion.io/navigation/json?departure_time=1688389200&option=flexible&origin=34.05605379,-118.24495386&destination=34.05037935,-118.24087972&key=<your_api_key>&mode=truck

Response

1
{
2
    "status": "Ok",
3
    "routes":   [...] 
4
}

When represented on a map the above response would look similar to below illustration

GET Request Example 2

In the next example, we will create a navigation flexible request for a trip where we want a truck to avoid hazmat roads. We configure:

• an origin and a destination
• mode as truck
• hazmat_type as “circumstantial”

Request

1
curl --location 'https://api.nextbillion.io/navigation/json?key=<your_api_key>&origin=48.22539980,-101.29602541&destination=48.24027183,-101.29608570&mode=truck&option=flexible&hazmat_type=circumstantial'

Response

1
{
2
    "status": "Ok",
3
    "routes":   [...] 
4
}

GET Request Example 3

Next we will create a navigation flexible request for a trip where we want to avoid sharp turns which can be potentially dangerous for a truck to complete. We configure:

• an origin and a destination
• mode as truck
• avoid option set to “sharp_turn”

Request

1
curl --location 'https://api.nextbillion.io/navigation/json?key=<your_api_key>&origin=32.75800890,-117.14624755&destination=32.75777097,-117.14546261&mode=truck&option=flexible&avoid=sharp_turn'

Response

1
{
2
    "status": "Ok",
3
    "routes":   [...] 
4
}

POST Request Example

Following is a Navigation Flexible POST request configured for the same scenario from the example above:

1
curl --location --request POST 'https://api.nextbillion.io/navigation/json?key=<your_api_key>&option=flexible' --header 'Content-Type: application/json' --data-raw '{...}'

Navigation Fast API

The Navigation Fast API is built for real-time, high-volume navigation, prioritizing low-latency. It provides core navigation features for common use cases.

The Fast endpoint accounts for historical traffic to ensure timely routing and prevent delays under normal conditions. It supports both car and truck modes, with default truck routing parameters included. Users can also choose to avoid highways, tolls, and ferries, request alternative routes, and utilize intervening waypoints. Additionally, it offers curbside approach routing, which is ideal for precise pickup/drop-off needs in ride-hailing, delivery, or fleet applications.

Request Parameters

POST Request

The parameters and their properties for the Navigation Fast POST method are the same as listed in the Request Parameters section. The key is passed as a request parameter 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 - Navigation Fast section below

Response Schema

Sample Queries-Navigation Fast

GET Request Example 1

Let’s create a basic navigation request for a trip

• being made by a car
• between a given origin and a destination
• with a simplified overview of the route geometry

Request

1
https://api.nextbillion.io/navigation/json?key={your_api_key}&origin=34.05605379,-118.24495386&destination=34.05023939,-118.24885017&mode=car&overview=simplified

Response

1
{
2
    "status": "Ok",
3
    "routes":   [...] 
4
}

Here is a visual representation of how the above response would look like on a map.

GET Request Example 2

Taking a step further for the same trip, let’s customize and

• add a waypoints

• request to avoid highways and tolls in the route

Request

1
curl --location 'https://api.nextbillion.io/navigation/json?waypoints=34.05264456,-118.24405323&overview=simplified&origin=34.05605379,-118.24495386&destination=34.05023939,-118.24885017&key=<your_api_key>&mode=car&avoid=highway|toll'

Response

1
{
2
    "status": "Ok",
3
    "routes":   [...] 
4
}

Following is a visual representation of how the above response would look like on a map.

POST Request Example

Following is a Navigation Fast POST request configured for the same scenario from Example 2 above:

1
curl --location --request POST 'https://api.nextbillion.io/navigation/json?key=<youir_api_key>' 
2
--header 'Content-Type: application/json' 
3
--data-raw '{...}'

API Query Limits

• Maximum number of waypoints allowed in a GET request is 50, whether it is the Fast API or the Flexible API. However, when using the HTTPS POST method, there is a limit of 200 waypoints when using the Flexible API and no limits when using the Fast API.
• 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.
• At least one of the combinations from (origin + destination) or (original_shape + original_shape_type) should be provided to create a valid request.
• 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