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 = 1,
  lang = "en",
  bbox = NULL,
  osm_tag = NULL,
  layer = NULL,
  locbias = NULL,
  locbias_scale = NULL,
  zoom = NULL,
  latinize = TRUE,
  progress = interactive()
)

Arguments

texts

Character vector of a texts to geocode.

limit

Number of results to return. A maximum of 50 results can be returned for a single search term. Defaults to 1. When more than a single text is provided but limit is greater than 1, the results can be uniquely linked to the input texts using the idx column in the output.

lang

Language of the results. If "default", returns the results in local language.

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. Possible values range from 0 to 1. 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.

latinize

If TRUE sanitizes search terms in texts by converting their encoding to "latin1" using latinize. This can be helpful if the search terms contain certain symbols (e.g. fancy quotes) that photon cannot handle properly. Defaults to TRUE as latinize is very conservative and should usually not cause any problems.

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 1 feature and 10 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 13.39894 ymin: 52.51088 xmax: 13.39894 ymax: 52.51088
#> Geodetic CRS:  WGS 84
#> # A tibble: 1 × 11
#>     idx osm_type osm_id country osm_key countrycode osm_value name  type  extent
#>   <int> <chr>     <int> <chr>   <chr>   <chr>       <chr>     <chr> <chr> <list>
#> 1     1 R         62422 Germany place   DE          city      Berl… city  <dbl> 
#> # ℹ 1 more variable: 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          Einga…
#>  6     1 R           1.11e7 Germany Berl… amenity DE          NA          Schwe…
#>  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          Meckl…
#> 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          Schwe…
#>  6     1 R           6.65e3 Deutsc… Berl… buildi… DE          6           Unter…
#>  7     1 R           1.27e6 Deutsc… Berl… amenity DE          NA          Meckl…
#>  8     1 R           3.60e6 Deutsc… Berl… buildi… DE          NA          Einga…
#>  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 1 feature and 10 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 13.39894 ymin: 52.51088 xmax: 13.39894 ymax: 52.51088
#> Geodetic CRS:  WGS 84
#> # A tibble: 1 × 11
#>     idx osm_type osm_id country osm_key countrycode osm_value name  type  extent
#>   <int> <chr>     <int> <chr>   <chr>   <chr>       <chr>     <chr> <chr> <list>
#> 1     1 R         62422 Germany place   DE          city      Berl… city  <dbl> 
#> # ℹ 1 more variable: 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 1 feature and 14 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 13.38142 ymin: 52.51275 xmax: 13.38142 ymax: 52.51275
#> Geodetic CRS:  WGS 84
#> # A tibble: 1 × 15
#>     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       
#> # ℹ 6 more variables: osm_key <chr>, street <chr>, district <chr>,
#> #   osm_value <chr>, name <chr>, geometry <POINT [°]>

# search for museums in berlin
geocode("Berlin", osm_tag = "tourism:museum")
#> Simple feature collection with 1 feature and 14 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 13.33063 ymin: 52.50659 xmax: 13.33063 ymax: 52.50659
#> Geodetic CRS:  WGS 84
#> # A tibble: 1 × 15
#>     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
#> # ℹ 6 more variables: housenumber <chr>, street <chr>, district <chr>,
#> #   osm_value <chr>, name <chr>, geometry <POINT [°]>

# search for touristic attractions in berlin
geocode("Berlin", osm_tag = "tourism")
#> Simple feature collection with 1 feature and 15 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 13.33923 ymin: 52.50845 xmax: 13.33923 ymax: 52.50845
#> Geodetic CRS:  WGS 84
#> # A tibble: 1 × 16
#>     idx  osm_id country city   countrycode postcode type  osm_type osm_key
#>   <int>   <int> <chr>   <chr>  <chr>       <chr>    <chr> <chr>    <chr>  
#> 1     1 9393789 Germany Berlin DE          10787    house W        tourism
#> # ℹ 7 more variables: 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 1 feature and 10 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: 13.39894 ymin: 52.51088 xmax: 13.39894 ymax: 52.51088
#> Geodetic CRS:  WGS 84
#> # A tibble: 1 × 11
#>     idx osm_type osm_id country osm_key countrycode osm_value name  type  extent
#>   <int> <chr>     <int> <chr>   <chr>   <chr>       <chr>     <chr> <chr> <list>
#> 1     1 R         62422 Germany place   DE          city      Berl… city  <dbl> 
#> # ℹ 1 more variable: 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 1 feature and 12 fields
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: -89.90316 ymin: 39.75894 xmax: -89.90316 ymax: 39.75894
#> Geodetic CRS:  WGS 84
#> # A tibble: 1 × 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…
#> # ℹ 3 more variables: type <chr>, extent <list>, geometry <POINT [°]>

# latinization can help normalize search terms
geocode("Luatuanu\u2019u", latinize = FALSE) # fails
#> Simple feature collection with 1 feature and 10 fields (with 1 geometry empty)
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: Inf ymin: Inf xmax: -Inf ymax: -Inf
#> Geodetic CRS:  WGS 84
#> # A tibble: 1 × 11
#>     idx osm_type osm_id country osm_key countrycode osm_value name  type  extent
#>   <int> <chr>     <int> <chr>   <chr>   <chr>       <chr>     <chr> <chr> <list>
#> 1     1 NA           NA NA      NA      NA          NA        NA    NA    <dbl> 
#> # ℹ 1 more variable: geometry <POINT [°]>
geocode("Luatuanu\u2019u", latinize = TRUE)  # works
#> Simple feature collection with 1 feature and 10 fields (with 1 geometry empty)
#> Geometry type: POINT
#> Dimension:     XY
#> Bounding box:  xmin: Inf ymin: Inf xmax: -Inf ymax: -Inf
#> Geodetic CRS:  WGS 84
#> # A tibble: 1 × 11
#>     idx osm_type osm_id country osm_key countrycode osm_value name  type  extent
#>   <int> <chr>     <int> <chr>   <chr>   <chr>       <chr>     <chr> <chr> <list>
#> 1     1 NA           NA NA      NA      NA          NA        NA    NA    <dbl> 
#> # ℹ 1 more variable: geometry <POINT [°]>