Skip to contents

Unstructured geocoding

Source: R/geocode.R
geocode.Rd

Geocode arbitrary text strings. Unstructured geocoding is more flexible but generally less accurate than structured geocoding.

Usage

geocode(
  texts,
  limit = 3,
  lang = "en",
  bbox = NULL,
  osm_tag = NULL,
  layer = NULL,
  locbias = NULL,
  locbias_scale = NULL,
  zoom = NULL,
  progress = interactive()
)

Arguments

texts

Character vector of a texts to geocode.

limit

Number of results to return. Defaults to 3.

lang

Language of the results.

bbox

Any object that can be parsed by st_bbox. Results must lie within this bbox.

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.

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()

# geocode a city
geocode("Berlin")
#> Simple feature collection with 3 features and 16 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 13.23981 ymin: 52.51088 xmax: 13.39894 ymax: 52.51458
#> Geodetic CRS:  WGS 84
#> # A tibble: 3 × 17
#>     idx osm_type   osm_id country city  osm_key countrycode housenumber postcode
#>   <int> <chr>       <int> <chr>   <chr> <chr>   <chr>       <chr>       <chr>   
#> 1     1 R          6.24e4 Germany NA    place   DE          NA          NA      
#> 2     1 N          1.08e9 Germany Berl… histor… DE          NA          10117   
#> 3     1 W          3.89e7 Germany Berl… leisure DE          3           14053   
#> # ℹ 8 more variables: locality <chr>, street <chr>, district <chr>,
#> #   osm_value <chr>, name <chr>, type <chr>, extent <list>,
#> #   geometry <POINT [°]>

# return more results
geocode("Berlin", limit = 10)
#> Simple feature collection with 10 features and 18 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: -71.18365 ymin: 44.46888 xmax: 13.39894 ymax: 52.52502
#> Geodetic CRS:  WGS 84
#> # A tibble: 10 × 19
#>      idx osm_type    osm_id country city  osm_key countrycode housenumber street
#>    <int> <chr>        <dbl> <chr>   <chr> <chr>   <chr>       <chr>       <chr> 
#>  1     1 R           6.24e4 Germany NA    place   DE          NA          NA    
#>  2     1 N           1.08e9 Germany Berl… histor… DE          NA          Gertr…
#>  3     1 W           3.89e7 Germany Berl… leisure DE          3           Olymp…
#>  4     1 R           6.65e3 Germany Berl… buildi… DE          6           Unter…
#>  5     1 R           3.60e6 Germany Berl… buildi… DE          NA          Washi…
#>  6     1 R           1.11e7 Germany Berl… amenity DE          NA          Flied…
#>  7     1 W           9.39e6 Germany Berl… tourism DE          8           Harde…
#>  8     1 N           3.86e9 Germany Berl… railway DE          NA          Einga…
#>  9     1 R           1.27e6 Germany Berl… amenity DE          NA          Kurfü…
#> 10     1 R           1.70e5 United… NA    place   US          NA          NA    
#> # ℹ 10 more variables: district <chr>, osm_value <chr>, postcode <chr>,
#> #   locality <chr>, name <chr>, county <chr>, state <chr>, type <chr>,
#> #   extent <list>, geometry <POINT [°]>

# return the results in german
geocode("Berlin", limit = 10, lang = "de")
#> Simple feature collection with 10 features and 18 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: -71.18365 ymin: 44.46888 xmax: 13.39894 ymax: 52.52502
#> Geodetic CRS:  WGS 84
#> # A tibble: 10 × 19
#>      idx osm_type    osm_id country city  osm_key countrycode housenumber street
#>    <int> <chr>        <dbl> <chr>   <chr> <chr>   <chr>       <chr>       <chr> 
#>  1     1 R           6.24e4 Deutsc… NA    place   DE          NA          NA    
#>  2     1 N           1.08e9 Deutsc… Berl… histor… DE          NA          Gertr…
#>  3     1 W           3.89e7 Deutsc… Berl… leisure DE          3           Olymp…
#>  4     1 W           9.39e6 Deutsc… Berl… tourism DE          8           Harde…
#>  5     1 R           1.11e7 Deutsc… Berl… amenity DE          NA          Flied…
#>  6     1 R           6.65e3 Deutsc… Berl… buildi… DE          6           Unter…
#>  7     1 R           1.27e6 Deutsc… Berl… amenity DE          NA          Kurfü…
#>  8     1 R           3.60e6 Deutsc… Berl… buildi… DE          NA          Washi…
#>  9     1 N           3.86e9 Deutsc… Berl… railway DE          NA          Einga…
#> 10     1 R           1.70e5 Verein… NA    place   US          NA          NA    
#> # ℹ 10 more variables: district <chr>, osm_value <chr>, postcode <chr>,
#> #   locality <chr>, name <chr>, county <chr>, state <chr>, type <chr>,
#> #   extent <list>, geometry <POINT [°]>

