ohsome_aggregate_elements: Aggregate OSM elements

Description

Creates an ohsome_query object for OSM element aggregation

Usage

ohsome_aggregate_elements(
  boundary = NULL,
  aggregation = c("count", "length", "perimeter", "area"),
  return_value = c("absolute", "density", "ratio"),
  grouping = NULL,
  time = NULL,
  ...
)
ohsome_elements_count(boundary = NULL, ...)
ohsome_elements_length(boundary = NULL, ...)
ohsome_elements_perimeter(boundary = NULL, ...)
ohsome_elements_area(boundary = NULL, ...)

Value

An ohsome_query object. The object can be sent to the ohsome API with ohsome_post(). It consists of the following elements:

url: The URL of the endpoint.
encode: The way the information is encoded and then posted to the ohsome API. Set as "form".
body: The parameters of the query such as format, filter or bpolys.

Arguments

boundary

Bounding geometries specified by WGS84 coordinates in the order lon,lat. The geometries of sf are transformed to WGS84 if the CRS of the object is known. The following classes are supported:

sf with (MULTI)POLYGON geometries
sfc with (MULTI)POLYGON geometries
sfg with (MULTI)POLYGON geometries and WGS 84 coordinates
bbox created with sf::st_bbox() or tmaptools::bb()
matrix created with sp::bbox() or osmdata::getbb()
character providing textual definitions of bounding polygons, boxes or circles as allowed by the ohsome API (see ohsome API - Boundaries ):
- bboxes: WGS84 coordinates in the following format: "id1:lon1,lat1,lon2,lat2|id2:lon1,lat1,lon2,lat2|..." OR "lon1,lat1,lon2,lat2|lon1,lat1,lon2,lat2|..."
- bcircles: WGS84 coordinates + radius in meter in the following format: "id1:lon,lat,r|id2:lon,lat,r|..." OR "lon,lat,r|lon,lat,r|..."
- bpolys: WGS84 coordinates given as a list of coordinate pairs (as for bboxes) or GeoJSON FeatureCollection. The first point has to be the same as the last point and MultiPolygons are only supported in GeoJSON.
list of bbox, matrix or character. Bounding geometry types of all list elements must be the same. Does not work with GeoJSON FeatureCollections.

aggregation

character; aggregation type:

"count" returns the total number of elements. This is the default.
"length" returns the total length of elements in meters.
"perimeter" returns the total perimeter of elements in meters.
"area" returns the total area of elements in square meters.

return_value

character; the value to be returned by the ohsome API:

"absolute" returns the absolute number, length, perimeter or area of elements. This is the default.
"density" returns the number, length, perimeter or area (in meters!) of elements per square kilometer.
"ratio" returns an absolute value for elements satisfying the filter argument, an absolute value2 for elements satisfying the filter2 argument, and the ratio of value2 to value.

grouping

character; group type(s) for grouped aggregations (only available for queries to aggregation endpoints). The following group types are available:

"boundary" groups the result by the given boundaries that are defined through any of the boundary query parameters.
"key" groups the result by the given keys that are defined through the groupByKeys query parameter.
"tag" groups the result by the given tags that are defined through the groupByKey and groupByValues query parameters.
"type" groups the result by OSM element type.
c("boundary", "tag") groups the result by the given boundaries and tags.

Not all of these group types are accepted by all of the aggregation endpoints. Check Grouping for available group types.

time

character; time parameter of the query (see Supported time formats).

...

Parameters of the request to the ohsome API endpoint.

Details

ohsome_aggregate_elements() creates an ohsome_query object for OSM element aggregation. ohsome_elements_count(), ohsome_elements_length(), ohsome_elements_perimeter() and ohsome_elements_area() are wrapper functions for specific aggregation endpoints. Boundary objects are passed via set_boundary() into ohsome_boundary().

Examples

Run this code

# \donttest{
# Count of breweries in Franconia
ohsome_aggregate_elements(
    mapview::franconia, 
    aggregation = "count", 
    filter = "craft=brewery",
    time = "2022-01-01"
)

ohsome_elements_count(
    mapview::franconia, 
    filter = "craft=brewery",
    time = "2022-01-01"
)

# Monthly counts of breweries in Franconia from 2012 to 2022
ohsome_elements_count(
    mapview::franconia, 
    filter = "craft=brewery", 
    time = "2012/2022/P1M"
)

# Count of breweries per district of Franconia
ohsome_elements_count(
    mapview::franconia, 
    filter = "craft=brewery", 
    grouping = "boundary",
    time = "2022-01-01"
)

# Number of breweries per square kilometer
ohsome_elements_count(
    mapview::franconia, 
    filter = "craft=brewery", 
    return_value = "density",
    time = "2022-01-01"
)

# Proportion of breweries that are microbreweries
ohsome_elements_count(
    mapview::franconia, 
    filter = "craft=brewery", 
    filter2 = "craft=brewery and microbrewery=yes", 
    return_value = "ratio",
    time = "2022-01-01"
) 

# Total length of highway elements in Franconia
ohsome_elements_length(
    mapview::franconia, 
    filter = "highway=* and geometry:line",
    time = "2022-01-01"
)
# }