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

Request Body

Response Schema

Sample Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
    curl -X 'POST' \
    'https://api.nextbillion.io/clustering?key=<your_api_Key>' \
    -H 'accept: application/json' \
    -H 'Content-Type: application/json' \
    -d
    '{
    "description": "LA Test Clusters",
    "options": {
    "routing": {
        "mode": "truck",
    "truck_size": "500,200,300",
    "truck_weight": "5000"


    },
    "objective": {
        "travel_cost": "duration"
    }
    },
    "jobs": [
    {
        "id": 0,
        "quantity": 1,
        "location_index": 0,
        "description": "O-360437"
    },
    {
        "id": 1,
        "quantity": 1,
        "location_index": 1,
        "description": "O-140377"
    },
    {
        "id": 2,
        "quantity": 1,
        "location_index": 2,
        "description": "O-26976"
    },
    {
        "id": 3,
        "quantity": 3,
        "location_index": 3,
        "description": "O-297946"
    },
    {
        "id": 4,
        "quantity": 2,
        "location_index": 4,
        "description": "O-175367"
    },
    {
        "id": 5,
        "quantity": 3,
        "location_index": 5,
        "description": "O-250232"
    },
    {
        "id": 6,
        "quantity": 2,
        "location_index": 6,
        "description": "O-260537"
    },
    {
        "id": 7,
        "quantity": 3,
        "location_index": 7,
        "description": "O-205433"
    },
    {
        "id": 8,
        "quantity": 1,
        "location_index": 8,
        "description": "O-269948"
    },
    {
        "id": 9,
        "quantity": 1,
        "location_index": 9,
        "description": "O-6372"
    },
    {
        "id": 10,
        "quantity": 3,
        "location_index": 10,
        "description": "O-162188"
    },
    {
        "id": 11,
        "quantity": 1,
        "location_index": 11,
        "description": "O-88667"
    },
    {
        "id": 12,
        "quantity": 3,
        "location_index": 12,
        "description": "O-233477"
    },
    {
        "id": 13,
        "quantity": 3,
        "location_index": 13,
        "description": "O-230919"
    },
    {
        "id": 14,
        "quantity": 1,
        "location_index": 14,
        "description": "O-157783"
    },
    {
        "id": 15,
        "quantity": 2,
        "location_index": 15,
        "description": "O-40161"
    },
    {
        "id": 16,
        "quantity": 3,
        "location_index": 16,
        "description": "O-220592"
    },
    {
        "id": 17,
        "quantity": 2,
        "location_index": 17,
        "description": "O-66161"
    },
    {
        "id": 18,
        "quantity": 1,
        "location_index": 18,
        "description": "O-197718"
    },
    {
        "id": 19,
        "quantity": 2,
        "location_index": 19,
        "description": "O-324341"
    }
    
    ],
    "clusters": [
    {
        "id": 0,
        "max_quantity": 100
    },
    {
        "id": 1,
        "min_quantity": 20,
        "max_quantity": 100
    },
    {
        "id": 2,
        "min_quantity": 20,
        "max_quantity": 100
    },
    {
        "id": 3,
        "min_quantity": 20,
        "max_quantity": 100
    }
    ],
    "locations": [
    "34.0522,-118.2437",
    "34.0516,-118.2591",
    "34.0639,-118.3587",
    "34.0749,-118.2706",
    "34.0639,-118.2910",
    "34.0736,-118.2404",
    "34.0639,-118.2831",
    "34.0501,-118.2376",
    "34.0325,-118.2738",
    "34.0394,-118.2661",
    "34.0467,-118.2641",
    "34.0522,-118.2649",
    "34.0639,-118.2405",
    "34.0524,-118.3442",
    "34.0609,-118.3182",
    "34.0446,-118.2689",
    "34.0627,-118.2339",
    "34.0639,-118.3563",
    "34.0570,-118.2443",
    "34.0806,-118.3863"
    ]
    }'

Sample Response

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

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

Response Schema

Sample Request

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

Sample Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
{
    "id": "9a1408f62b3822c756f15bac0a17a720",
    "status": "ok",
    "description": "LA Test Clusters",
    "result": {
        "clusters": [
            {
                "id": 0,
                "quantity": 0.0,
                "cost": 0.0,
                "geometry": "",
                "job_ids": [],
                "center_location_index": null
            },
            {
                "id": 1,
                "quantity": 17.0,
                "cost": 1812.0,
                "geometry": "cg~nEfvzpUzlCcgDbLce@wmAcVccArg@cGv{D",
                "job_ids": [
                    0,
                    3,
                    5,
                    7,
                    12,
                    16,
                    18
                ],
                "center_location_index": 18
            },
            {
                "id": 2,
                "quantity": 13.0,
                "cost": 2126.0,
                "geometry": "kb|nEvu~pUfcEojBcj@co@gkAwj@{kA~tC?jp@",
                "job_ids": [
                    1,
                    4,
                    6,
                    8,
                    9,
                    10,
                    11,
                    15
                ],
                "center_location_index": 15
            },
            {
                "id": 3,
                "quantity": 9.0,
                "cost": 1911.0,
                "geometry": "wj_oEjiqqUfoDcfGct@oaDczBrhL",
                "job_ids": [
                    2,
                    13,
                    14,
                    17,
                    19
                ],
                "center_location_index": 17
            }
        ],
        "summary": {
            "cost": 5849.0,
            "unassigned_jobs": 0,
            "unassigned_quantity": 0
        },
        "unassigned": []
    }
}

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

Clustering API

Introduction

Clustering POST Method

Request Parameter

Request Body

Response Schema

Sample Request

Sample Response

Clustering GET Method

Request Parameter

Response Schema

Sample Request

Sample Response

API Query Limits

API Error Codes

PRODUCTS

SOLUTIONS

COMPARE

DEVELOPERS

GUIDES

RESOURCES

COMPANY

UNITED STATES

SINGAPORE