Clustering API

Introduction

The Clustering API is designed to facilitate the bundling of orders or jobs based on a set of user-defined constraints. The API employs a clustering technique for selecting geo-locations within each cluster in a manner that minimizes the total distance or duration required to service each cluster from a predetermined central location. In situations where a central location is not specified, the API is equipped with an automatic algorithm that identifies an appropriate central location based on the constraints provided in the input problem. This API enables businesses to streamline their logistics operations and optimize their supply chain management processes.

Clustering POST Method

Clustering API uses a POST method to accept an input payload with rules for bundling the jobs together along with their properties and locations. The result is a unique task ID that can be used in the Clustering GET Method to retrieve the clustering result.

Request Parameter

Request Body

Response Schema

Sample Request

1
curl -X 'POST'     'https://api.nextbillion.io/clustering?key=<your_api_Key>'     -H 'accept: application/json'     -H 'Content-Type: application/json'     -d
2
    '{...}'

Sample Response

1
{
2
    "id": "9a1408f62b3822c756f15bac0a17a720",
3
    "msg": "Clustering job created",
4
    "status": "Ok",
5
    "warning": [
6
        "truck_size only work with option=flexible and mode=truck",
7
        "truck_weight only work with option=flexible and mode=truck"
8
    ]
9
}

Clustering GET Method

The GET method retrieves the result of a clustering task submitted previously using the Clustering POST method. The API returns a response object containing the result of the clustering task, including the optimal clusters and their respective jobs, as well as other metadata related to the task.

Request Parameter

Response Schema

Sample Request

1
curl --location --request GET 'https://api.nextbillion.io/clustering/result?id=9a1408f62b3822c756f15bac0a17a720&key=<your_api_key>'

Sample Response

1
{
2
    "id": "9a1408f62b3822c756f15bac0a17a720",
3
    "status": "ok",
4
    "description": "LA Test Clusters",
5
    "result": '{...}'
6
    }

API Query Limits

• The maximum number of location coordinates that can be added to the location object is 1000.

• In routing and job objects:

  • The values provided for id fields should be non-zero positive integers.

  • The values provided for parameters like quantity, max_quantity, min_quantity, location_index, and center_location_index should be a non-negative integer.

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

• When using the service to create clusters automatically based on max_cluster_radius, the service will not create clusters containing less than 2 jobs.

• 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