Navigation API

Introduction

NextBillion.ai’s Navigation API is a service that computes a route between 2 places, and also returns detailed turn by turn instructions for the route. The Navigation API can be used as an input into your Navigation app. Alternatively, you can directly use NextBillion.ai’s Navigation SDK for a complete turn-by-turn navigation experience.

The Navigation API has 2 versions, both of which can be uniquely utilized for different use cases. First one is the Fast version, which would return the route and related information in real time. Second is the Flexible version, which offers truck routing and time-based navigation features in addition to those available in the Fast version. We will be talking about both these services below.

Also check out NextBillion's Road Editor API for easy manipulation and custom updates to road network data, enhancing the utility of Navigation API response in meeting your business needs

Navigation Fast API

The Navigation Fast API gets the directions and route guidance in real time for trips starting at current time. The routes returned through this service have the traffic conditions factored in to avoid any delays under usual circumstances.

Navigation 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. However, an important difference between these two input methods is in the maximum number of waypoints that can be added to the input. We will cover them below.

GET Request

Use the Navigation API GET request to obtain the directions and route information for a trip using a basic request with an origin and destination or by providing a geometry. Users can further customize the request using several other additional parameters available in the NextBillion.ai’s Navigation API.

Please note that the maximum number of waypoints allowed in a GET request is 50.

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 '{...}'

Navigation Flexible API

The Navigation Flexible API offers customizable features for advanced navigation experience. It serves requests for truck specific routing, time based routing, allows choosing between fastest and shortest route types and also offers to return segment-wise speed limits of the route suggested. The traffic conditions are also factored in by the service to avoid delays under usual circumstances.

Navigation Flexible API service can be used by setting the option parameter as flexible. Please note some request and response parameters available in the Fast version are not available in the Flexible version and vice-versa.

Navigation Flexible 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. However, an important difference between these two input methods is in the maximum number of waypoints that can be added to the input. We will cover them below.

GET Request

Use the Navigation API GET request to obtain the directions and route information for a trip using a basic request with an origin and destination or by providing a geometry. Users can further customize the request using several other additional parameters available in the NextBillion.ai’s Navigation API.

Please note that the maximum number of waypoints allowed in a GET request is 50.

Request Parameters

POST Request

The parameters and their properties for the Navigation Flexible POST method are the same as listed in the Request Parameters 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.

Please note that the maximum number of waypoints allowed in a POST request is 200.

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 '{...}'

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.
• 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