# Clustering

It solves the “capacity clustering problem” by assigning a set of customers to a given number of distinct groups (called clusters).
The API “clusters” by minimizing the total distance from each individual customer to its designated group median.
It can also consider minimum and maximum capacity restrictions for each group.

Clustering can be used in many practical applications.
For example, it can help to plan territories, i.e. territory optimization for field teams with large territories for field workers,
or to solve large vehicle routing problems (VRP).

Try Clustering in our [API Explorer](https://explorer.graphhopper.com/?endpoint=cluster)!

The idea is to divide a certain number of customers, a pre-specified number of clusters. As already written above, a distribution is sought that minimizes the total cost (e.g. distance or time or a function of distance and time).
We currently support two approaches.

1. You can simply define a certain number of clusters via configuration ("clustering" with empty set of "clusters") and additionally how many customers should be in such a cluster.
This is defined by an upper and lower limit ("min_quantity" and "max_quantity). The algorithm then searches for suitable clusters and divides the customers into these clusters.

2. You can explicitly define clusters via "clusters". In this way, each individual cluster can be defined.
This approach not only allows each cluster to have its own capacity upper and lower bound, but each cluster can also be assigned a fixed cluster center.
In contrast to 1. the algorithm then does not search for a suitable center, but assigns the customers given the fixed centers to each cluster. Note that if you define clusters
explicitly, any configuration of "clustering" will be overwritten by these explicit clusters.


## Solve a clustering problem

 - [POST /cluster](https://docs.graphhopper.com/openapi/clustering/solveclusteringproblem.md): 
The Cluster endpoint is used with a POST request towards
. The solution will be provided in the JSON response.
Please note that for problems that take longer than 10 seconds a bad request error is returned.
In this case please use the asynchronous Batch Cluster Endpoint instead.


## Submit a clustering job

 - [POST /cluster/calculate](https://docs.graphhopper.com/openapi/clustering/asyncclusteringproblem.md): 
Prefer the synchronous endpoint and use this Batch Cluster endpoint for
long running problems only. The work flow is asynchronous:

- send a POST request towards  and fetch the job_id.
- poll the solution every 500ms until it gives . Do this with a GET request
  towards .


## Retrieve solution of a clustering job

 - [GET /cluster/solution/{jobId}](https://docs.graphhopper.com/openapi/clustering/getclustersolution.md): This endpoint returns the solution of the clustering problems submitted to the Batch Cluster endpoint.
You can fetch it with the job_id, you have been sent.