# Directions API

## Introduction

NextBillion.ai's Directions API is a service that computes a route between two places offering a comprehensive suite of features to optimize your navigation experience:

- **Optimal Routing**: Get the best driving directions based on real-time traffic conditions, with options for the fastest or shortest routes.
- **Advanced Trip Planning**: Plan your journeys in advance by setting a departure time to receive optimal routes and estimated times of arrival (ETAs).
- **Diverse Driving Modes**: Obtain safe and legal directions tailored for various modes of transport, including walking, cycling, motorbiking, cars, and trucks.
- **Route Customization**: Avoid or exclude routes with specific maneuvers or road objects, such as tolls, right/left turns, U-turns, highways or service roads.
- **Truck-Specific Routing**: Cater to unique truck routing needs by considering factors like truck weight and dimensions, weight distribution per axle, hazardous cargo, emission classification, layover regulations, and many more specialized features.

NextBillion.ai's **Directions API** is available in two versions, designed to suit a wide range of business needs. The **Flexible** version provides the most advanced set of features, customization options, and routing capabilities. It is ideal for complex or specialized use cases where precision and tailored solutions matter most. The **Fast** version, on the other hand, is optimized for speed and efficiency. With a streamlined feature set, it delivers rapid results and is best suited for high-volume, standard routing scenarios where quick responses are a priority.

We will cover both these endpoints in depth in the following sections.

## Directions Flexible API

The Directions Flexible API is designed for scenarios where **precision, customization, and advanced routing** constraints are critical. The routes are calculated based on **live and historical traffic** conditions. It also supports comprehensive **truck-specific features** (such as truck size, hazardous cargo, and emissions class), and advanced **routing preferences** like avoiding tolls, sharp turns, or restricted roads. With the ability to optimize for the *fastest* or *shortest* path, provide alternative routes, and handle multiple travel modes—from walking and biking to motorbikes, cars, and trucks—the Flexible endpoint offers a high degree of versatility.

To use the Directions Flexible API service set the `option` parameter to "flexible". The Flexible endpoint supports both HTTPS GET and POST methods. Request URL, parameters and response schemas are the same for both methods.

```
GET https://api.nextbillion.io/directions/json?option=flexible&key={your_api_key}
```

### Request Parameters

