• Optimization
  • Navigation
  • Tracking
  • Maps
  • Places

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

GET

https://api.nextbillion.io/navigation/json?key={your_api_key}


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

Loading..

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.

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

Response Schema

Loading..

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

1https://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 {
5 "geometry": "svr}_A`ebp`F~p@jr@njAt_An|BjvBjj@w~@fhAl_A",
6 "distance": 851.2,
7 "duration": 213.8,
8 "start_location": {
9 "latitude": 34.056058,
10 "longitude": -118.244961
11 },
12 "end_location": {
13 "latitude": 34.050176,
14 "longitude": -118.248739
15 },
16 "legs": [
17 {
18 "distance": {

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

navigation fast example 1

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

1curl --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 {
5 "geometry": "svr}_A`ebp`F~p@jr@bx@to@ngBo}C{RxXfiD|{Cij@xdA|o@~h@",
6 "distance": 1211.6,
7 "duration": 296.7,
8 "start_location": {
9 "latitude": 34.056058,
10 "longitude": -118.244961
11 },
12 "end_location": {
13 "latitude": 34.050176,
14 "longitude": -118.248739
15 },
16 "legs": [
17 {
18 "distance": {

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

navigation fast example 2

POST Request Example

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

1curl --location --request POST 'https://api.nextbillion.io/navigation/json?key=<youir_api_key>'
2--header 'Content-Type: application/json'
3--data-raw '{
4 "waypoints":"34.05264456,-118.24405323",
5 "origin":"34.05605379,-118.24495386",
6 "destination":"34.05023939,-118.24885017",
7 "overview":"simplified",
8 "mode":"car"
9}'
10
GET

https://api.nextbillion.io/navigation?option=flexible&key={your_api_key}


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

Loading..

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

Loading..

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

1https://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 {
5 "geometry": "kqznE~uupUSQo@o@S_@`@k@\\g@JMJOX]PSFKJK^a@nAwANOd@i@^g@d@o@TY^e@f@k@LQTWLM\\_@DGHKd@o@f@m@X]PUNS`B{BPHDBF@NDz@V\\Lh@RXLn@VLHNHHFv@j@RPHH\\\\",
6 "distance": 956.98,
7 "duration": 208.356,
8 "start_location": {
9 "latitude": 34.05606,
10 "longitude": -118.24496
11 },
12 "end_location": {
13 "latitude": 34.05038,
14 "longitude": -118.2409
15 },
16 "legs": [
17 {
18 "distance": {

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

navigation flexi example 1

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

1curl --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 {
5 "geometry": "ofm~zAfyre`ElGT~UXD?`Z?to@_@na@p@lK@hPBfn@iAzoBIF?pw@WjZKl[KrMFzz@b@xJFD?n[Pl~@?@?nQ?B?~^EB?zfAP??te@Kxa@CF?nCA??xa@?@?bIIF?fJK@?tIM@?pVW@?vEOF?tNk@F?|DvCBBjVSlEEp\\YvSND?jU\\jBHB?lEjAbEn@fDv@lDfCxAjDz@xFt@~Od@fStA~aA|@`e@t@|ZHtJ?@Fzl@]|jAgFpm@aLfrAgDv`@yOzdBkKfjAAJc@hF{Dre@?BuIr|@oL`mA{Ftl@ADsEfj@uI`|@aOxyAc]bmD?BoCj\\u@vI_D~\\a@~HAHcAtNAJ{BtV_AdKuCp\\AF{Frm@wEpd@cEt[?BkEd]_D|TuEdWiHx^iHv\\eE~PqDzNkC|K{D|MmFtQuH~TyHbTs@dBoEtKCF[t@sGfOSb@cJhRiNpYA@ku@|wAeBdD{y@x~Aoj@tgAEHgGlLswAdqCcTxa@oQp]AB_GfLcTf`@yIbPA@sHhNCB{@~Bk[fl@cm@thAYd@CDiRv[ySj_@yOt]CFyYpr@gGbQwEbPiFhRCJYdA{DlPoAhGAByAdH}ClRyCnUoAhKAFmA|Om@zL}@xR?HuAz]{NkEcEiAqNsEcCeFsAo@aa@gNiOoFCAo]gKw_@gKwg@qL}k@}MCAsm@wLybBwXiDo@CAcu@aNEAs_A}P??}e@uIwk@eKEA{MgCC?s_AoQyo@kN_y@{SgOuDEA{n@gQ}IaC{UiGCAoJkCsl@gPqd@eRo\\qM}LeGcKaHqN_KqDqDmEgEsEoFsKcNcL_N{DgFcAqAs@y@oBiALcLDgE?G?wF?_E?a\\@_QHqz@?IAch@AsI?oDIoT?KKaXCkHDsUDk]?AQecAQ_dAEgc@?KByo@Acn@B{o@AmTF}W?II_Z?K?sV?EBcU?eB?E@eS@qO@gH?GJsV?KEqVAyOAk]?K@yJ???we@?I?uk@??Ici@Iuj@?mg@?MXyj@Emr@?CC{_@?Ml@mkCX{qATuHd@}Gh@yDx@eGfC_KnBuFrA}B@AnAyBbFsHjKmMbNqMzHsK`F}KxCaKlB}Jt@iI@Gl@{JH{LMkBcByVc@{GqAmN]sGOiFEeMGoTb@sqA??`@cdB?KCgm@A{o@Nsf@?K@kERcn@Akm@?KCen@?IOaYm@gMi@kGaBoKeCmK}Nai@ACmJ_[CGsIwYqEyPgBwH??S{@yCeOaBsJy@kGi@kGq@aVE_TwPg@",
6 "distance": 11037.742,
7 "duration": 1043.4,
8 "start_location": {
9 "latitude": 48.2254,
10 "longitude": -101.296036
11 },
12 "end_location": {
13 "latitude": 48.240271,
14 "longitude": -101.296066
15 },
16 "legs": [
17 {
18 "distance": {

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

1curl --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 {
5 "geometry": "qnkn}@ng`m~EqDBC?yO@cE@iG@qLBE?iODE?@zBIvPHdPGtg@ztA?D?h]CB?i@qQLkb@AuE?EAgJCmB?IJ_C?AkBuBs@k@}@o@KKq@i@m@s@GMiA}AqMoXAA_EkI",
6 "distance": 660.833,
7 "duration": 127.174,
8 "start_location": {
9 "latitude": 32.758009,
10 "longitude": -117.146248
11 },
12 "end_location": {
13 "latitude": 32.757771,
14 "longitude": -117.145463
15 },
16 "legs": [
17 {
18 "distance": {

POST Request Example

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

1curl --location --request POST 'https://api.nextbillion.io/navigation/json?key=<your_api_key>&option=flexible' \
2--header 'Content-Type: application/json' \
3--data-raw '{
4 "origin":"34.05605379,-118.24495386",
5 "destination":"34.05037935,-118.24087972",
6 "departure_time":1688389200,
7 "mode":"truck"
8}'

API Query Limits

  • Maximum number of waypoints allowed in a GET request is 50 and in a POST request is 200.

  • 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

Response CodeDescriptionAdditional Notes
200Normal success case.
Normal success case.
400Input validation failed.
There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request.
401APIKEY not supplied or invalid.
This error occurs when the wrong API key is passed in the request or the key is missing altogether
403APIKEY is valid but does not have access to requested resources.
You might be querying for a geographical region which is not valid for your account, or requesting a service which is not enabled for you.
404Requested host/path not found.
This error occurs when there is a malformed host name used
422Could not process the request.
Valid route could not be generated for the given parameters.
429Too many requests.
QPM or API request count quota reached
500Internal Service error.
There was an internal issue with NextBillion.ai services. You can reach out to [email protected] for an explanation.