Use Clustering - hexbin

This section describes how to retrieve features from Data Hub in a hexbin clustered form. Two different clustering modes, "hexbin" and "quadbin", are available.

"quadbin" - gives the amount of features in tiles and subtiles. Purpuse is to give a fast overview on dataset locations on lower zoom levels. The quadbins corresponds to the webmercator tiling scheme.
"hexbin" - gives the amount of feature in a hexagonal tiling. Beside the amount of the features per hexbin it provides statistics (min, max, avg, median) on a user-defined property.

hexbin

Get clustered Features in a tile

While retrieving features from Spaces inside a tile you can use "hexbin" clustering to visualize your data as hexagons. Each hexagon represents the features of the area it covers. Additional statistical information about one property of your data can be evaluated and returned as properties of the returned hexagonal features.

The hexbin algorithm divides the world in hexagonal "bins" on a specified resolution. Each hexagon has an address being described by the H3 addressing scheme. For more information on that topic see: https://eng.uber.com/h3/

Request

Try in Swagger

GET /spaces/{spaceId}/tile/{type}/{tileId}?clustering=hexbin&clustering.resolution={aNumber}&clustering.property={aPropertyName}

The following clustering related parameters can be passed and combined with others ( e.g. tags, clip, feature filtering).

Parameter	Type	Mandatory	Meaning
absoluteResolution	Number	NO	integer, The H3 hexagon resolution [0,13], default:( s.b. Default Resolution for zoomlevel )
relativeResolution	Number	NO	integer value [-2,2] to be added to current used resolution
property	String	NO	A property of the original features for which to calculate statistics
pointmode	Boolean	NO	retuns the centroid of hexagons as geojson feature
singlecoord	Boolean	NO	force to evaluate the first object coordinate only (default: false)
sampling	String	NO	samplingratio of underlying dataset values [off, low, lowmed, med, medhigh, high] (default: off) off ~ (1/1), low ~ (1/8), lowmed ~ (1/32), med ~ (1/128), medhigh ~ (1/1024), high ~ (1/4096))

Response

{
    "type": "FeatureCollection",
    "features": [
        {
            "type": "Feature",
            "properties": {
                "kind" : "H3",
                "kind_detail" : "858b1303fffffff",
                "resolution": 5,
                "level": 7,
                "aggregation": {
                    "aPropertyName": {  // only if a clustering.property={aPropertyName} is specified. If not specified field "qty" is
                                        // written on this object-level (e.g. properties.aggregation.qty )
                        "avg": 30.05000,
                        "max": 44.1,
                        "min": 16,
                        "qty": 2,
                        "sum": 60.1
                    }
                },
            "centroid": [ ... ], // only if clustering.pointmode = false|null
            "hexagon": [ ... ]  // only if clustering.pointmode = true
            },
            "geometry": {...},
        },
        ......
        ......
        {
            "type": "Feature",
            "properties": {
                "kind" : "H3",
                 "kind_detail" : "881f1d4a81fffff",
                    ....
            },
            "geometry": {...}
        }
    ]
}

Miscellaneous

Default Resolution for zoomlevel

The parameter clusterning.absoluteResolution specifies the size of the hexagons wanted. ( s. https://h3geo.org/docs/core-library/restable ) The default Resolution is balanced to suit size and performance of hexbin calculations per tile for normal amounts of data. Various parameters like amount, density, distribution and object size plays a role in performance time. Higher resolution specific tile level, up to ( default + 2 ) can be specified on experimental base, depending on datasize. If the value of clusterning resolution exeeds the maximum value for tile level, the maximum resolution will be used instead.

Zoomlevel	Default H3 Resolution
0	2
1	2
2	2
3	2
4	3
5	4
6	4
7	5
8	6
9	6
10	7
11	8
12	9
13	9
14	10
15	11
16	11
17	12
18	13
19	13
20	13
21	13
22	13

hexbin (H3)