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.
Navigation Fast API
Request URL: https://api.nextbillion.io/navigation/json?{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
originand adestination -
with a simplified
overviewof the route geometry
Request
https://api.nextbillion.io/navigation/json?key=<your_api_key>&origin=34.05605379,-118.24495386&destination=34.05023939,-118.24885017&mode=car&overview=simplifiedResponse
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": {
19 "value": 851
20 },
21 "duration": {
22 "value": 213
23 },
24 "start_location": {
25 "latitude": 34.056058,
26 "longitude": -118.244961
27 },
28 "end_location": {
29 "latitude": 34.050176,
30 "longitude": -118.248739
31 },
32 "steps": [
33 {
34 "geometry": "svr}_A`ebp`FlDxCrFjGVzBhE`EtNxMdMlLlHxGfBpAhDj@dBnAxQ~PbPlN|@t@lOhM|g@ff@zKjKrD~DnUvSjNnM`CxBxBrBhS`R",
35 "start_location": {
36 "latitude": 34.056058,
37 "longitude": -118.244961
38 },
39 "end_location": {
40 "latitude": 34.052042,
41 "longitude": -118.248728
42 },
43 "distance": {
44 "value": 568
45 },
46 "duration": {
47 "value": 122
48 },
49 "maneuver": {
50 "instruction": "Head southwest on N Hill St",
51 "voice_instruction": [],
52 "bearing_before": 0,
53 "bearing_after": 216,
54 "coordinate": {
55 "latitude": 34.056058,
56 "longitude": -118.244961
57 },
58 "maneuver_type": "depart"
59 },
60 "name": "N Hill St",
61 "intersections": [
62 {
63 "location": {
64 "latitude": 34.056058,
65 "longitude": -118.244961
66 },
67 "bearings": [216],
68 "classes": [],
69 "entry": [],
70 "intersection_in": 0,
71 "intersection_out": 0,
72 "lanes": []
73 },
74 {
75 "location": {
76 "latitude": 34.054919,
77 "longitude": -118.246027
78 },
79 "bearings": [30, 135, 225],
80 "classes": [],
81 "entry": [],
82 "intersection_in": 0,
83 "intersection_out": 2,
84 "lanes": []
85 },
86 {
87 "location": {
88 "latitude": 34.054344,
89 "longitude": -118.246562
90 },
91 "bearings": [30, 135, 210, 315],
92 "classes": [],
93 "entry": [],
94 "intersection_in": 0,
95 "intersection_out": 2,
96 "lanes": []
97 },
98 {
99 "location": {
100 "latitude": 34.053395,
101 "longitude": -118.247446
102 },
103 "bearings": [45, 225, 300],
104 "classes": [],
105 "entry": [],
106 "intersection_in": 0,
107 "intersection_out": 1,
108 "lanes": []
109 },
110 {
111 "location": {
112 "latitude": 34.053189,
113 "longitude": -118.247644
114 },
115 "bearings": [45, 225, 315],
116 "classes": [],
117 "entry": [],
118 "intersection_in": 0,
119 "intersection_out": 1,
120 "lanes": []
121 },
122 {
123 "location": {
124 "latitude": 34.053099,
125 "longitude": -118.24774
126 },
127 "bearings": [45, 135, 210, 315],
128 "classes": [],
129 "entry": [],
130 "intersection_in": 0,
131 "intersection_out": 2,
132 "lanes": []
133 },
134 {
135 "location": {
136 "latitude": 34.052428,
137 "longitude": -118.248365
138 },
139 "bearings": [45, 135, 225],
140 "classes": [],
141 "entry": [],
142 "intersection_in": 0,
143 "intersection_out": 2,
144 "lanes": []
145 }
146 ],
147 "road_shield_type": {}
148 },
149 {
150 "geometry": "s{j}_Anpip`FlEeHdE{G^m@pC{E|IsOfMwS",
151 "start_location": {
152 "latitude": 34.052042,
153 "longitude": -118.248728
154 },
155 "end_location": {
156 "latitude": 34.051348,
157 "longitude": -118.247708
158 },
159 "distance": {
160 "value": 121
161 },
162 "duration": {
163 "value": 46
164 },
165 "maneuver": {
166 "instruction": "Turn left",
167 "voice_instruction": [
168 {
169 "distance_along_geometry": 560,
170 "unit": "meters",
171 "instruction": "In 560 meters, Turn left"
172 },
173 {
174 "distance_along_geometry": 200,
175 "unit": "meters",
176 "instruction": "In 200 meters, Turn left"
177 },
178 {
179 "distance_along_geometry": 50,
180 "unit": "meters",
181 "instruction": "Turn left"
182 }
183 ],
184 "bearing_before": 216,
185 "bearing_after": 129,
186 "coordinate": {
187 "latitude": 34.052042,
188 "longitude": -118.248728
189 },
190 "maneuver_type": "turn",
191 "modifier": "left"
192 },
193 "name": "",
194 "intersections": [
195 {
196 "location": {
197 "latitude": 34.052042,
198 "longitude": -118.248728
199 },
200 "bearings": [45, 135, 225],
201 "classes": [],
202 "entry": [],
203 "intersection_in": 0,
204 "intersection_out": 1,
205 "lanes": []
206 },
207 {
208 "location": {
209 "latitude": 34.051939,
210 "longitude": -118.248581
211 },
212 "bearings": [45, 135, 210, 315],
213 "classes": [],
214 "entry": [],
215 "intersection_in": 3,
216 "intersection_out": 1,
217 "lanes": []
218 },
219 {
220 "location": {
221 "latitude": 34.05184,
222 "longitude": -118.248439
223 },
224 "bearings": [30, 135, 210, 315],
225 "classes": [],
226 "entry": [],
227 "intersection_in": 3,
228 "intersection_out": 1,
229 "lanes": []
230 },
231 {
232 "location": {
233 "latitude": 34.051751,
234 "longitude": -118.248306
235 },
236 "bearings": [30, 135, 210, 315],
237 "classes": [],
238 "entry": [],
239 "intersection_in": 3,
240 "intersection_out": 1,
241 "lanes": []
242 }
243 ],
244 "road_shield_type": {}
245 },
246 {
247 "geometry": "gpi}_Avpgp`F`O|MfGnFfKpJtc@l]",
248 "start_location": {
249 "latitude": 34.051348,
250 "longitude": -118.247708
251 },
252 "end_location": {
253 "latitude": 34.050176,
254 "longitude": -118.248739
255 },
256 "distance": {
257 "value": 161
258 },
259 "duration": {
260 "value": 45
261 },
262 "maneuver": {
263 "instruction": "Turn right onto S Broadway, then you will arrive",
264 "voice_instruction": [
265 {
266 "distance_along_geometry": 50,
267 "unit": "meters",
268 "instruction": "Turn right onto S Broadway, then you will arrive"
269 }
270 ],
271 "bearing_before": 129,
272 "bearing_after": 216,
273 "coordinate": {
274 "latitude": 34.051348,
275 "longitude": -118.247708
276 },
277 "maneuver_type": "end of road",
278 "modifier": "right"
279 },
280 "name": "S Broadway",
281 "intersections": [
282 {
283 "location": {
284 "latitude": 34.051348,
285 "longitude": -118.247708
286 },
287 "bearings": [45, 225, 315],
288 "classes": [],
289 "entry": [],
290 "intersection_in": 2,
291 "intersection_out": 1,
292 "lanes": []
293 },
294 {
295 "location": {
296 "latitude": 34.050959,
297 "longitude": -118.248067
298 },
299 "bearings": [30, 120, 225, 315],
300 "classes": [],
301 "entry": [],
302 "intersection_in": 0,
303 "intersection_out": 2,
304 "lanes": [
305 {
306 "indications": ["none"],
307 "valid": true
308 },
309 {
310 "indications": ["right"],
311 "valid": false
312 }
313 ]
314 }
315 ],
316 "road_shield_type": {}
317 },
318 {
319 "geometry": "_gg}_Adqip`F",
320 "start_location": {
321 "latitude": 34.050176,
322 "longitude": -118.248739
323 },
324 "end_location": {
325 "latitude": 34.050176,
326 "longitude": -118.248739
327 },
328 "distance": {
329 "value": 0
330 },
331 "duration": {
332 "value": 0
333 },
334 "maneuver": {
335 "instruction": "You have arrived at S Broadway, on the right",
336 "voice_instruction": [
337 {
338 "distance_along_geometry": 50,
339 "unit": "meters",
340 "instruction": "You have arrived at S Broadway, on the right"
341 }
342 ],
343 "bearing_before": 215,
344 "bearing_after": 0,
345 "coordinate": {
346 "latitude": 34.050176,
347 "longitude": -118.248739
348 },
349 "maneuver_type": "arrive",
350 "modifier": "right"
351 },
352 "name": "S Broadway",
353 "intersections": [
354 {
355 "location": {
356 "latitude": 34.050176,
357 "longitude": -118.248739
358 },
359 "bearings": [35],
360 "classes": [],
361 "entry": [],
362 "intersection_in": 0,
363 "intersection_out": 0,
364 "lanes": []
365 }
366 ],
367 "road_shield_type": {}
368 }
369 ]
370 }
371 ]
372 }
373 ],
374 "country_code": "US"
375}
376Here 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
avoidhighways and tolls in the route
Request
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=carResponse
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": {
19 "value": 542
20 },
21 "duration": {
22 "value": 120
23 },
24 "start_location": {
25 "latitude": 34.056058,
26 "longitude": -118.244961
27 },
28 "end_location": {
29 "latitude": 34.052672,
30 "longitude": -118.244026
31 },
32 "steps": [
33 {
34 "geometry": "svr}_A`ebp`FlDxCrFjGVzBhE`EtNxMdMlLlHxGfBpAhDj@dBnAxQ~PbPlN",
35 "start_location": {
36 "latitude": 34.056058,
37 "longitude": -118.244961
38 },
39 "end_location": {
40 "latitude": 34.054344,
41 "longitude": -118.246562
42 },
43 "distance": {
44 "value": 243
45 },
46 "duration": {
47 "value": 37
48 },
49 "maneuver": {
50 "instruction": "Head southwest on N Hill St",
51 "voice_instruction": [],
52 "bearing_before": 0,
53 "bearing_after": 216,
54 "coordinate": {
55 "latitude": 34.056058,
56 "longitude": -118.244961
57 },
58 "maneuver_type": "depart"
59 },
60 "name": "N Hill St",
61 "intersections": [
62 {
63 "location": {
64 "latitude": 34.056058,
65 "longitude": -118.244961
66 },
67 "bearings": [216],
68 "classes": [],
69 "entry": [],
70 "intersection_in": 0,
71 "intersection_out": 0,
72 "lanes": []
73 },
74 {
75 "location": {
76 "latitude": 34.054919,
77 "longitude": -118.246027
78 },
79 "bearings": [30, 135, 225],
80 "classes": [],
81 "entry": [],
82 "intersection_in": 0,
83 "intersection_out": 2,
84 "lanes": []
85 }
86 ],
87 "road_shield_type": {}
88 },
89 {
90 "geometry": "oko}_Abiep`FxFcK~FyJ~C_GpKyRpGyN`FkItEgIjDkGvB{DdHqLrIuOrDmGnCkErCiDbCeC^o@",
91 "start_location": {
92 "latitude": 34.054344,
93 "longitude": -118.246562
94 },
95 "end_location": {
96 "latitude": 34.052672,
97 "longitude": -118.244026
98 },
99 "distance": {
100 "value": 299
101 },
102 "duration": {
103 "value": 83
104 },
105 "maneuver": {
106 "instruction": "Turn left onto W 1st St",
107 "voice_instruction": [
108 {
109 "distance_along_geometry": 200,
110 "unit": "meters",
111 "instruction": "In 200 meters, Turn left onto W 1st St"
112 },
113 {
114 "distance_along_geometry": 50,
115 "unit": "meters",
116 "instruction": "Turn left onto W 1st St"
117 }
118 ],
119 "bearing_before": 216,
120 "bearing_after": 127,
121 "coordinate": {
122 "latitude": 34.054344,
123 "longitude": -118.246562
124 },
125 "maneuver_type": "turn",
126 "modifier": "left"
127 },
128 "name": "W 1st St",
129 "intersections": [
130 {
131 "location": {
132 "latitude": 34.054344,
133 "longitude": -118.246562
134 },
135 "bearings": [30, 135, 210, 315],
136 "classes": [],
137 "entry": [],
138 "intersection_in": 0,
139 "intersection_out": 1,
140 "lanes": []
141 },
142 {
143 "location": {
144 "latitude": 34.053673,
145 "longitude": -118.245481
146 },
147 "bearings": [45, 135, 225, 300],
148 "classes": [],
149 "entry": [],
150 "intersection_in": 3,
151 "intersection_out": 1,
152 "lanes": [
153 {
154 "indications": ["left"],
155 "valid": false
156 },
157 {
158 "indications": ["none"],
159 "valid": true
160 },
161 {
162 "indications": ["none"],
163 "valid": true
164 },
165 {
166 "indications": ["none"],
167 "valid": true
168 }
169 ]
170 },
171 {
172 "location": {
173 "latitude": 34.05299,
174 "longitude": -118.244439
175 },
176 "bearings": [45, 135, 210, 315],
177 "classes": [],
178 "entry": [],
179 "intersection_in": 3,
180 "intersection_out": 1,
181 "lanes": []
182 }
183 ],
184 "road_shield_type": {}
185 },
186 {
187 "geometry": "_cl}_Arj`p`F",
188 "start_location": {
189 "latitude": 34.052672,
190 "longitude": -118.244026
191 },
192 "end_location": {
193 "latitude": 34.052672,
194 "longitude": -118.244026
195 },
196 "distance": {
197 "value": 0
198 },
199 "duration": {
200 "value": 0
201 },
202 "maneuver": {
203 "instruction": "You have arrived at W 1st St",
204 "voice_instruction": [
205 {
206 "distance_along_geometry": 200,
207 "unit": "meters",
208 "instruction": "In 200 meters, You will arrive"
209 },
210 {
211 "distance_along_geometry": 50,
212 "unit": "meters",
213 "instruction": "You have arrived at W 1st St"
214 }
215 ],
216 "bearing_before": 129,
217 "bearing_after": 0,
218 "coordinate": {
219 "latitude": 34.052672,
220 "longitude": -118.244026
221 },
222 "maneuver_type": "arrive"
223 },
224 "name": "W 1st St",
225 "intersections": [
226 {
227 "location": {
228 "latitude": 34.052672,
229 "longitude": -118.244026
230 },
231 "bearings": [309],
232 "classes": [],
233 "entry": [],
234 "intersection_in": 0,
235 "intersection_out": 0,
236 "lanes": []
237 }
238 ],
239 "road_shield_type": {}
240 }
241 ]
242 },
243 {
244 "distance": {
245 "value": 669
246 },
247 "duration": {
248 "value": 176
249 },
250 "start_location": {
251 "latitude": 34.052672,
252 "longitude": -118.244026
253 },
254 "end_location": {
255 "latitude": 34.050176,
256 "longitude": -118.248739
257 },
258 "steps": [
259 {
260 "geometry": "_cl}_Arj`p`F_@n@cCdCsChDoCjEsDlG",
261 "start_location": {
262 "latitude": 34.052672,
263 "longitude": -118.244026
264 },
265 "end_location": {
266 "latitude": 34.05299,
267 "longitude": -118.244439
268 },
269 "distance": {
270 "value": 52
271 },
272 "duration": {
273 "value": 16
274 },
275 "maneuver": {
276 "instruction": "Head northwest on W 1st St, then use any lane to turn left onto S Spring St",
277 "voice_instruction": [],
278 "bearing_before": 0,
279 "bearing_after": 309,
280 "coordinate": {
281 "latitude": 34.052672,
282 "longitude": -118.244026
283 },
284 "maneuver_type": "depart"
285 },
286 "name": "W 1st St",
287 "intersections": [
288 {
289 "location": {
290 "latitude": 34.052672,
291 "longitude": -118.244026
292 },
293 "bearings": [309],
294 "classes": [],
295 "entry": [],
296 "intersection_in": 0,
297 "intersection_out": 0,
298 "lanes": []
299 }
300 ],
301 "road_shield_type": {}
302 },
303 {
304 "geometry": "{vl}_Aldap`Fl@h@fB|AvPbN|HpHdSzOdHfHzGtGdH|HnMvLvAjAtO|NtGfGdIdH~BpBxAnArAjAjC|BrBfB`FjErCbCnGrF",
305 "start_location": {
306 "latitude": 34.05299,
307 "longitude": -118.244439
308 },
309 "end_location": {
310 "latitude": 34.050266,
311 "longitude": -118.24695
312 },
313 "distance": {
314 "value": 381
315 },
316 "duration": {
317 "value": 78
318 },
319 "maneuver": {
320 "instruction": "Use any lane to turn left onto S Spring St",
321 "voice_instruction": [],
322 "bearing_before": 307,
323 "bearing_after": 215,
324 "coordinate": {
325 "latitude": 34.05299,
326 "longitude": -118.244439
327 },
328 "maneuver_type": "turn",
329 "modifier": "left"
330 },
331 "name": "S Spring St",
332 "intersections": [
333 {
334 "location": {
335 "latitude": 34.05299,
336 "longitude": -118.244439
337 },
338 "bearings": [45, 135, 210, 315],
339 "classes": [],
340 "entry": [],
341 "intersection_in": 1,
342 "intersection_out": 2,
343 "lanes": [
344 {
345 "indications": ["left"],
346 "valid": true
347 },
348 {
349 "indications": ["none"],
350 "valid": true
351 },
352 {
353 "indications": ["none"],
354 "valid": true
355 }
356 ]
357 },
358 {
359 "location": {
360 "latitude": 34.051713,
361 "longitude": -118.245618
362 },
363 "bearings": [45, 135, 225, 300],
364 "classes": [],
365 "entry": [],
366 "intersection_in": 0,
367 "intersection_out": 2,
368 "lanes": [
369 {
370 "indications": ["left"],
371 "valid": false
372 },
373 {
374 "indications": ["none"],
375 "valid": true
376 },
377 {
378 "indications": ["none"],
379 "valid": true
380 },
381 {
382 "indications": ["none"],
383 "valid": true
384 }
385 ]
386 },
387 {
388 "location": {
389 "latitude": 34.051437,
390 "longitude": -118.245876
391 },
392 "bearings": [45, 225, 300],
393 "classes": [],
394 "entry": [],
395 "intersection_in": 0,
396 "intersection_out": 1,
397 "lanes": []
398 },
399 {
400 "location": {
401 "latitude": 34.05117,
402 "longitude": -118.246131
403 },
404 "bearings": [45, 120, 225],
405 "classes": [],
406 "entry": [],
407 "intersection_in": 0,
408 "intersection_out": 2,
409 "lanes": []
410 },
411 {
412 "location": {
413 "latitude": 34.050804,
414 "longitude": -118.246467
415 },
416 "bearings": [30, 210, 300],
417 "classes": [],
418 "entry": [],
419 "intersection_in": 0,
420 "intersection_out": 1,
421 "lanes": []
422 },
423 {
424 "location": {
425 "latitude": 34.050759,
426 "longitude": -118.246507
427 },
428 "bearings": [30, 135, 210],
429 "classes": [],
430 "entry": [],
431 "intersection_in": 0,
432 "intersection_out": 2,
433 "lanes": []
434 },
435 {
436 "location": {
437 "latitude": 34.050647,
438 "longitude": -118.246608
439 },
440 "bearings": [30, 120, 210, 315],
441 "classes": [],
442 "entry": [],
443 "intersection_in": 0,
444 "intersection_out": 2,
445 "lanes": []
446 },
447 {
448 "location": {
449 "latitude": 34.050402,
450 "longitude": -118.246828
451 },
452 "bearings": [30, 120, 210],
453 "classes": [],
454 "entry": [],
455 "intersection_in": 0,
456 "intersection_out": 2,
457 "lanes": []
458 }
459 ],
460 "road_shield_type": {}
461 },
462 {
463 "geometry": "slg}_Ajafp`F{M~VwHlN}@dBwOdZ",
464 "start_location": {
465 "latitude": 34.050266,
466 "longitude": -118.24695
467 },
468 "end_location": {
469 "latitude": 34.050959,
470 "longitude": -118.248067
471 },
472 "distance": {
473 "value": 128
474 },
475 "duration": {
476 "value": 59
477 },
478 "maneuver": {
479 "instruction": "Use any lane to turn right onto W 3rd St",
480 "voice_instruction": [
481 {
482 "distance_along_geometry": 380,
483 "unit": "meters",
484 "instruction": "In 380 meters, Use any lane to turn right onto W 3rd St"
485 },
486 {
487 "distance_along_geometry": 200,
488 "unit": "meters",
489 "instruction": "In 200 meters, Use any lane to turn right onto W 3rd St"
490 },
491 {
492 "distance_along_geometry": 50,
493 "unit": "meters",
494 "instruction": "Use any lane to turn right onto W 3rd St"
495 }
496 ],
497 "bearing_before": 216,
498 "bearing_after": 306,
499 "coordinate": {
500 "latitude": 34.050266,
501 "longitude": -118.24695
502 },
503 "maneuver_type": "turn",
504 "modifier": "right"
505 },
506 "name": "W 3rd St",
507 "intersections": [
508 {
509 "location": {
510 "latitude": 34.050266,
511 "longitude": -118.24695
512 },
513 "bearings": [30, 135, 225, 300],
514 "classes": [],
515 "entry": [],
516 "intersection_in": 0,
517 "intersection_out": 3,
518 "lanes": [
519 {
520 "indications": ["none"],
521 "valid": true
522 },
523 {
524 "indications": ["none"],
525 "valid": true
526 },
527 {
528 "indications": ["right"],
529 "valid": true
530 }
531 ]
532 },
533 {
534 "location": {
535 "latitude": 34.050504,
536 "longitude": -118.247334
537 },
538 "bearings": [120, 210, 300],
539 "classes": [],
540 "entry": [],
541 "intersection_in": 0,
542 "intersection_out": 2,
543 "lanes": []
544 }
545 ],
546 "road_shield_type": {}
547 },
548 {
549 "geometry": "}wh}_Adghp`FfKpJtc@l]",
550 "start_location": {
551 "latitude": 34.050959,
552 "longitude": -118.248067
553 },
554 "end_location": {
555 "latitude": 34.050176,
556 "longitude": -118.248739
557 },
558 "distance": {
559 "value": 106
560 },
561 "duration": {
562 "value": 21
563 },
564 "maneuver": {
565 "instruction": "Use any lane to turn left onto S Broadway, then you will arrive",
566 "voice_instruction": [
567 {
568 "distance_along_geometry": 94,
569 "unit": "meters",
570 "instruction": "In 200 meters, You will arrive"
571 },
572 {
573 "distance_along_geometry": 50,
574 "unit": "meters",
575 "instruction": "Use any lane to turn left onto S Broadway, then you will arrive"
576 }
577 ],
578 "bearing_before": 306,
579 "bearing_after": 217,
580 "coordinate": {
581 "latitude": 34.050959,
582 "longitude": -118.248067
583 },
584 "maneuver_type": "turn",
585 "modifier": "left"
586 },
587 "name": "S Broadway",
588 "intersections": [
589 {
590 "location": {
591 "latitude": 34.050959,
592 "longitude": -118.248067
593 },
594 "bearings": [30, 120, 225, 315],
595 "classes": [],
596 "entry": [],
597 "intersection_in": 1,
598 "intersection_out": 2,
599 "lanes": [
600 {
601 "indications": ["left"],
602 "valid": true
603 },
604 {
605 "indications": ["none"],
606 "valid": true
607 },
608 {
609 "indications": ["none"],
610 "valid": true
611 },
612 {
613 "indications": ["none"],
614 "valid": true
615 }
616 ]
617 }
618 ],
619 "road_shield_type": {}
620 },
621 {
622 "geometry": "_gg}_Adqip`F",
623 "start_location": {
624 "latitude": 34.050176,
625 "longitude": -118.248739
626 },
627 "end_location": {
628 "latitude": 34.050176,
629 "longitude": -118.248739
630 },
631 "distance": {
632 "value": 0
633 },
634 "duration": {
635 "value": 0
636 },
637 "maneuver": {
638 "instruction": "You have arrived at S Broadway, on the right",
639 "voice_instruction": [
640 {
641 "distance_along_geometry": 50,
642 "unit": "meters",
643 "instruction": "You have arrived at S Broadway, on the right"
644 }
645 ],
646 "bearing_before": 215,
647 "bearing_after": 0,
648 "coordinate": {
649 "latitude": 34.050176,
650 "longitude": -118.248739
651 },
652 "maneuver_type": "arrive",
653 "modifier": "right"
654 },
655 "name": "S Broadway",
656 "intersections": [
657 {
658 "location": {
659 "latitude": 34.050176,
660 "longitude": -118.248739
661 },
662 "bearings": [35],
663 "classes": [],
664 "entry": [],
665 "intersection_in": 0,
666 "intersection_out": 0,
667 "lanes": []
668 }
669 ],
670 "road_shield_type": {}
671 }
672 ]
673 }
674 ]
675 }
676 ],
677 "country_code": "US"
678}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:
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}'
10Navigation Flexible API
Request URL: https://api.nextbillion.io/navigation?option=flexible&{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
originand adestination -
at a specific
departure_time
Request
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=truckResponse
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": {
19 "value": 956
20 },
21 "duration": {
22 "value": 208
23 },
24 "start_location": {
25 "latitude": 34.05606,
26 "longitude": -118.24496
27 },
28 "end_location": {
29 "latitude": 34.05038,
30 "longitude": -118.2409
31 },
32 "steps": [
33 {
34 "geometry": "kqznE~uupUSQo@o@S_@",
35 "start_location": {
36 "latitude": 34.05606,
37 "longitude": -118.24496
38 },
39 "end_location": {
40 "latitude": 34.0565,
41 "longitude": -118.24447
42 },
43 "distance": {
44 "value": 66
45 },
46 "duration": {
47 "value": 20
48 },
49 "maneuver": {
50 "instruction": "Head northeast on N Hill St, then use the right lane to turn right onto W Temple St",
51 "voice_instruction": [],
52 "bearing_before": 0,
53 "bearing_after": 36,
54 "coordinate": {
55 "latitude": 34.056058,
56 "longitude": -118.244961
57 },
58 "maneuver_type": "depart"
59 },
60 "name": "N Hill St",
61 "intersections": [
62 {
63 "location": {
64 "latitude": 34.056058,
65 "longitude": -118.244961
66 },
67 "bearings": [36],
68 "classes": [],
69 "entry": [true],
70 "intersection_in": 0,
71 "intersection_out": 0,
72 "lanes": []
73 },
74 {
75 "location": {
76 "latitude": 34.056159,
77 "longitude": -118.244872
78 },
79 "bearings": [40, 216],
80 "classes": [],
81 "entry": [true, false],
82 "intersection_in": 1,
83 "intersection_out": 0,
84 "lanes": []
85 },
86 {
87 "location": {
88 "latitude": 34.056395,
89 "longitude": -118.244633
90 },
91 "bearings": [52, 220],
92 "classes": [],
93 "entry": [true, false],
94 "intersection_in": 1,
95 "intersection_out": 0,
96 "lanes": []
97 }
98 ],
99 "road_shield_type": {}
100 },
101 {
102 "geometry": "ctznE|rupU`@k@\\g@JMJOX]PSFKJK^a@nAwANOd@i@^g@d@o@TY^e@f@k@LQTWLM\\_@DGHKd@o@f@m@X]PUNS`B{B",
103 "start_location": {
104 "latitude": 34.0565,
105 "longitude": -118.24447
106 },
107 "end_location": {
108 "latitude": 34.05243,
109 "longitude": -118.23966
110 },
111 "distance": {
112 "value": 633
113 },
114 "duration": {
115 "value": 144
116 },
117 "maneuver": {
118 "instruction": "Use the right lane to turn right onto W Temple St",
119 "voice_instruction": [],
120 "bearing_before": 52,
121 "bearing_after": 133,
122 "coordinate": {
123 "latitude": 34.056499,
124 "longitude": -118.244473
125 },
126 "maneuver_type": "turn",
127 "modifier": "right"
128 },
129 "name": "W Temple St",
130 "intersections": [
131 {
132 "location": {
133 "latitude": 34.056499,
134 "longitude": -118.244473
135 },
136 "bearings": [55, 133, 232, 315],
137 "classes": [],
138 "entry": [true, true, false, true],
139 "intersection_in": 2,
140 "intersection_out": 1,
141 "lanes": [
142 {
143 "indications": ["left"],
144 "valid": false
145 },
146 {
147 "indications": ["straight"],
148 "valid": false
149 },
150 {
151 "indications": ["straight", "right"],
152 "valid": true
153 }
154 ]
155 },
156 {
157 "location": {
158 "latitude": 34.056327,
159 "longitude": -118.244251
160 },
161 "bearings": [132, 313],
162 "classes": [],
163 "entry": [true, false],
164 "intersection_in": 1,
165 "intersection_out": 0,
166 "lanes": []
167 },
168 {
169 "location": {
170 "latitude": 34.056176,
171 "longitude": -118.244052
172 },
173 "bearings": [132, 312],
174 "classes": [],
175 "entry": [true, false],
176 "intersection_in": 1,
177 "intersection_out": 0,
178 "lanes": []
179 },
180 {
181 "location": {
182 "latitude": 34.05612,
183 "longitude": -118.243978
184 },
185 "bearings": [133, 312],
186 "classes": [],
187 "entry": [true, false],
188 "intersection_in": 1,
189 "intersection_out": 0,
190 "lanes": []
191 },
192 {
193 "location": {
194 "latitude": 34.05606,
195 "longitude": -118.2439
196 },
197 "bearings": [136, 313],
198 "classes": [],
199 "entry": [true, false],
200 "intersection_in": 1,
201 "intersection_out": 0,
202 "lanes": []
203 },
204 {
205 "location": {
206 "latitude": 34.055929,
207 "longitude": -118.243747
208 },
209 "bearings": [136, 316],
210 "classes": [],
211 "entry": [true, false],
212 "intersection_in": 1,
213 "intersection_out": 0,
214 "lanes": []
215 },
216 {
217 "location": {
218 "latitude": 34.055739,
219 "longitude": -118.243525
220 },
221 "bearings": [37, 140, 218, 316],
222 "classes": [],
223 "entry": [true, true, true, false],
224 "intersection_in": 3,
225 "intersection_out": 1,
226 "lanes": [
227 {
228 "indications": ["left"],
229 "valid": false
230 },
231 {
232 "indications": ["straight"],
233 "valid": true
234 },
235 {
236 "indications": ["straight", "right"],
237 "valid": true
238 }
239 ]
240 },
241 {
242 "location": {
243 "latitude": 34.05558,
244 "longitude": -118.243362
245 },
246 "bearings": [138, 320],
247 "classes": [],
248 "entry": [true, false],
249 "intersection_in": 1,
250 "intersection_out": 0,
251 "lanes": []
252 },
253 {
254 "location": {
255 "latitude": 34.055177,
256 "longitude": -118.242921
257 },
258 "bearings": [137, 318],
259 "classes": [],
260 "entry": [true, false],
261 "intersection_in": 1,
262 "intersection_out": 0,
263 "lanes": []
264 },
265 {
266 "location": {
267 "latitude": 34.055104,
268 "longitude": -118.24284
269 },
270 "bearings": [138, 317],
271 "classes": [],
272 "entry": [true, false],
273 "intersection_in": 1,
274 "intersection_out": 0,
275 "lanes": []
276 },
277 {
278 "location": {
279 "latitude": 34.054913,
280 "longitude": -118.242631
281 },
282 "bearings": [38, 134, 217, 318],
283 "classes": [],
284 "entry": [false, true, true, false],
285 "intersection_in": 3,
286 "intersection_out": 1,
287 "lanes": []
288 },
289 {
290 "location": {
291 "latitude": 34.054754,
292 "longitude": -118.242434
293 },
294 "bearings": [134, 314],
295 "classes": [],
296 "entry": [true, false],
297 "intersection_in": 1,
298 "intersection_out": 0,
299 "lanes": []
300 },
301 {
302 "location": {
303 "latitude": 34.054559,
304 "longitude": -118.242192
305 },
306 "bearings": [134, 314],
307 "classes": [],
308 "entry": [true, false],
309 "intersection_in": 1,
310 "intersection_out": 0,
311 "lanes": []
312 },
313 {
314 "location": {
315 "latitude": 34.05445,
316 "longitude": -118.242057
317 },
318 "bearings": [136, 314],
319 "classes": [],
320 "entry": [true, false],
321 "intersection_in": 1,
322 "intersection_out": 0,
323 "lanes": []
324 },
325 {
326 "location": {
327 "latitude": 34.054291,
328 "longitude": -118.241873
329 },
330 "bearings": [138, 316],
331 "classes": [],
332 "entry": [true, false],
333 "intersection_in": 1,
334 "intersection_out": 0,
335 "lanes": []
336 },
337 {
338 "location": {
339 "latitude": 34.05409,
340 "longitude": -118.241652
341 },
342 "bearings": [37, 134, 218, 318],
343 "classes": [],
344 "entry": [true, true, false, false],
345 "intersection_in": 3,
346 "intersection_out": 1,
347 "lanes": [
348 {
349 "indications": ["left"],
350 "valid": false
351 },
352 {
353 "indications": ["straight"],
354 "valid": true
355 },
356 {
357 "indications": ["straight"],
358 "valid": true
359 }
360 ]
361 },
362 {
363 "location": {
364 "latitude": 34.054016,
365 "longitude": -118.241558
366 },
367 "bearings": [38, 136, 314],
368 "classes": [],
369 "entry": [false, true, false],
370 "intersection_in": 2,
371 "intersection_out": 1,
372 "lanes": []
373 },
374 {
375 "location": {
376 "latitude": 34.053914,
377 "longitude": -118.241439
378 },
379 "bearings": [140, 316],
380 "classes": [],
381 "entry": [true, false],
382 "intersection_in": 1,
383 "intersection_out": 0,
384 "lanes": []
385 },
386 {
387 "location": {
388 "latitude": 34.053845,
389 "longitude": -118.241368
390 },
391 "bearings": [140, 320],
392 "classes": [],
393 "entry": [true, false],
394 "intersection_in": 1,
395 "intersection_out": 0,
396 "lanes": []
397 },
398 {
399 "location": {
400 "latitude": 34.053694,
401 "longitude": -118.241213
402 },
403 "bearings": [37, 135, 320],
404 "classes": [],
405 "entry": [false, true, false],
406 "intersection_in": 2,
407 "intersection_out": 1,
408 "lanes": []
409 },
410 {
411 "location": {
412 "latitude": 34.053657,
413 "longitude": -118.241168
414 },
415 "bearings": [39, 135, 218, 315],
416 "classes": [],
417 "entry": [false, true, false, false],
418 "intersection_in": 3,
419 "intersection_out": 1,
420 "lanes": []
421 },
422 {
423 "location": {
424 "latitude": 34.053611,
425 "longitude": -118.241112
426 },
427 "bearings": [34, 135, 315],
428 "classes": [],
429 "entry": [false, true, false],
430 "intersection_in": 2,
431 "intersection_out": 1,
432 "lanes": []
433 },
434 {
435 "location": {
436 "latitude": 34.053416,
437 "longitude": -118.240875
438 },
439 "bearings": [37, 136, 214, 315],
440 "classes": [],
441 "entry": [true, true, true, false],
442 "intersection_in": 3,
443 "intersection_out": 1,
444 "lanes": [
445 {
446 "indications": ["left"],
447 "valid": false
448 },
449 {
450 "indications": ["straight"],
451 "valid": true
452 },
453 {
454 "indications": ["straight", "right"],
455 "valid": true
456 }
457 ]
458 },
459 {
460 "location": {
461 "latitude": 34.053216,
462 "longitude": -118.240641
463 },
464 "bearings": [136, 316],
465 "classes": [],
466 "entry": [true, false],
467 "intersection_in": 1,
468 "intersection_out": 0,
469 "lanes": []
470 },
471 {
472 "location": {
473 "latitude": 34.053087,
474 "longitude": -118.24049
475 },
476 "bearings": [133, 316],
477 "classes": [],
478 "entry": [true, false],
479 "intersection_in": 1,
480 "intersection_out": 0,
481 "lanes": []
482 },
483 {
484 "location": {
485 "latitude": 34.053,
486 "longitude": -118.240379
487 },
488 "bearings": [134, 313],
489 "classes": [],
490 "entry": [true, false],
491 "intersection_in": 1,
492 "intersection_out": 0,
493 "lanes": []
494 },
495 {
496 "location": {
497 "latitude": 34.052923,
498 "longitude": -118.240283
499 },
500 "bearings": [134, 314],
501 "classes": [],
502 "entry": [true, false],
503 "intersection_in": 1,
504 "intersection_out": 0,
505 "lanes": []
506 }
507 ],
508 "road_shield_type": {}
509 },
510 {
511 "geometry": "uzynEzttpUPHDBF@NDz@V\\Lh@RXLn@VLHNHHFv@j@RPHH\\\\",
512 "start_location": {
513 "latitude": 34.05243,
514 "longitude": -118.23966
515 },
516 "end_location": {
517 "latitude": 34.05038,
518 "longitude": -118.2409
519 },
520 "distance": {
521 "value": 257
522 },
523 "duration": {
524 "value": 43
525 },
526 "maneuver": {
527 "instruction": "Turn right onto Judge John Aiso St",
528 "voice_instruction": [
529 {
530 "distance_along_geometry": 630,
531 "unit": "meters",
532 "instruction": "In 630 meters, Turn right onto Judge John Aiso St"
533 },
534 {
535 "distance_along_geometry": 200,
536 "unit": "meters",
537 "instruction": "In 200 meters, Turn right onto Judge John Aiso St"
538 },
539 {
540 "distance_along_geometry": 50,
541 "unit": "meters",
542 "instruction": "Turn right onto Judge John Aiso St"
543 }
544 ],
545 "bearing_before": 134,
546 "bearing_after": 202,
547 "coordinate": {
548 "latitude": 34.052434,
549 "longitude": -118.239663
550 },
551 "maneuver_type": "turn",
552 "modifier": "right"
553 },
554 "name": "Judge John Aiso St",
555 "intersections": [
556 {
557 "location": {
558 "latitude": 34.052434,
559 "longitude": -118.239663
560 },
561 "bearings": [15, 135, 202, 314],
562 "classes": [],
563 "entry": [false, true, true, false],
564 "intersection_in": 3,
565 "intersection_out": 2,
566 "lanes": []
567 },
568 {
569 "location": {
570 "latitude": 34.051745,
571 "longitude": -118.239959
572 },
573 "bearings": [21, 201, 322],
574 "classes": [],
575 "entry": [false, true, true],
576 "intersection_in": 0,
577 "intersection_out": 1,
578 "lanes": []
579 },
580 {
581 "location": {
582 "latitude": 34.051401,
583 "longitude": -118.240127
584 },
585 "bearings": [24, 203, 289],
586 "classes": [],
587 "entry": [false, true, true],
588 "intersection_in": 0,
589 "intersection_out": 1,
590 "lanes": []
591 },
592 {
593 "location": {
594 "latitude": 34.051162,
595 "longitude": -118.240252
596 },
597 "bearings": [23, 118, 209, 301],
598 "classes": [],
599 "entry": [false, true, true, true],
600 "intersection_in": 0,
601 "intersection_out": 2,
602 "lanes": []
603 },
604 {
605 "location": {
606 "latitude": 34.051013,
607 "longitude": -118.24035
608 },
609 "bearings": [29, 120, 213],
610 "classes": [],
611 "entry": [false, true, true],
612 "intersection_in": 0,
613 "intersection_out": 2,
614 "lanes": []
615 },
616 {
617 "location": {
618 "latitude": 34.050682,
619 "longitude": -118.240608
620 },
621 "bearings": [33, 217],
622 "classes": [],
623 "entry": [false, true],
624 "intersection_in": 0,
625 "intersection_out": 1,
626 "lanes": []
627 },
628 {
629 "location": {
630 "latitude": 34.050576,
631 "longitude": -118.240704
632 },
633 "bearings": [37, 219],
634 "classes": [],
635 "entry": [false, true],
636 "intersection_in": 0,
637 "intersection_out": 1,
638 "lanes": []
639 }
640 ],
641 "road_shield_type": {}
642 },
643 {
644 "geometry": "{mynEr|tpU??",
645 "start_location": {
646 "latitude": 34.05038,
647 "longitude": -118.2409
648 },
649 "end_location": {
650 "latitude": 34.05038,
651 "longitude": -118.2409
652 },
653 "distance": {
654 "value": 0
655 },
656 "duration": {
657 "value": 0
658 },
659 "maneuver": {
660 "instruction": "You have arrived at Judge John Aiso St",
661 "voice_instruction": [
662 {
663 "distance_along_geometry": 200,
664 "unit": "meters",
665 "instruction": "In 200 meters, You will arrive"
666 },
667 {
668 "distance_along_geometry": 50,
669 "unit": "meters",
670 "instruction": "You have arrived at Judge John Aiso St"
671 }
672 ],
673 "bearing_before": 221,
674 "bearing_after": 0,
675 "coordinate": {
676 "latitude": 34.05038,
677 "longitude": -118.2409
678 },
679 "maneuver_type": "arrive"
680 },
681 "name": "Judge John Aiso St",
682 "intersections": [
683 {
684 "location": {
685 "latitude": 34.05038,
686 "longitude": -118.2409
687 },
688 "bearings": [41],
689 "classes": [],
690 "entry": [true],
691 "intersection_in": 0,
692 "intersection_out": 0,
693 "lanes": []
694 }
695 ],
696 "road_shield_type": {}
697 }
698 ]
699 }
700 ]
701 }
702 ],
703 "country_code": "US"
704}When represented on a map the above response would look similar to below illustration
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
waypointsallowed in a GET request is 50 and in a POST request is 200. -
Maximum dimensions allowed for
truck_sizeare 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 (geometry+geometry_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 Code | Description | Additional Notes |
|---|---|---|
| 200 | Normal success case. | Normal success case. |
| 400 | Input validation failed. | There is a missing or an invalid parameter or a parameter with an invalid value type is added to the request. |
| 401 | APIKEY not supplied or invalid. | This error occurs when the wrong API key is passed in the request or the key is missing altogether |
| 403 | APIKEY 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. |
| 404 | Requested host/path not found. | This error occurs when there is a malformed host name used |
| 422 | Could not process the request. | Valid route could not be generated for the given parameters. |
| 429 | Too many requests. | QPM or API request count quota reached |
| 500 | Internal Service error. | There was an internal issue with NextBillion.ai services. You can reach out to [email protected] for an explanation. |
Isochrone
