Clustering Tile API
The API allows you to cluster the bandmath layer using one of the proposed algorithms.
What is KMeans Clustering
K-means clustering is one of the simplest and popular unsupervised machine learning algorithms. Typically, unsupervised algorithms make inferences from datasets using only input data without referring to known, or labelled, outcomes. The objective of K-means is simple: group similar data points together and discover underlying patterns. To achieve this objective, K-means looks for a fixed number (k) of clusters in a dataset. You’ll define a target number k, which refers to the number of centroids you need in the dataset. A centroid is the imaginary or real location representing the center of the cluster. Every data point is allocated to each of the clusters through reducing the in-cluster sum of squares. In other words, the K-means algorithm identifies k number of centroids, and then allocates every data point to the nearest cluster, while keeping the centroids as small as possible. The ‘means’ in the K-means refers to averaging of the data; that is, finding the centroid.
API to Save Clustering Options into DB
Save clustering options into a data base. This API is handy to use when clustering by AOI is required. Returns options id to use with the tile API
curl -i -X POST 'https://api-connect.eos.com/api/render/clustering_options/?api_key=<your_api_key>' \
-H 'Content-Type: application/json' \
-d \
'{
"calibrate":1,
"clusters_no":2,
"geometry":{
"coordinates":[
[
[
-96.957586,
32.884453
],
[
-96.955869,
32.888489
],
[
-96.947522,
32.885426
],
[
-96.950655,
32.88074
],
[
-96.955397,
32.881696
],
[
-96.957586,
32.884453
]
]
],
"type":"Polygon"
},
"method":"kmeans",
"min_area":2000
}
'
The above commands returns the following JSON with results
{
"id": "5037afcd30eeca50787d195567cd5661"
}
Usage Example - Clustering Options Saved Using API clustering_options
GET https://api-connect.eos.com/api/render/<Sensor>/clustering_band/<viewID>/<band>?clustering_ref=<ID clustering reference>?api_key=<your_api_key>
GET https://api-connect.eos.com/api/render/S2/clustering_band/14-S-PB-2024-2-8-0/NDVI?clustering_ref=8277998b9b7b9b04d8615d50d6b90d7d
The above commands returns the following JSON with results
{
"NDVI": [
[
1,
[
0.17183180927023528
]
],
[
2,
[
0.40492993671394995
]
]
]
}
Format of the view ID must be changed from this S2/14/S/PB/2024/2/8/0 to this 14-S-PB-2024-2-8-0
HTTP Request
POST https://api-connect.eos.com/api/render/clustering_options/?api_key=<your_api_key>
Form parameters
| Parameter | Description |
|---|---|
| clusters_no | (optional) number of classes. Valid range from 2 to 19. Default: 5 |
| method | (optional) clustering method. Valid methods: “kmeans”. Default: “kmeans” |
| min_area | (optional) minimal size of a cluster in square meters. If this value is set then postprocessing is applied to the raster layer. Clusters of size smaller this MIN_AREA are dissolved. Valid range from 1000 to 999999. Default: no filtering by area |
| calibrate | (optional) if True (or 1), band data is converted to ToA Reflectance (or to At-Satellite Brightness Temperature for TIRS) prior to evaluating the band math (See Radiometric Correction). Default: 0 |
| geometry | (optional) if provided then calculate centers of clusters by data inside an area of interest in GeoJSON format. Supported geometry types: “Polygon”, “MultiPolygon”. Default: null (clustering shall be calculated for a full scene) |
| bbox | (optional) if provided then calculate centers of clusters by data inside of a bounding box (bbox). Bbox is defined in EPSG:4326 as [miny,minx,maxy,maxx]. Default: null (clustering shall be calculated for a full scene) |
| connectivity | (optional) connectivity used when calculating the area of clusters. Valid values: 4, 8. Default: 8 |
Query parameters
| Parameter | Value | Description |
|---|---|---|
| api_key | (Required) Apikey retrieved from developer portal |
API to Calculate Kmeans centroids
Evaluate centers of clusters for a bandmath layer.
curl -i 'https://api-connect.eos.com/api/render/S2/clustering_band/13-R-EL-2024-2-9-0/NDVI?CLUSTERING=kmeans&clusters_no=8&CALIBRATE=1'
The above commands returns the following JSON with results
{
"NDVI": [
[
1,
[
-0.021661379520570127
]
],
[
2,
[
0.007595605051199972
]
],
[
3,
[
0.018977683176406638
]
],
[
4,
[
0.027151177417459857
]
],
[
5,
[
0.03826579194579709
]
],
[
6,
[
0.05605972316193032
]
],
[
7,
[
0.08716820055316339
]
],
[
8,
[
0.14148646901962877
]
]
]
}
HTTP Request
POST https://api-connect.eos.com/api/render/<sensor>/clustering_band/<scene_id>/<band>?CLUSTERING=kmeans&clusters_no=<number>&CALIBRATE=<number>api_key=<your_api_key>
Form parameters
| Parameter | Description |
|---|---|
| sensor | S2 or L8/L9 |
| scene_id | For Landsat 8 or 9 LC08_L1TP_197023_20181210_20181210_01_RT |
scene’s identificator. scene_id is constructed by removing the short-name-of-the-sensor prefix from the view_id returned by the Search API. Examples: “10/S/EG/2017/3/1/0”, “LE70420362017095EDC00”, “115/S1A_IW_GRDH_1SDV_20161201T141548_20161201T141617_014187_016EBB_F627” etc band |Alias of index like NDVI or bands like (B5-B4)/(B5+B4) | band combination expression
Query parameters
| Parameter | Value | Description |
|---|---|---|
| api_key | (Required) Apikey retrieved from developer portal |