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
Loading...Request Body
Loading...Response Schema
Loading...Sample Request
1 curl -X 'POST' \
2 'https://api.nextbillion.io/clustering?key=<your_api_Key>' \
3 -H 'accept: application/json' \
4 -H 'Content-Type: application/json' \
5 -d
6 '{
7 "description": "LA Test Clusters",
8 "options": {
9 "routing": {
10 "mode": "truck",
11 "truck_size": "500,200,300",
12 "truck_weight": "5000"
13
14
15 },
16 "objective": {
17 "travel_cost": "duration"
18 }
19 },
20 "jobs": [
21 {
22 "id": 0,
23 "quantity": 1,
24 "location_index": 0,
25 "description": "O-360437"
26 },
27 {
28 "id": 1,
29 "quantity": 1,
30 "location_index": 1,
31 "description": "O-140377"
32 },
33 {
34 "id": 2,
35 "quantity": 1,
36 "location_index": 2,
37 "description": "O-26976"
38 },
39 {
40 "id": 3,
41 "quantity": 3,
42 "location_index": 3,
43 "description": "O-297946"
44 },
45 {
46 "id": 4,
47 "quantity": 2,
48 "location_index": 4,
49 "description": "O-175367"
50 },
51 {
52 "id": 5,
53 "quantity": 3,
54 "location_index": 5,
55 "description": "O-250232"
56 },
57 {
58 "id": 6,
59 "quantity": 2,
60 "location_index": 6,
61 "description": "O-260537"
62 },
63 {
64 "id": 7,
65 "quantity": 3,
66 "location_index": 7,
67 "description": "O-205433"
68 },
69 {
70 "id": 8,
71 "quantity": 1,
72 "location_index": 8,
73 "description": "O-269948"
74 },
75 {
76 "id": 9,
77 "quantity": 1,
78 "location_index": 9,
79 "description": "O-6372"
80 },
81 {
82 "id": 10,
83 "quantity": 3,
84 "location_index": 10,
85 "description": "O-162188"
86 },
87 {
88 "id": 11,
89 "quantity": 1,
90 "location_index": 11,
91 "description": "O-88667"
92 },
93 {
94 "id": 12,
95 "quantity": 3,
96 "location_index": 12,
97 "description": "O-233477"
98 },
99 {
100 "id": 13,
101 "quantity": 3,
102 "location_index": 13,
103 "description": "O-230919"
104 },
105 {
106 "id": 14,
107 "quantity": 1,
108 "location_index": 14,
109 "description": "O-157783"
110 },
111 {
112 "id": 15,
113 "quantity": 2,
114 "location_index": 15,
115 "description": "O-40161"
116 },
117 {
118 "id": 16,
119 "quantity": 3,
120 "location_index": 16,
121 "description": "O-220592"
122 },
123 {
124 "id": 17,
125 "quantity": 2,
126 "location_index": 17,
127 "description": "O-66161"
128 },
129 {
130 "id": 18,
131 "quantity": 1,
132 "location_index": 18,
133 "description": "O-197718"
134 },
135 {
136 "id": 19,
137 "quantity": 2,
138 "location_index": 19,
139 "description": "O-324341"
140 }
141
142 ],
143 "clusters": [
144 {
145 "id": 0,
146 "max_quantity": 100
147 },
148 {
149 "id": 1,
150 "min_quantity": 20,
151 "max_quantity": 100
152 },
153 {
154 "id": 2,
155 "min_quantity": 20,
156 "max_quantity": 100
157 },
158 {
159 "id": 3,
160 "min_quantity": 20,
161 "max_quantity": 100
162 }
163 ],
164 "locations": [
165 "34.0522,-118.2437",
166 "34.0516,-118.2591",
167 "34.0639,-118.3587",
168 "34.0749,-118.2706",
169 "34.0639,-118.2910",
170 "34.0736,-118.2404",
171 "34.0639,-118.2831",
172 "34.0501,-118.2376",
173 "34.0325,-118.2738",
174 "34.0394,-118.2661",
175 "34.0467,-118.2641",
176 "34.0522,-118.2649",
177 "34.0639,-118.2405",
178 "34.0524,-118.3442",
179 "34.0609,-118.3182",
180 "34.0446,-118.2689",
181 "34.0627,-118.2339",
182 "34.0639,-118.3563",
183 "34.0570,-118.2443",
184 "34.0806,-118.3863"
185 ]
186 }'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
Loading...Response Schema
Loading...Sample Request
1curl --location --request GET 'https://api.nextbillion.io/clustering/result?id=9a1408f62b3822c756f15bac0a17a720&key=<your_api_key>'
2Sample Response
1{
2 "id": "9a1408f62b3822c756f15bac0a17a720",
3 "status": "ok",
4 "description": "LA Test Clusters",
5 "result": {
6 "clusters": [
7 {
8 "id": 0,
9 "quantity": 0.0,
10 "cost": 0.0,
11 "geometry": "",
12 "job_ids": [],
13 "center_location_index": null
14 },
15 {
16 "id": 1,
17 "quantity": 17.0,
18 "cost": 1812.0,
19 "geometry": "cg~nEfvzpUzlCcgDbLce@wmAcVccArg@cGv{D",
20 "job_ids": [
21 0,
22 3,
23 5,
24 7,
25 12,
26 16,
27 18
28 ],
29 "center_location_index": 18
30 },
31 {
32 "id": 2,
33 "quantity": 13.0,
34 "cost": 2126.0,
35 "geometry": "kb|nEvu~pUfcEojBcj@co@gkAwj@{kA~tC?jp@",
36 "job_ids": [
37 1,
38 4,
39 6,
40 8,
41 9,
42 10,
43 11,
44 15
45 ],
46 "center_location_index": 15
47 },
48 {
49 "id": 3,
50 "quantity": 9.0,
51 "cost": 1911.0,
52 "geometry": "wj_oEjiqqUfoDcfGct@oaDczBrhL",
53 "job_ids": [
54 2,
55 13,
56 14,
57 17,
58 19
59 ],
60 "center_location_index": 17
61 }
62 ],
63 "summary": {
64 "cost": 5849.0,
65 "unassigned_jobs": 0,
66 "unassigned_quantity": 0
67 },
68 "unassigned": []
69 }
70}API Query Limits
-
The maximum number of location coordinates that can be added to the
locationobject is 1000. -
In
routingandjobobjects:-
The values provided for
idfields should be non-zero positive integers. -
The values provided for parameters like
quantity,max_quantity,min_quantity,location_index, andcenter_location_indexshould be a non-negative integer.
-
-
Maximum dimensions allowed for
truck_sizeare 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. -
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 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. |
| 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. |
