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.

POST

https://api.nextbillion.io/clustering?key={your_api_key}


Request Parameter

Loading..

Request Body

Loading..

Response Schema

Loading..

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.

GET

https://api.nextbillion.io/clustering/result?id={id}&key={your_api_key}


Request Parameter

Loading..

Response Schema

Loading..

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

Response CodeDescriptionAdditional 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.

422

Could not process the request.

The clustering request could not be completed successfully for the given set of locations or parameter configuration. Please check the API error message for more details.

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 [email protected] for an explanation.

© 2024 NextBillion.ai all rights reserved.