# limit to cities
geocode("Berlin", layer = "city")
#> Simple feature collection with 3 features and 13 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: -89.90316 ymin: 39.75894 xmax: 13.39894 ymax: 52.51088
#> Geodetic CRS:  WGS 84
#> # A tibble: 3 × 14
#>     idx osm_type osm_id country     osm_key countrycode osm_value postcode name 
#>   <int> <chr>     <int> <chr>       <chr>   <chr>       <chr>     <chr>    <chr>
#> 1     1 R         62422 Germany     place   DE          city      NA       Berl…
#> 2     1 R        170184 United Sta… place   US          town      03570    Berl…
#> 3     1 R        126290 United Sta… place   US          village   NA       Berl…
#> # ℹ 5 more variables: county <chr>, state <chr>, type <chr>, extent <list>,
#> #   geometry <POINT [°]>

# limit to European cities
geocode("Berlin", bbox = c(xmin = -71.18, ymin = 44.46, xmax = 13.39, ymax = 52.52))
#> Simple feature collection with 3 features and 16 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 13.23981 ymin: 52.45286 xmax: 13.38142 ymax: 52.51458
#> Geodetic CRS:  WGS 84
#> # A tibble: 3 × 17
#>     idx     osm_id country city   countrycode postcode locality   type  osm_type
#>   <int>      <int> <chr>   <chr>  <chr>       <chr>    <chr>      <chr> <chr>   
#> 1     1 1078631331 Germany Berlin DE          10117    Dorotheen… house N       
#> 2     1   38862723 Germany Berlin DE          14053    NA         house W       
#> 3     1   11148577 Germany Berlin DE          14195    NA         house R       
#> # ℹ 8 more variables: osm_key <chr>, housenumber <chr>, street <chr>,
#> #   district <chr>, osm_value <chr>, name <chr>, extent <list>,
#> #   geometry <POINT [°]>

# search for museums in berlin
geocode("Berlin", osm_tag = "tourism:museum")
#> Simple feature collection with 3 features and 15 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 13.33063 ymin: 52.48614 xmax: 13.53985 ymax: 52.5417
#> Geodetic CRS:  WGS 84
#> # A tibble: 3 × 16
#>     idx     osm_id country city   countrycode postcode type  osm_type osm_key
#>   <int>      <dbl> <chr>   <chr>  <chr>       <chr>    <chr> <chr>    <chr>  
#> 1     1 2959465154 Germany Berlin DE          10623    house N        tourism
#> 2     1  367216314 Germany Berlin DE          13055    house W        tourism
#> 3     1  290220610 Germany Berlin DE          10318    house W        tourism
#> # ℹ 7 more variables: housenumber <chr>, street <chr>, district <chr>,
#> #   osm_value <chr>, name <chr>, extent <list>, geometry <POINT [°]>

# search for touristic attractions in berlin
geocode("Berlin", osm_tag = "tourism")
#> Simple feature collection with 3 features and 16 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 13.33923 ymin: 52.50845 xmax: 13.40109 ymax: 52.51908
#> Geodetic CRS:  WGS 84
#> # A tibble: 3 × 17
#>     idx    osm_id country city   countrycode postcode locality    type  osm_type
#>   <int>     <int> <chr>   <chr>  <chr>       <chr>    <chr>       <chr> <chr>   
#> 1     1   9393789 Germany Berlin DE          10787    NA          house W       
#> 2     1 313670734 Germany Berlin DE          10178    Friedrichs… house W       
#> 3     1 217512230 Germany Berlin DE          10117    Gendarmenm… house W       
#> # ℹ 8 more variables: osm_key <chr>, housenumber <chr>, street <chr>,
#> #   district <chr>, osm_value <chr>, name <chr>, extent <list>,
#> #   geometry <POINT [°]>

# search for anything but tourism
geocode("Berlin", osm_tag = "!tourism")
#> Simple feature collection with 3 features and 16 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 13.23981 ymin: 52.51088 xmax: 13.39894 ymax: 52.51458
#> Geodetic CRS:  WGS 84
#> # A tibble: 3 × 17
#>     idx osm_type   osm_id country city  osm_key countrycode housenumber postcode
#>   <int> <chr>       <int> <chr>   <chr> <chr>   <chr>       <chr>       <chr>   
#> 1     1 R          6.24e4 Germany NA    place   DE          NA          NA      
#> 2     1 N          1.08e9 Germany Berl… histor… DE          NA          10117   
#> 3     1 W          3.89e7 Germany Berl… leisure DE          3           14053   
#> # ℹ 8 more variables: locality <chr>, street <chr>, district <chr>,
#> #   osm_value <chr>, name <chr>, type <chr>, extent <list>,
#> #   geometry <POINT [°]>

# use location biases to match Berlin, IL instead of Berlin, DE
geocode("Berlin", locbias = c(-100, 40), locbias_scale = 0.1, zoom = 7, osm_tag = "place")
#> Simple feature collection with 3 features and 12 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: -98.48982 ymin: 39.72533 xmax: -89.90316 ymax: 46.37858
#> Geodetic CRS:  WGS 84
#> # A tibble: 3 × 13
#>     idx osm_type osm_id country osm_key countrycode osm_value name  county state
#>   <int> <chr>     <int> <chr>   <chr>   <chr>       <chr>     <chr> <chr>  <chr>
#> 1     1 R        126290 United… place   US          village   Berl… Sanga… Illi…
#> 2     1 R        181615 United… place   US          city      Berl… LaMou… Nort…
#> 3     1 R        126309 United… place   US          village   New … Sanga… Illi…
#> # ℹ 3 more variables: type <chr>, extent <list>, geometry <POINT [°]>