Grouping

The grouping end points are available for every aggregation resource (count, length, perimeter, area). They are accessed through an additional /groupBy/(grouping-type) resource. Group types are boundary, key, tag and type.

Note

For /elements/(aggregation)/density the group types boundary, tag and type are available.

For POST requests the fields are given analogous to GET requests. When you just have a smaller set of spatial parameters, a GET request fits perfectly. POST mostly makes sense when you start to use GeoJSON as input geometries.

Boundary

Groups the result by the given boundaries that are defined through any of the boundary query parameters.

POST /elements/(aggregation)/groupBy/boundary
Parameters:

  • aggregation – aggregation type, one of area, count, length, perimeter

Query Parameters:

Key

Groups the result by the given keys that are defined through the groupByKeys query parameter.

POST /elements/(aggregation)/groupBy/key
Parameters:

  • aggregation – aggregation type, one of area, count, length, perimeter

Query Parameters:

  • <params> – see query-parameters at /elements(aggregation) endpoint

  • groupByKeys – OSM key(s) given as a comma separated list (e.g. “key1,key2”), mandatory, no default value

The result of this grouping will contain separate results for each key specified in groupByKeys and - if applicable - a remainder for all objects that fulfilled the filter but had none of the ‘groupByKeys’. Note that if more than one key is defined in groupByKeys, the sum of the result values can be higher than the total result of a simple (not-grouped) aggregation: this is because an element can match none, one, or multiple of the specified groupByKeys.

Here you can find a groupByKey example.

Note

The groupByKeys query parameter is only available for the /groupBy/key endpoint.

Note

The /groupBy/key endpoint is not available for /elements/(aggregation)/density.

Tag

Groups the result by the given tags that are defined through the groupByKey and groupByValues query parameters.

POST /elements/(aggregation)/groupBy/tag
Parameters:

  • aggregation – aggregation type, one of area, count, length, perimeter

Query Parameters:

  • <params> – see query-parameters at /elements(aggregation) endpoint

  • groupByKey – OSM key e.g.: ‘highway’; mandatory, no default value, only one groupByKey can be defined

  • groupByValues – OSM value(s) for the specified key given as a comma separated list (e.g. “value1,value2”), default: no value

The result of this grouping will contain separate results for each specified tag having the key defined in groupByKey and a value as given in groupByValue. A remainder object contains results for all elements which do not match any of these tags, if there are any. If the groupByValues parameter is left empty, all occuring tag values which are found in the filtered OSM data will be present in the output.

Here you can find a groupByTag example.

Note

The groupByKey and the groupByValues query parameters are only available for the /groupBy/tag endpoint.

Type

Groups the result by the given OSM, or simple feature types that are defined through the types parameter.

POST /elements/(aggregation)/groupBy/type
Parameters:

  • aggregation – aggregation type, one of area, count, length, perimeter

Query Parameters:

Boundary and Tag

Groups the result by the given boundary and the tags.

POST /elements/(aggregation)/groupBy/boundary/groupBy/tag
Parameters:

  • aggregation – aggregation type, one of area, count, length, perimeter

Query Parameters:

  • <params> – see query-parameters at /elements(aggregation) endpoint

  • groupByKey – OSM key e.g.: ‘highway’; mandatory, no default value, only one groupByKey can be defined

  • groupByValues – OSM value(s) for the specified key given as a comma separated list (e.g. “value1,value2”), default: no value

The result of this grouping will contain separate results for each conbination of boundary and OSM tag. The semantics are otherwise the same as for the individual groupings described above.

Here you can find a groupByBoundaryGroupByTag example.