geocode: Unstructured geocoding

In photon: High-Performance Geocoding using 'photon'

Unstructured geocoding

Description

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,
  dedupe = TRUE,
  include = NULL,
  exclude = 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.
dedupe	If FALSE, keeps duplicates in the geocoding results. By default, photon attempts to deduplicate results that have the same name, postcode, and OSM value. Defaults to TRUE.
include, exclude	Character vector containing categories to include or exclude. Places will be included if any category in include is present. Places will be excluded if all categories in exclude are present.
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.

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

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.

Examples

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

# geocode a city
geocode("Berlin")

# return more results
geocode("Berlin", limit = 10)

# return the results in german
geocode("Berlin", limit = 10, lang = "de")

# limit to cities
geocode("Berlin", layer = "city")

# limit to European cities
geocode("Berlin", bbox = c(xmin = -71.18, ymin = 44.46, xmax = 13.39, ymax = 52.52))

# search for museums in berlin
geocode("Berlin", osm_tag = "tourism:museum")

# search for touristic attractions in berlin
geocode("Berlin", osm_tag = "tourism")

# search for anything but tourism
geocode("Berlin", osm_tag = "!tourism")

# 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")

# latinization can help normalize search terms
geocode("Luatuanu\u2019u", latinize = FALSE) # fails
geocode("Luatuanu\u2019u", latinize = TRUE)  # works

photon documentation built on April 10, 2026, 5:07 p.m.