Road Editor API

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.

Request Parameter

Request Body

Response Schema

Sample API Request

1
curl --location --request POST '{base URL}/restrictions/closure?key=<your_api_key>'
2
--header 'Content-Type: application/json'
3
--data-raw  '{...}'

Sample API Response

1
{
2
  "id": 5092,
3
  "name": "A Closure",
4
  "area": "singapore",
5
  "bbox": "{...}",
6
  }

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.

Request Parameter

Request Body

Response Schema

Sample API Request

1
curl --location --request PATCH 'https://nbai.nextbillion.io/road-editor/restrictions/11484/?key=<your_api_key>' --header 'Content-Type: application/json' --data  "{...}"

Sample API Response

1
{
2
  "id": 5092,
3
  "name": "A Closure",
4
  "area": "singapore",
5
  "bbox": "{...}",
6
  }

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.

Request Parameter

Request Body

Response Schema

Sample API Request

1
curl --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
  }

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.

Request Parameter

Response Schema

Sample API Request:

1
curl --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
  "id": 11484,
3
  "name": null,
4
  "area": "california",
5
  "bbox": "{...}",
6
  }

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.

Request Parameter

Response Schema

Sample API Request

1
curl --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
  }

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

Request Parameter

Response Schema

Sample API Request:

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

Sample API Response:

1
{
2
  "data": "[...]",
3
  }

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.

Request Parameter

Response Schema

Sample API Request:

1
curl --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.

Request Parameter

Response Schema

Sample API Request:

1
curl --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