| Name | Required | Format and Usage | Description |
|------|----------|------------------|-------------|
| `key` | Yes | Type: `string`<br>Format: 32 character alphanumeric string<br>Example: `key=API_KEY` | A key is a unique identifier required to authenticate a request to the API. |
| `origin` | Yes | Type: `string`<br>Format: `latitude,longitude`<br>Example: `origin=41.349302,2.136480` | Starting point of your route. Ensure that the origin is a routable land location. |
| `destination` | Yes | Type: `string`<br>Format: `latitude,longitude`<br>Example: `destination=41.349302,2.136480` | Ending point of your route. Ensure that the destination is a routable land location. |
| `option` | Yes | Type: `string`<br>Example: `option=flexible` | Must be set to `flexible` to use the Flexible version. |
| `waypoints` | No | Type: `string`<br>Format: `latitude_1,longitude_1\|latitude_2,longitude_2\|...`<br>Example: `waypoints=41.349302,2.136480\|41.349303,2.136481` | `waypoints` are coordinates along the route between the `origin` and `destination`. It is a pipe-separated list of coordinate pairs. Please note that all `waypoints` are treated as mandatory route points and the route will arrive at each `waypoints` in the sequence they are provided in the input request.<br> Please note that the maximum number of `waypoints` that can be added in a single request is 50. |
| `mode` | No | Type: `string`<br>Default: `car`<br>Allowed values: `car`, `truck`, `motorcycle`, `bike`, `walk`<br>Example: `mode=car` | Driving mode for route calculation. When using `truck` mode, default dimensions are assumed (height: 214 cm, width: 183 cm, length: 519 cm, weight: 5000 kg) unless overridden by `truck_size` and `truck_weight`. If the desired mode is not available for ayour region, please reach out to [support@nextbillion.ai](mailto:support@nextbillion.ai) |
| `geometry` | No | Type: `string`<br>Default: `polyline6`<br>Allowed values: `polyline`, `polyline6`<br>Example: `geometry=polyline` | Sets the output format of the route geometry. |
| `route_type` | No | Type: `string`<br>Default: `fastest`<br>Allowed values: `fastest`, `shortest`<br>Example: `route_type=fastest` | Sets the type of route to return. |
| `departure_time` | No | Type: `integer`<br>Example: `departure_time=1563254734` | Use this parameter to set a departure time for your trip using a UNIX timestamp in seconds precision. The response will return a route based on typical traffic conditions at the given time. If no input is provided for this parameter then the traffic conditions at the time of making the request are considered. |
| `honor_restrictions` | No | Type: `boolean`<br>Default: `false` | Decide what the API should do if the `origin`, `destination`, or any `waypoints` falls inside a restricted area. When set to "false" (default behavior), the API overrides any restrictions to generate a full route, along with a warning in the response to indicate the same. When set to "true", all routing restrictions are honored and no route is generated for such cases. |
| `avoid` | No | Type: `string`<br>Default: `ferry`<br>Allowed values: `toll`, `highway`, `ferry`, `sharp_turn`, `uturn`, `service_road`, `left_turn`, `right_turn`, `bbox`, `geofence_id`, `tunnel`, `none`<br>Example: `avoid=toll\|highway\|bbox:34.0635,-118.2547,34.0679,-118.2478` | Set this parameter to find alternative routes that bypass specified objects. Use a pipe (`\|`) to separate multiple values. This is a flexible filter; if no alternative routes exist, the service will still provide a route that includes the objects. For a strict filter, consider using the `exclude` parameter.<br>**Note:**<br>*   Following objects are exceptions to the flexible filtering behavior of `avoid` parameter: `bbox` , `tunnel` and `geofence_id` . When used, the service will return a 4xx error in case there are no alternative routes available.<br>*   When using `avoid=bbox` users also need to specify the boundaries of the bounding box to be avoided. Multiple bounding boxes can be specified simultaneously. The perimeter of a bounding box can not exceed 500 kms.<br>    *   **Format:** bbox: min\_latitude,min\_longtitude,max\_latitude,max\_longitude.<br>    *   **Example:** avoid=bbox: 34.0635,-118.2547, 34.0679,-118.2478 \| bbox: 34.0478,-118.2437, 34.0521,-118.2342<br>*   When using `avoid=sharp_turn`, default range of permissible turn angles is \[120,240\] in the clockwise direction from the current road. In order to override default range, please use `turn_angle_range` parameter.<br>*   When using `avoid=geofence_id` , only the the geofences created using NextBillion.ai [Geofence API](https://docs.nextbillion.ai/docs/tracking/api/geofence) are valid.<br>*   When this parameter is not provided in the input, `ferry` routes are set to be avoided by default. When this parameter is provided, only the mentioned object(s) are avoided.<br>*   If `none` is provided along with other values, an error is returned as a valid route is not feasible. |
| `exclude` | No | Type: `string`<br>Default: `none`<br>Allowed values: `toll`, `ferry`, `highway`, `service_road`, `uturn`, `sharp_turn`, `left_turn`, `right_turn`, `none`<br>Example: `exclude=highway\|toll\|uturn` | This parameter serves as a mandatory filter, ensuring the service returns only those routes that strictly avoid the object(s) indicated. Multiple values should be separated by a pipe (`\|`). If no routes can be found that exclude the specified object(s), the service will return a 4xx error. For a less strict filtering approach, consider using the `avoid` parameter.<br>**Note:**<br>*   When using `exclude=sharp_turn`, default range of permissible turn angles is \[120,240\] in the clockwise direction from the current road. In order to override default range, please use `turn_angle_range` parameter.<br>*   If `none` is provided along with other values, an error is returned as a valid route is not feasible. |
| `allow` | No | Type: `string`<br>Allowed values: `taxi`<br>Example: `allow=taxi` | Use taxi-specific lanes/roads for route calculation. Effective only when `mode=car`. |
| `approaches` | No | Type: `string`<br>Default: `unrestricted`<br>Allowed values: `unrestricted`, `curb`<br>Example: `approaches=unrestricted;curb;;unrestricted` | Semicolon-separated list indicating the side of the road from which to approach `waypoints`. The number of values must be one more than the number of `waypoints` provided. Skip a coordinate by leaving its position empty between `;` separators. |
| `bearings` | No | Type: `string`<br>Default: `none`<br>Format: `degree,range;degree,range;...`<br>Example: `bearings=0,180;0,180` | Limits search to road segments with the given bearing toward true north in clockwise direction. Each bearings should be in the format of "degree,range", where the degree should be a value between [0, 360] and range should be a value between [0, 180]. The number of bearings provided must be two more than the number of `waypoints` to account for the bearings of `origin` and `destination`. If a route can approach a waypoint or the destination from any direction, the bearing for that point can be specified as "0,180". |
| `alternatives` | No | Type: `boolean`<br>Default: `false` | When `true` the API will return alternate routes. The default value is `false`. You can set the number of alternate routes to be returned in the `altcount` property.<br>The `alternatives` is effective only when there are no `waypoints` included in the request. |
| `altcount` | No | Type: `integer`<br>Default: `3`<br>Minimum: 1,<br>Maximum: 3<br>Example: `altcount=3` | Sets the number of alternative routes. Effective only when `alternatives` is `true`. |
| `turn_angle_range` | No | Type: `integer` | Specify the turn angles that can be taken safely by the vehicle. Permissible turn angles are calculated as [0 + turn_angle_range, 360 - turn_angle_range]. Effective only when `avoid=sharp_turn` or `exclude=sharp_turn`. It is worth highlighting here that providing smaller angles might lead to 4xx errors as route engine might not be able find routes satisfying the smaller turn angle criteria for all turns in the route. |
| `cross_border` | No | Type: `boolean`<br>Default: `false` | Specify if crossing an international border is expected for operations near border areas. When `false`, routes crossing borders are prohibited. When `true`, routes may cross international borders if required. Feature may not be available in all regions. |
| `road_info` | No | Type: `string`<br>Allowed values: `max_speed`, `toll_distance`, `toll_cost`, `toll_info`, `truck_route`, `stop_sign`, `traffic_light`<br>Example: `road_info=toll_info\|toll_cost` | Receive additional information about road segments in the response. Multiple values separated by pipe (`\|`). Currently, following inputs are supported:<br> * `max_speed`: segment-wise maximum speed information of roads in the response.<br> * `toll_distance`: returns the total distance travelled on the road segments having tolls.<br> * `toll_cost`: returns the range of toll charges, in local currency, that can be incurred for the suggested route.<br> * `toll_info`: returns information about toll - location coordinates and toll name. For most tolls, the location coordinates in the response represent the physical location of the toll. However, some regions support distance-based or zone-based tolls, and there are no physical gates or stations on the road. The coordinates returned for for such tolls are just references for locations where charges are levied.<br> * `truck_route`: returns all the available values for allowed truck types on each segment used in the suggested route.<br> * `stop_sign`: returns the locations of all "STOP" signs along the suggested route.<br> * `traffic_light`: returns the locations of all traffic lights along the suggested route.|
| `truck_size` | No | Type: `string`<br>Default: `214,183,519`<br>Example: `truck_size=200,210,600` | Defines truck dimensions in centimeters: `height,width,length`. Maximum dimensions: height = 1000 cm, width = 5000 cm, length = 5000 cm. Effective only when `mode=truck`. |
| `truck_weight` | No | Type: `integer`<br>Default: `5000`<br>Minimum value: 1,<br>Maximum value: 100,000<br>Example: `truck_weight=11770` | Weight of the truck including trailers and shipped goods, in kilograms. Effective only when `mode=truck`. |
| `truck_axle_load` | No | Type: `number`<br>Default: `0`<br>Example: `truck_axle_load=5.6` | Total load per axle (including the weight of trailers and shipped goods) in tonnes. The service returns routes legally allowed to carry the specified load per axle. Effective only when `mode=truck`. |
| `hazmat_type` | No | Type: `string`<br>Allowed values: `explosives`, `gas`, `flammable_liquid`, `flammable_gas`, `organic`, `toxic`, `radioactive`, `corrosive`, `other`<br>Example: `hazmat_type=explosives\|corrosive` | Type of hazardous material being carried. The service will avoid roads not suitable for the specified goods type. Multiple values must be separated by pipe (`\|`). Effective only when `mode=truck`. |
| `emission_class` | No | Type: `string`<br>Allowed values: `euro0`, `euro1`, `euro2`, `euro3`, `euro4`, `euro5`, `euro6`, `euro7`, `euro8`, `euro9`<br>Example: `emission_class=euro2\|euro3` | Emission class of the vehicle (engine). The service generates routes permissible for that engine class. Only EU region emission classifications are currently supported. Effective only when `mode=truck`. |
| `prefer` | No | Type: `string`<br>Allowed values: `truck_route` | Prioritizes truck-friendly roads when calculating routes. Effective only when and `mode=truck`. The `truck_type` setting is ineffective without this parameter. |
| `truck_type` | No | Type: `string`<br>Allowed values: `rigid_truck`, `semi_trailer`, `b_double`, `road_train`, `generic_truck`<br>Example: `truck_type=rigid_truck\|semi_trailer` | Define the truck type for determining permissible roads. Multiple values must be separated via pipe separator, (`\|`). Effective only when `prefer=truck_route` and `mode=truck`. |
| `drive_time_limits` | No | Type: `string`<br>Format: drive_time_limits_1, drive_time_limits_2,...<br>Example: `drive_time_limits=500,400,400` | Comma-separated array of durations in seconds for which the driver can drive continuously before taking a rest. After driving for each specified duration, the driver rests for the period specified in `rest_times`. Useful for Hours of Service compliance and calculating actual ETAs with regulated driving periods. If trip duration is smaller than the first input, no rest actions are scheduled. If trip duration exceeds scheduled time, a warning is returned. |
| `rest_times` | No | Type: `string`<br> Format: rest_times_1,rest_times_2,....<br>Example: `rest_times=500,300,100` | Comma-separated array of durations in seconds for which the driver should rest after completing the corresponding continuous driving interval from `drive_time_limits`. Ideally the number of `rest_times` should equal the number of `drive_time_limits`. If fewer `rest_times` are provided, the service schedules 0 seconds rest periods for unmatched intervals. Extra `rest_times` beyond `drive_time_limits` are not applied. |

### POST Request

The parameters and their properties for the Directions Flexible POST version are the same as listed in the [Request Parameters](#request-parameters) section. The `key` and `option` are passed as query parameters and the rest of the parameters should be included in the Request Body.

```
POST https://api.nextbillion.io/directions/json?option=flexible&key={your_api_key}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `status` | string | State of the response. On normal responses, the value will be `Ok`. |
| `msg` | string | Error message in case of a failed request. Not returned on success. |
| `routes` | array of objects | Array of route objects. Multiple routes when `alternatives` is configured. |
| `routes[].geometry` | string | Encoded geometry of the route in the format specified by the `geometry` parameter. |
| `routes[].distance` | number | Total distance of the complete trip, in meters. |
| `routes[].duration` | number | Total duration of the complete trip, in seconds. |
| `routes[].start_location` | object | Coordinates where the route starts (same as `origin`). Contains `latitude` and `longitude`. |
| `routes[].end_location` | object | Coordinates where the route ends (same as `destination`). Contains `latitude` and `longitude`. |
| `routes[].legs` | array of objects | Details about each leg of the route. Waypoints split the route into legs. |
| `routes[].legs[].distance` | object | Leg distance. Contains `value` (number) in meters. |
| `routes[].legs[].duration` | object | Leg duration. Contains `value` (number) in seconds. |
| `routes[].legs[].start_location` | object | Coordinates where the leg starts. Contains `latitude` and `longitude`. |
| `routes[].legs[].end_location` | object | Coordinates where the leg ends. Contains `latitude` and `longitude`. |
| `routes[].legs[].steps` | array of objects | Details of each step of the leg. |
| `routes[].legs[].steps[].geometry` | string | Encoded geometry of the step. |
| `routes[].legs[].steps[].start_location` | object | Step start coordinates. Contains `latitude` and `longitude`. |
| `routes[].legs[].steps[].end_location` | object | Step end coordinates. Contains `latitude` and `longitude`. |
| `routes[].legs[].steps[].distance` | object | Step distance. Contains `value` (number) in meters. |
| `routes[].legs[].steps[].duration` | object | Step duration. Contains `value` (number) in seconds. |
| `routes[].legs[].post_actions` | array of objects | Scheduled stops from Hours of Service compliance. Present only when `drive_time_limits` is configured and a rest is scheduled. Each object has `action` (string, type of action) and `duration` (string, duration of stop). |
| `routes[].legs[].warnings` | array of objects | Warnings associated with the leg. Each object has `title` (string, warning details). |
| `routes[].road_info` | object | Additional road segment information. Only present when the `road_info` parameter is set in the request. |
| `routes[].road_info.max_speed` | array of objects | Segment-wise maximum speed. Each object has `offset` (integer, index value of the location coordinate in decoded route geometry where the road segment starts), `length` (integer, number of consecutive vertices), `value` (number, max speed in km/h; `-1` = unlimited, `0` = no info). |
| `routes[].road_info.toll_distance` | integer | Total distance on toll road segments, in meters. |
| `routes[].road_info.toll_cost` | object | Toll charge range. Contains `minimum_toll_cost` (number), `maximum_toll_cost` (number), `currency` (string). |
| `routes[].road_info.toll_info` | array of objects | Toll location coordinates and toll name. |
| `routes[].road_info.truck_route` | array of objects | Allowed truck types per segment. Each object has `offset` (integer, index value of the location coordinate in decoded route geometry where the road segment starts), `length` (integer), `value` (array of strings — allowed truck types). |
| `routes[].road_info.stop_sign` | array of objects | Information about all "STOP" signs on the route. Each object has `offset` (integer, index value of the location coordinate in decoded route geometry corresponding to the stop sign), `latitude` (number), and `longitude`(number). This attribute is present only when `road_info=stop_sign`. |
| `routes[].road_info.traffic_light` | array of objects | Information about all traffic lights on the route. Each object has `offset` (integer, index value of the location coordinate in decoded route geometry corresponding to the traffic light), `latitude` (number), and `longitude`(number). This attribute is present only when `road_info=traffic_light`. |

> **Directions API Examples**
> To see all the examples related to Directions API, click the [Directions API Examples](https://docs.nextbillion.ai/routing/directions-api/examples) banner.

## Directions Fast API

The Directions Fast API is designed to serve **high-volume**, real-time routing scenarios and prioritizing **low latency**. It offers essential routing features for common use cases. The Fast endpoint considers **historical traffic** for timely routing and avoids any delays under usual circumstances. It supports car and truck modes with default truck routing parameters. Additional options include avoiding highways, tolls, and ferries, providing alternative routes, and supporting intervening waypoints. It also offers curbside approach routing, ideal for ride-hailing, delivery, or fleet applications needing precise pickup/drop-off.

> *We recommend using the [Directions Flexible API](#directions-flexible-api) for custom business requirements or if support for advanced routing constraints is critical.*

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

```
GET https://api.nextbillion.io/directions/json?key={your_api_key}
```

### Request Parameters

| Name | Required | Format and Usage | Description |
|------|----------|------------------|-------------|
| `key` | Yes | Type: `string`<br>Format: 32 character alphanumeric string<br>Example: `key=API_KEY` | A key is a unique identifier that is required to authenticate a request to the API. |
| `origin` | Yes | Type: `string`<br>Format: `latitude,longitude`<br>Example: `origin=41.349302,2.136480` | Starting point of your route. Ensure that the origin is a routable land location. |
| `destination` | Yes | Type: `string`<br>Format: `latitude,longitude`<br>Example: `destination=41.349302,2.136480` | Ending point of your route. Ensure that the destination is a routable land location. |
| `waypoints` | No | Type: `string`<br>Format: `latitude_1,longitude_1\|latitude_2,longitude_2\|...`<br>Example: `waypoints=41.349302,2.136480\|41.349303,2.136481` | `waypoints` are coordinates along the route between the `origin` and `destination`. It is a pipe-separated list of coordinate pairs. Please note that all `waypoints` are treated as mandatory route points and the route will arrive at each `waypoints` in the sequence they are provided in the input request.<br>Please note that the maximum number of `waypoints` that can be provided in a single request is 50 when using GET method and 200 with POST method. |
| `mode` | No | Type: `string`<br>Default: `car`<br>Allowed values: `car`, `truck`<br>Example: `mode=car` | Driving mode the service should use to determine a route. Please reach out to [support@nextbillion.ai](mailto:support@nextbillion.ai) if the selected mode is not available for your region. When `mode=truck` is used with the Directions Fast API endpoint, the service applies default truck dimensions as described in the [Default Truck Dimensions for Fast API](#default-truck-dimensions-for-fast-api) section. |
| `steps` | No | Type: `boolean`<br>Default: `false` | Set to `true` to receive additional details about routes and each of its legs, including turn-by-turn step information. |
| `alternatives` | No | Type: `boolean`<br>Default: `false` | When `true`, the API returns alternate routes. Effective only when there are no `waypoints` in the request. Use `altcount` to control the number of alternatives returned. |
| `altcount` | No | Type: `integer`<br>Default: `3`<br>Minimum value: 1,<br>Maximum value: 3<br>Example: `altcount=3` | Sets the number of alternative routes to return. Effective only when `alternatives` is `true`. The specified count does not guarantee a matching number of routes if potential alternatives do not exist. |
| `avoid` | No | Type: `string`<br>Default: `ferry`<br>Allowed values: `toll`, `ferry`, `highway`, `none`<br>Example: `avoid=highway\|toll` | Ensures the route avoids the specified features. Multiple values separated by pipe (`\|`). When not provided, ferries are avoided by default. If `none` is provided along with other values, an error is returned. |
| `overview` | No | Type: `string`<br>Default: `full`<br>Allowed values: `full`, `simplified`, `false`<br>Example: `overview=full` | Specifies the route geometry detail level. Allowed value details: `full` (most detailed), `false` (no geometry). |
| `approaches` | No | Type: `string`<br>Default: `unrestricted`<br>Allowed values: `unrestricted`, `curb`<br>Example: `approaches=unrestricted;;curb;` | A semicolon-separated list indicating the side of the road from which to approach waypoints. When set to `unrestricted` a route can arrive at the waypoint from either side of the road and when set to `curb` the route will arrive at the waypoint on the driving side of the region.<br> The number of values must be one more than the number of `waypoints` to account for the approach to `destination`. Skip a coordinate by leaving its position empty between `;` separators.|
| `bearings` | No | Type: `string`<br>Default: `none`<br>Format: `degree,range;degree,range;...`<br>Example: `bearings=0,180;0,180` | Limits search to road segments with the given bearing toward true north in clockwise direction. Each bearings should be in the format of "degree,range", where the degree should be a value between [0, 360] and range should be a value between [0, 180]. The number of bearings provided must be two more than the number of `waypoints` to account for the bearings of `origin` and `destination`. If a route can approach a waypoint or the destination from any direction, the bearing for that point can be specified as "0,180". |
| `geometry` | No | Type: `string`<br>Default: `polyline`<br>Allowed values: `polyline`, `polyline6`, `geojson`<br>Example: `geometry=polyline` | Sets the output format of the route geometry. When `geojson` is selected, `polyline6` encoded geometry is returned along with a `geojson` object. |

### POST Request

The parameters and their properties for the Directions Fast POST version are the same as listed in the [Request Parameters](#request-parameters-1) section. The `key` is passed as a request parameter and the rest of the parameters should be included in the Request Body.

```
POST https://api.nextbillion.io/directions/json?key={your_api_key}
```

### Response Schema

| Field | Type | Description |
|-------|------|-------------|
| `status` | string | State of the response. On normal responses, the value will be `Ok`. |
| `msg` | string | Error message in case of a failed request. Not returned on success. |
| `routes` | array of objects | Array of route objects. Multiple routes when `alternatives` is configured. |
| `routes[].geometry` | string | Encoded geometry of the route in the format specified by the `geometry` parameter and the verbosity of `overview`. |
| `routes[].distance` | number | Total distance of the complete trip, in meters. |
| `routes[].duration` | number | Total duration of the complete trip, in seconds. |
| `routes[].start_location` | object | Coordinates where the route starts. Returned only when `steps=true`. Contains `latitude` (number) and `longitude` (number). |
| `routes[].end_location` | object | Coordinates where the route ends. Returned only when `steps=true`. Contains `latitude` (number) and `longitude` (number). |
| `routes[].geojson` | object | GeoJSON representation of the route. Returned only when `geometry=geojson`. Follows [RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946). |
| `routes[].geojson.type` | string | Type of the GeoJSON object. |
| `routes[].geojson.geometry` | object | GeoJSON geometry with `type` (string) and `coordinates` (array of numbers). |
| `routes[].geojson.properties` | string | Properties associated with the GeoJSON shape. |
| `routes[].legs` | array of objects | Details about each leg of the route. Waypoints split the route into legs. |
| `routes[].legs[].distance` | object | Leg distance. Contains `value` (number) in meters. |
| `routes[].legs[].duration` | object | Leg duration. Contains `value` (number) in seconds. |
| `routes[].legs[].start_location` | object | Coordinates where the leg starts. Returned only when `steps=true`. Contains `latitude` and `longitude`. |
| `routes[].legs[].end_location` | object | Coordinates where the leg ends. Returned only when `steps=true`. Contains `latitude` and `longitude`. |
| `routes[].legs[].steps` | array of objects | Details of each step. Returned only when `steps=true`; empty array otherwise. |
| `routes[].legs[].steps[].geometry` | string | Encoded geometry of the step. |
| `routes[].legs[].steps[].start_location` | object | Step start coordinates. Contains `latitude` and `longitude`. |
| `routes[].legs[].steps[].end_location` | object | Step end coordinates. Contains `latitude` and `longitude`. |
| `routes[].legs[].steps[].distance` | object | Step distance. Contains `value` (number) in meters. |
| `routes[].legs[].steps[].duration` | object | Step duration. Contains `value` (number) in seconds. |
| `routes[].legs[].steps[].geojson` | object | GeoJSON details of the step. Returned only when `geometry=geojson`. |

### Default Truck Dimensions for Fast API

Following are the default truck dimensions used by the service to determine routes when `mode=truck` is used with Directions Fast API endpoint:

| Dimension/Region | Height | Width | Length | Weight | Axles | Weight per Axle | Countries |
|------------------|--------|-------|--------|--------|-------|---------------------|-------------------------------------|
| North America | 13 feet, 6 inches | 96 inches | 48 feet | 80,000 pounds | 5 | 34,000 pounds | United States, Canada and Mexico |
| Europe | 4.00 meters | 2.55 meters | 16.50 meters | 40 tonnes | 5 | 11.5 tonnes | Germany, France, Italy, Spain, United Kingdom, Netherlands, Belgium, Austria, Switzerland, Poland, Czechia, Portugal, Sweden, Norway, Denmark, Finland, Ireland, Greece, Hungary, Romania, Bulgaria, Slovakia, Slovenia, Croatia, Luxembourg, Estonia, Latvia, Lithuania, Serbia, Bosnia and Herzegovina, Montenegro, North Macedonia, Albania, Ukraine, Belarus, Moldova, Iceland, Malta, Cyprus and Russia |
| South America | 4.00 meters | 2.60 meters | 18.60 meters | 45 tonnes | 6 | 11.5 tonnes | Brazil, Argentina, Chile, Colombia, Peru, Venezuela, Ecuador, Bolivia, Paraguay, Uruguay, Guyana and Suriname |
| Oceania | 4.30 meters | 2.44 meters | 19.00 meters | 42.5 tonnes | 6 | 11.5 tonnes | Australia and New Zealand |
| Fallback | 2.14 meters | 1.83 meters | 5.19 meters | 5 tonnes | 2 | 2.5 tonnes | Other Countries and Regions |

## API Query Limits

- Following are the maximum number of `waypoints` allowed in a single request for both Fast and Flexible methods:
  - 50 when using HTTPS GET
  - 200 when using HTTPS POST
- 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.
- 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 [support@nextbillion.ai](mailto:support@nextbillion.ai) 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 a malformed hostname is used. |
| 413 | Request entity too large | This error is caused when the length of input request URI or the request body is too large. Please modify the request. Reach out to [support@nextbillion.ai](mailto:support@nextbillion.ai) if the issue still persists. |
| 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 [support@nextbillion.ai](mailto:support@nextbillion.ai) for an explanation. |