Skip to contents

Reverse geocoding

Source: R/reverse.R
reverse.Rd

Reverse geocode a set of points to retrieve their corresponding place names. To geocode a place name or an address, see unstructured or structured geocoding.

Usage

reverse(
  .data,
  radius = NULL,
  limit = 3,
  lang = "en",
  osm_tag = NULL,
  layer = NULL,
  locbias = NULL,
  locbias_scale = NULL,
  zoom = NULL,
  distance_sort = TRUE,
  progress = interactive()
)

Arguments

.data

A dataframe or list with names lon and lat, or an sfc or sf object containing point geometries.

radius

Numeric specifying the range around the points in .data that is used for searching.

limit

Number of results to return. Defaults to 3.

lang

Language of the results.

osm_tag

Character string giving an OSM tag to filter the results by. See details.

layer

Character string giving a layer to filter the results by. Can be one of "house", "street", "locality", "district", "city", "county", "state", "country", or "other".

locbias

Numeric vector of length 2 or any object that can be coerced to a length-2 numeric vector (e.g. a list or sfg object). Specifies a location bias for geocoding in the format c(lon, lat). Geocoding results are biased towards this point. The radius of the bias is controlled through zoom and the weight of place prominence through location_bias_scale.

locbias_scale

Numeric vector specifying the importance of prominence in locbias. A higher prominence scale gives more weight to important places. Defaults to 0.2.

zoom

Numeric specifying the radius for which the locbias is effective. Corresponds to the zoom level in OpenStreetMap. The exact relation to locbias is \(0.25\text{ km} \cdot 2^{(18 - \text{zoom})}\). Defaults to 16.

distance_sort

If TRUE, sorts the reverse geocoding results based on the distance to the input point. Defaults to TRUE.

progress

If TRUE, shows a progress bar for longer queries.

Value

An sf dataframe or tibble containing the following columns:

  • idx: Internal ID specifying the index of the texts parameter.

  • osm_type: Type of OSM element, one of N (node), W (way), R (relation), or P (polygon).

  • osm_id: OpenStreetMap ID of the matched element.

  • country: Country of the matched place.

  • city: City of the matched place.

  • osm_key: OpenStreetMap key.

  • countrycode: ISO2 country code.

  • housenumber: House number, if applicable.

  • postcode: Post code, if applicable.

  • locality: Locality, if applicable.

  • street: Street, if applicable.

  • district: District name, if applicable.

  • osm_value: OpenStreetMap tag value.

  • name: Place name.

  • type: Layer type as described for the layer parameter.

  • extent: Boundary box of the match.

Details

Filtering by OpenStreetMap tags follows a distinct syntax explained on https://github.com/komoot/photon. In particular:

  • Include places with tag: key:value

  • Exclude places with tag: !key:value

  • Include places with tag key: key

  • Include places with tag value: :value

  • Exclude places with tag key: !key

  • Exclude places with tag value: :!value

Examples

# an instance must be mounted first
photon <- new_photon()

# works with sf objects
sf_data <- sf::st_sfc(sf::st_point(c(8, 52)), sf::st_point(c(7, 52)))
reverse(sf_data)
#> Simple feature collection with 6 features and 17 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 6.995134 ymin: 51.99511 xmax: 7.99941 ymax: 52.00153
#> Geodetic CRS:  WGS 84
#> # A tibble: 6 × 18
#>     idx  osm_id country city  countrycode postcode county type  osm_type osm_key
#>   <int>   <dbl> <chr>   <chr> <chr>       <chr>    <chr>  <chr> <chr>    <chr>  
#> 1     1  2.80e7 Germany Sass… DE          48336    Kreis… stre… W        highway
#> 2     1  9.64e9 Germany Sass… DE          48336    Kreis… house N        histor…
#> 3     1  3.35e8 Germany Sass… DE          48336    Kreis… house W        buildi…
#> 4     2  4.21e9 Germany Stad… DE          48703    Kreis… house N        place  
#> 5     2  4.21e9 Germany Stad… DE          48703    Kreis… house N        place  
#> 6     2  9.83e9 Germany Stad… DE          48703    Kreis… loca… N        place  
#> # ℹ 8 more variables: housenumber <chr>, street <chr>, district <chr>,
#> #   osm_value <chr>, name <chr>, state <chr>, extent <list>,
#> #   geometry <POINT [°]>

# ... but also with simple dataframes
df_data <- data.frame(lon = c(8, 7), lat = c(52, 52))
reverse(df_data)
#> Simple feature collection with 6 features and 17 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 6.995134 ymin: 51.99511 xmax: 7.99941 ymax: 52.00153
#> Geodetic CRS:  WGS 84
#> # A tibble: 6 × 18
#>     idx  osm_id country city  countrycode postcode county type  osm_type osm_key
#>   <int>   <dbl> <chr>   <chr> <chr>       <chr>    <chr>  <chr> <chr>    <chr>  
#> 1     1  2.80e7 Germany Sass… DE          48336    Kreis… stre… W        highway
#> 2     1  9.64e9 Germany Sass… DE          48336    Kreis… house N        histor…
#> 3     1  3.35e8 Germany Sass… DE          48336    Kreis… house W        buildi…
#> 4     2  4.21e9 Germany Stad… DE          48703    Kreis… house N        place  
#> 5     2  4.21e9 Germany Stad… DE          48703    Kreis… house N        place  
#> 6     2  9.83e9 Germany Stad… DE          48703    Kreis… loca… N        place  
#> # ℹ 8 more variables: housenumber <chr>, street <chr>, district <chr>,
#> #   osm_value <chr>, name <chr>, state <chr>, extent <list>,
#> #   geometry <POINT [°]>

# limit search radius to 10m
reverse(df_data, radius = 10)
#> Simple feature collection with 6 features and 17 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 6.995134 ymin: 51.99511 xmax: 7.99941 ymax: 52.00153
#> Geodetic CRS:  WGS 84
#> # A tibble: 6 × 18
#>     idx  osm_id country city  countrycode postcode county type  osm_type osm_key
#>   <int>   <dbl> <chr>   <chr> <chr>       <chr>    <chr>  <chr> <chr>    <chr>  
#> 1     1  2.80e7 Germany Sass… DE          48336    Kreis… stre… W        highway
#> 2     1  9.64e9 Germany Sass… DE          48336    Kreis… house N        histor…
#> 3     1  3.35e8 Germany Sass… DE          48336    Kreis… house W        buildi…
#> 4     2  4.21e9 Germany Stad… DE          48703    Kreis… house N        place  
#> 5     2  4.21e9 Germany Stad… DE          48703    Kreis… house N        place  
#> 6     2  9.83e9 Germany Stad… DE          48703    Kreis… loca… N        place  
#> # ℹ 8 more variables: housenumber <chr>, street <chr>, district <chr>,
#> #   osm_value <chr>, name <chr>, state <chr>, extent <list>,
#> #   geometry <POINT [°]>