• Optimization
  • Navigation
  • Tracking
  • Maps
  • Places

Road Editor API

Enterprise Edition Only

The Nextbillion.ai Road Editor API is available only in a Enterprise plan. Please contact support if you wish to use this API and other premium services at [email protected].

Introduction

Nextbillion.ai’s Road Editor API is a service for the proprietary Road Restrictions Tool (RRT). With RRT, users can effortlessly set up a variety of restrictions on their maps, which include turn restrictions, speed limits, road closures, parking restrictions, and more. This proprietary platform enables users to enhance their maps with customized and detailed restrictions, providing a safer and more efficient navigation experience for drivers and pedestrians alike.


Let’s take a look at the methods provided available for the Road Editor API.

Create a new Restriction

This method is used to create new restrictions. Users can either create restrictions for a single road segment/node or multiple segments/nodes using a geofence. Using an HTTP POST request method in the Road Editor API, the users can create maxspeed, turn, fixedspeed, truck, closure and parking type of restrictions using a group of road nodes, segments or a geofence to indicate where the restriction should be applied, along with the attributes of the restriction like name, area, start time, end time, traveling mode etc.

Once a successful request is submitted, the service returns a response with the details of the new restriction such as its ID, type, and coordinates. The ID returned here can be used in other methods for carrying out different operations on the restrictions. This API method provides a flexible way for users to create new restriction groups catering to specific business needs for different geographic areas.

POST

{base URL}/restrictions/{restriction_type}?key={your_api_key}


Request Parameter

Loading..

Request Body

Loading..

Response Schema

Loading..

Sample API Request

1curl --location --request POST '{base URL}/restrictions/closure?key=<your_api_key>'
2--header 'Content-Type: application/json'
3--data-raw '{
4"name": "A Closure",
5"area": "singapore",
6"comment": "test comment",
7"mode": [
8"4w"
9],
10"segments": [
11{
12"from": 100849941810,
13"to": 100849942580
14}
15],
16"direction": "backward"
17}'

Sample API Response

