Directions API
Introduction
Nextbillion.ai's Directions API is a service that computes a route between 2 places. With the Directions API you can:
-
Find the most optimal route and ETAs between the origin and the destination.
-
Get directions for different driving modes like car & truck.
-
You can also add waypoints, which are coordinates along the route.
-
Produce turn-by-turn instructions.
-
Plan your trips in advance by setting departure time to get best routes and ETAs
-
Get different routes based on different truck dimensions and weight.
A full list of parameters is documented in the next section.
Parameters
Loading...Response Schema
Loading...Query Limits
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.
Examples
Sample API Request
Example 1 - Simple Directions API
https://api.nextbillion.io/directions/json?origin=12.98740754,77.58327035&destination=12.95545688,77.61554269&session=R5mvdi&alternatives=false&altcount=1&annotations=false&approaches=unrestricted;unrestricted&avoid=toll&mode=4w&waypoints=12.973691,77.58824853&departure_time=1649144593&key=<insert your key here>
In the above example, we will find the route between the origin of 12.98740754,77.58327035 and the destination point with the coordinate of 12.95545688,77.61554269. We have also added a waypoint with coordinates of 12.973691,77.58824853.
Let’s take a look at the parameters we use in this request-
-
We have alternatives = false so no alternative routes will be shown.
-
Annotations are set to false, so the response schema will not return telemetry for each node pair.
-
Approaches are set to unrestricted; unrestricted. Note that we are setting values for 2 approaches because we have added a waypoint. 1 destination and 1 waypoint, each need their approaches values set. Note that you can skip the approach for a waypoint/destination by simply using a semi-colon instead of the value. In that case, the parameter would become - approaches=;; unrestricted.
-
We have set the avoid property to toll, so our route will avoid any toll plazas along it.
-
We have set Mode = 4w so we get a route specific to a 4-wheeler.
Visual Representation

Sample API Response
1{
2 "status": "Ok",
3 "mode": "4w",
4 "routes": [
5 {
6 "geometry": "mognA{}[email protected]@PZJ@@`Ad@`[email protected]@[email protected]@s@^]^][email protected]@\\[email protected]]@[email protected]@[email protected]@KDYBKFWH][email protected]@DMJ]F]@[email protected]}@[email protected]}@[email protected]@Q{@EUG[G[[email protected]@[email protected]][email protected]@[email protected]@[email protected]@[email protected]@Z^[email protected]@VHDDBTL`@[email protected]^[email protected]@`@[email protected]@[email protected]@@[email protected]@[email protected][email protected][email protected][email protected]?][email protected]@JYHa@[email protected]?ADwAD{[email protected]@[email protected][email protected][email protected]@[email protected]@IP][email protected]@[email protected][[email protected]@[email protected][[email protected][email protected]@[email protected]@[email protected][[email protected]@C?M@_@[email protected]@?IAi@?KDK?O?G?KBY?G^[email protected]@FWDSH[[email protected]@\\[email protected]@[email protected]@[email protected]\\D`ANTD\\[email protected]@JANGNKCKOWe@{@[email protected]][email protected]?AQWOQIK}@[email protected]@[email protected]@M`@[email protected]@[email protected]@[email protected][email protected]{[email protected]@@u@@[email protected]@IDMFMBEDIBGBKF[@[email protected]@IO?EQAG?EQ{[email protected]?EEOEOXSTQN[email protected]@[[email protected]@[email protected]@[email protected][email protected]@^[email protected]@@[email protected][email protected]}@[email protected]@[email protected]@[email protected][email protected]@[email protected]@BP@d@@[email protected]@[email protected]@[email protected]@[email protected][email protected][email protected]@DB?J?`@[email protected]?BtAB",
7 "distance": 7680.200000000001,
8 "duration": 1632.6999999999998,
9 "legs": [
10 {
11 "distance": {
12 "value": 2510
13 },
14 "duration": {
15 "value": 533
16 },
17 "steps": []
18 },
19 {
20 "distance": {
21 "value": 5169
22 },
23 "duration": {
24 "value": 1098
25 },
26 "steps": []
27 }
28 ]
29 }
30 ]
31}
API Query Limits
-
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.
-
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, 1000 cm for width, 1000 cm for height. -
Maximum weight allowed for
truck_weight
(including the trailer and shipped goods) is 100,000 kg
API Error Codes
Response Code | Description | Additional Notes |
---|---|---|
200 | Normal success case. | Normal success case. |
400 | Input validation failed. | Such as missing parameter or parameter with invalid value type (for example value cannot be parsed into number). |
401 | APIKEY not supplied or invalid. | - |
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 limit 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. |