1{
2 "id": 5092,
3 "name": "A Closure",
4 "area": "singapore",
5 "bbox": {
6 "maxLat": 1.32387825,
7 "maxLon": 103.8018043,
8 "minLat": 1.32387825,
9 "minLon": 103.8018043
10 },
11 "status": "active",
12 "repeatOn": null,
13 "comment": null,
14 "createAt": "2023-09-04T21:39:12.279Z",
15 "updateAt": "2023-09-04T21:39:12.279Z",
16 "startTime": null,
17 "endTime": null,
18 "mode": [

Update a Restriction

Use this method to update a restriction using its ID. The endpoint accepts a HTTPS PATCH request with the ID of the restriction as a path parameter and restriction values to be updated in the request body. Once the request is processed, the endpoint returns an HTTP status code as a response indicating whether the update was successful or not. If the update was successful, the updated attributes of the restriction are also present in the response.

PATCH

{base URL}/restrictions/{id}?key={your_api_key}

Request Parameter

Loading..

Request Body

Loading..

Response Schema

Loading..

Sample API Request

1curl --location --request PATCH 'https://nbai.nextbillion.io/road-editor/restrictions/11484/?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data '{
4 "name": "California 4w parking restriction",
5 "area": "california",
6 "status": "active",
7 "operator": "system",
8 "comment": "Updated restriction",
9 "mode": ["4w"],
10 "restriction_type": "closure",
11 "state": "enabled",
12 "segments": [
13 {
14 "from": 100024861907,
15 "to": 100025015462,
16 "coordinate": {
17 "lat": 37.7682622,
18 "lon": -122.4533587

Sample API Response

1{
2 "id": 11484,
3 "name": "California 4w parking restriction",
4 "area": "california",
5 "bbox": {
6 "min_lat": 37.7682622,
7 "min_lon": -122.4533587,
8 "max_lat": 37.7682622,
9 "max_lon": -122.4533587
10 },
11 "status": "active",
12 "repeat_on": null,
13 "operator": "api",
14 "comment": "Updated restriction",
15 "create_at": "2023-07-20T05:46:12.493Z",
16 "update_at": "2023-09-21T07:07:11.555Z",
17 "start_time": null,
18 "end_time": null,

Set state of a restriction by ID

Use this method to set the state of a restriction using its ID. The state of a restriction determines if the restriction can be used or not.

Users can set the state of a restriction to one of enabled, disabled or deleted by providing the ID of the restriction as a path parameter and the desired new state in the request body. The response to the API call will return an HTTP status code indicating the success or failure of the operation. If successful, the updated details of the restriction are also present in the responses.

PUT

{base URL}/restrictions/{id}/state?key={your_api_key}

Request Parameter

Loading..

Request Body

Loading..

Response Schema

Loading..

Sample API Request

1curl --location --request PUT '{base URL}/restrictions/11484/state?key=<your_api_key>' \
2--header 'Content-Type: application/json' \
3--data '{
4 "state":"enabled"
5}'

Sample API Response

1{
2 "id": 11484,
3 "name": null,
4 "area": "california",
5 "bbox": {
6 "max_lat": 37.7682622,
7 "max_lon": -122.4533587,
8 "min_lat": 37.7682494,
9 "min_lon": -122.4536157
10 },
11 "status": "active",
12 "repeat_on": null,
13 "comment": null,
14 "create_at": "2023-07-20T05:46:12.493Z",
15 "update_at": "2023-07-28T04:08:53.378Z",
16 "start_time": null,
17 "end_time": null,
18 "mode": [],

Get Restrictions by bbox

This endpoint is used to fetch the list of restrictions using a bounding box. This endpoint is useful when applications need to retrieve and display a specific set of restrictions within a defined geographic area.

Users can send a GET request with details of the bounding box defined by its geographic coordinates to get a list of restrictions that fall within that bounding box. Users can also filter the restrictions to be returned in the input by type or traveling mode and upon receiving a successful request, the service will return the qualifying restrictions along with their status and other properties. This endpoint can be useful in a variety of applications such as transportation management systems, mapping software etc.

GET

{base URL}/restrictions?key={your_api_key}

Request Parameter

Loading..

Response Schema

Loading..

Sample API Request:

1curl --location '{baseURL}/restrictions?key=<your_api_key>&min_lat=37.752941&min_lon=-122.508755&max_lon=-122.418713&max_lat=37.783974&restriction_type=closure&status=active'

Sample API Response:

1[
2 {
3 "id": 11469,
4 "name": null,
5 "area": "california",
6 "bbox": {
7 "max_lat": 37.770943,
8 "max_lon": -122.418926,
9 "min_lat": 37.770943,
10 "min_lon": -122.418926
11 },
12 "status": "active",
13 "repeat_on": null,
14 "comment": null,
15 "create_at": "2023-07-20T05:46:06.248Z",
16 "update_at": "2023-07-20T05:46:06.248Z",
17 "start_time": null,
18 "end_time": null,

Get Restrictions by ID

This endpoint is used to retrieve a specific restriction based on an ID, which is the unique identifier of the restriction. Users can send a GET request to this endpoint with a valid ID and the service will retrieve the restriction data associated with that ID and return it in the response. If no restriction is found with the specified ID, the service will return an error response with an appropriate message.

This endpoint is useful when a client wants to retrieve the details of a specific restriction, for example, to display the details on a map or to check the status of a certain restriction.

GET

{base URL}/restrictions/{id}?key={your_api_key}

Request Parameter

Loading..

Response Schema

Loading..

Sample API Request

1curl --location '{baseURL}/restrictions/9868?key=<your_api_key>'

Sample API Response

1{
2 "id": 9868,
3 "name": "A Max Speed Restriction",
4 "area": "singapore",
5 "bbox": {
6 "max_lat": 1.32249115,
7 "max_lon": 103.79859505,
8 "min_lat": 1.32208025,
9 "min_lon": 103.79757525
10 },
11 "status": "inactive",
12 "repeat_on": null,
13 "comment": null,
14 "create_at": "2023-07-05T13:20:36.396Z",
15 "update_at": "2023-09-19T15:57:46.306Z",
16 "start_time": null,
17 "end_time": null,
18 "mode": [

Get Restriction List

Use this method to get a list of restrictions. This method accepts an HTTPS GET request containing criteria to retrieve restrictions based on area, restriction type, status etc. Users can also set the maximum number of results to be retrieved and result offset value. This provides a useful feature to display paginated results in the end application.

Upon receiving a valid request the service returns a response containing the list of restrictions that meet the specified criteria. The response will include the restrictions themselves, as well as any metadata about the pagination, such as the total number of results, result offset values and the maximum number of results per “page”.

GET

{base URL}/restrictions/list?key={your_api_key}

Request Parameter

Loading..

Response Schema

Loading..

Sample API Request:

1curl --location '{baseURL}/restrictions/list?key=<your_api_key>&offset=0&limit=15'

Sample API Response:

1{
2 "data": [
3 {
4 "id": 115362,
5 "name": "Opening hours test",
6 "area": "singapore",
7 "bbox": {
8 "max_lat": 1.33301315,
9 "max_lon": 103.8027566,
10 "min_lat": 1.332526,
11 "min_lon": 103.8025735
12 },
13 "status": "inactive",
14 "repeat_on": "Tu,Sa 00:20-20:00",
15 "comment": null,
16 "create_at": "2023-07-20T20:18:40.348Z",
17 "update_at": "2023-09-19T12:00:03.874Z",
18 "start_time": null,

Delete a Restriction

Use this method to delete a specific restriction using its ID. Users need to provide the ID of the restriction as a path parameter. Once the API call is made, the system will delete the specified restriction group and return an HTTP status code indicating the success or failure of the operation along with ID and state of the deleted restriction. This endpoint is useful when users need to remove a specific restriction group that is no longer required.

DELETE

{base URL}/restrictions/{id}?key={your_api_key}

Request Parameter

Loading..

Response Schema

Loading..

Sample API Request:

1curl --location --request DELETE '{baseURL}/restrictions/9868?key=<your_api_key>'

Sample API Response

1{
2 "id": 9868,
3 "state": "deleted"
4}

Get available areas

Use this method to get the available areas for your road editor API. This method accepts a HTTPS GET request with a valid key to return all the available areas. This endpoint is useful when users need to identify the areas available for adding and/or managing restrictions.

GET

{base URL}/areas?key={your_api_key}

Request Parameter

Loading..

Response Schema

Loading..

Sample API Request:

1curl --location '{base URL}/areas?key=<your_api_key>'

Sample API Response

1[
2 {
3 "timezone": 8,
4 "name": "singapore",
5 "code": "singapore",
6 "modes": [
7 "4w"
8 ]
9 },
10 {
11 "timezone": -5,
12 "name": "california",
13 "code": "california",
14 "modes": [
15 "4w"
16 ]
17 }
18]

API Query Limits

  • Please check with your NextBillion account manager, sales representative or reach out at [email protected] for the following items:

    • Base URL of the API.

    • Correct value of area attribute.

  • 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.
API request is successful.
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 a malformed hostname is used.
422Could not process the request.
The restriction could not be applied due to an underlying map issue. Please check with [email protected] for more information.
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.