Package 'nominatimlite'

Convert a bounding box to an sfc POLYGON object

Description

Converts bounding box coordinates to an sfc object with POLYGON geometry.

Usage

bbox_to_poly(bbox = NA, xmin = NA, ymin = NA, xmax = NA, ymax = NA, crs = 4326)

Arguments

bbox	A numeric vector of four bounding box coordinates in the form c(xmin, ymin, xmax, ymax).
xmin, ymin, xmax, ymax	Individual bounding box coordinates. Use these arguments as an alternative to bbox.
crs	coordinate reference system, something suitable as input to st_crs

Details

Bounding boxes can be located using online tools such as https://boundingbox.klokantech.com/.

Value

An sfc object with POLYGON geometry and the coordinate reference system specified by crs.

See Also

sf::st_as_sfc() and sf::st_sfc().

Spatial output functions: geo_address_lookup_sf(), geo_amenity_sf(), geo_lite_sf(), geo_lite_struct_sf(), reverse_geo_lite_sf()

Examples

# Bounding box for Germany
bbox_GER <- c(5.86631529, 47.27011137, 15.04193189, 55.09916098)

bbox_GER_sf <- bbox_to_poly(bbox_GER)

library(ggplot2)

ggplot(bbox_GER_sf) +
  geom_sf()

# Extract the bounding box of an `sf` object
sfobj <- geo_lite_sf("seychelles", points_only = FALSE)

sfobj

# Require at least one non-empty object
if (!all(sf::st_is_empty(sfobj))) {
  bbox <- sf::st_bbox(sfobj)

  bbox

  bbox_sfobj <- bbox_to_poly(bbox)

  ggplot(bbox_sfobj) +
    geom_sf(fill = "lightblue", alpha = 0.5) +
    geom_sf(data = sfobj, fill = "wheat")
}

---

Address lookup API

Description

Looks up addresses and other details for one or more OpenStreetMap (OSM) objects, such as nodes, ways or relations. Results are returned as a tibble. Use geo_address_lookup_sf() to return an sf object instead.

Usage

geo_address_lookup(
  osm_ids,
  type = c("N", "W", "R"),
  lat = "lat",
  long = "lon",
  full_results = FALSE,
  return_addresses = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  custom_query = list()
)

Arguments

osm_ids	A numeric vector of OSM identifiers, for example c(12345, 67890).
type	A character vector containing the OSM object type associated with each value in osm_ids. Possible values are node ("N"), way ("W") and relation ("R"). A single value is recycled.
lat	A string giving the name of the latitude column in the output. Defaults to "lat".
long	A string giving the name of the longitude column in the output. Defaults to "lon".
full_results	If TRUE, return all available fields from the Nominatim API. If FALSE, return only query metadata, location data and requested address columns.
return_addresses	If TRUE, include single-line addresses in the results.
verbose	If TRUE, displays detailed messages in the console.
nominatim_server	A string giving the base URL of the Nominatim server. Defaults to "https://nominatim.openstreetmap.org/".
custom_query	A named list of additional API parameters, for example list(countrycodes = "US"). See Details.

Details

See https://nominatim.org/release-docs/latest/api/Lookup/ for additional parameters to be passed to custom_query.

Value

A tibble with the results that match the query.

See Also

Address search functions: geo_address_lookup_sf(), geo_amenity(), geo_amenity_sf(), geo_lite(), geo_lite_sf(), geo_lite_struct(), geo_lite_struct_sf()

Address lookup functions: geo_address_lookup_sf()

Examples

ids <- geo_address_lookup(osm_ids = c(46240148, 34633854), type = "W")

ids

several <- geo_address_lookup(c(146656, 240109189), type = c("R", "N"))
several

---

Address lookup API with sf output

Description

Looks up addresses and other details for one or more OpenStreetMap (OSM) objects, such as nodes, ways or relations. Results are returned as an sf object. Use geo_address_lookup() to return a tibble instead.

Usage

geo_address_lookup_sf(
  osm_ids,
  type = c("N", "W", "R"),
  full_results = FALSE,
  return_addresses = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  custom_query = list(),
  points_only = TRUE
)

Arguments

osm_ids	A numeric vector of OSM identifiers, for example c(12345, 67890).
type	A character vector containing the OSM object type associated with each value in osm_ids. Possible values are node ("N"), way ("W") and relation ("R"). A single value is recycled.
full_results	If TRUE, return all available fields from the Nominatim API. If FALSE, return only query metadata, geometry and requested address columns.
return_addresses	If TRUE, include single-line addresses in the results.
verbose	If TRUE, displays detailed messages in the console.
nominatim_server	A string giving the base URL of the Nominatim server. Defaults to "https://nominatim.openstreetmap.org/".
custom_query	A named list of additional API parameters, for example list(countrycodes = "US"). See Details.
points_only	If TRUE, return only point geometries. If FALSE, the API may return other geometry types. See About geometry types.

Details

See https://nominatim.org/release-docs/latest/api/Lookup/ for additional parameters to be passed to custom_query.

Value

An sf object with the results that match the query.

About geometry types

The points_only argument controls whether the results contain only points. All Nominatim results have at least a point geometry.

When points_only = FALSE, the geometry type depends on the matching feature. Administrative areas and major buildings are returned as polygons, rivers and roads are returned as lines and amenities may still be returned as points.

This function is vectorized, allowing multiple addresses to be searched. With points_only = FALSE, multiple geometry types may be returned.

See Also

Address search functions: geo_address_lookup(), geo_amenity(), geo_amenity_sf(), geo_lite(), geo_lite_sf(), geo_lite_struct(), geo_lite_struct_sf()

Address lookup functions: geo_address_lookup()

Spatial output functions: bbox_to_poly(), geo_amenity_sf(), geo_lite_sf(), geo_lite_struct_sf(), reverse_geo_lite_sf()

Examples

# Notre-Dame Cathedral, Paris

NotreDame <- geo_address_lookup_sf(osm_ids = 201611261, type = "W")

# Require at least one non-empty object
if (!all(sf::st_is_empty(NotreDame))) {
  library(ggplot2)

  ggplot(NotreDame) +
    geom_sf()
}

NotreDame_poly <- geo_address_lookup_sf(201611261,
  type = "W",
  points_only = FALSE
)

if (!all(sf::st_is_empty(NotreDame_poly))) {
  ggplot(NotreDame_poly) +
    geom_sf()
}

# Vectorized input

several <- geo_address_lookup_sf(c(146656, 240109189), type = c("R", "N"))
several

---

Look up amenities

Description

Looks up OpenStreetMap amenities within a bounding box of the form ⁠(xmin, ymin, xmax, ymax)⁠. Results are returned as a tibble. Use geo_amenity_sf() to return an sf object instead.

Usage

geo_amenity(
  bbox,
  amenity,
  lat = "lat",
  long = "lon",
  limit = 1,
  full_results = FALSE,
  return_addresses = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  progressbar = TRUE,
  custom_query = list(),
  strict = FALSE
)

Arguments

bbox	A bounding box (viewbox) used to limit the search. Supply a numeric vector of longitude (x) and latitude (y) in the form ⁠(xmin, ymin, xmax, ymax)⁠, an sf object or an sfc object. See Details.
amenity	A character vector of amenities to look up, for example c("pub", "restaurant"). See osm_amenities.
lat	A string giving the name of the latitude column in the output. Defaults to "lat".
long	A string giving the name of the longitude column in the output. Defaults to "lon".
limit	A positive integer giving the maximum number of results to return per query. Nominatim returns at most 50 results per query.
full_results	If TRUE, return all available fields from the Nominatim API. If FALSE, return only query metadata, location data and requested address columns.
return_addresses	If TRUE, include single-line addresses in the results.
verbose	If TRUE, displays detailed messages in the console.
nominatim_server	A string giving the base URL of the Nominatim server. Defaults to "https://nominatim.openstreetmap.org/".
progressbar	If TRUE, displays a progress bar when processing multiple queries.
custom_query	A named list of additional API parameters, for example list(countrycodes = "US"). See Details.
strict	If TRUE, keeps only results inside bbox. If FALSE (the default), Nominatim may return results outside the bounding box.

Details

Bounding boxes can be located using online tools such as https://boundingbox.klokantech.com/.

For a full list of valid amenities, see https://wiki.openstreetmap.org/wiki/Key:amenity and osm_amenities.

See https://nominatim.org/release-docs/latest/api/Search/ for additional parameters to be passed to custom_query.

Value

A tibble with the results that match the query.

See Also

Amenity lookup functions: geo_amenity_sf(), osm_amenities

Address search functions: geo_address_lookup(), geo_address_lookup_sf(), geo_amenity_sf(), geo_lite(), geo_lite_sf(), geo_lite_struct(), geo_lite_struct_sf()

Examples

# Times Square, NY, USA
bbox <- c(
  -73.9894467311, 40.75573629,
  -73.9830630737, 40.75789245
)

geo_amenity(
  bbox = bbox,
  amenity = "restaurant"
)

# Multiple amenities
geo_amenity(
  bbox = bbox,
  amenity = c("restaurant", "pub")
)

# Increase `limit` and use strict filtering
geo_amenity(
  bbox = bbox,
  amenity = c("restaurant", "pub"),
  limit = 10,
  strict = TRUE
)

---

Look up amenities with sf output

Description

Looks up OpenStreetMap amenities within a bounding box of the form ⁠(xmin, ymin, xmax, ymax)⁠. Results are returned as an sf object. Use geo_amenity() to return a tibble instead.

Usage

geo_amenity_sf(
  bbox,
  amenity,
  limit = 1,
  full_results = FALSE,
  return_addresses = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  progressbar = TRUE,
  custom_query = list(),
  strict = FALSE,
  points_only = TRUE
)

Arguments

bbox	A bounding box (viewbox) used to limit the search. Supply a numeric vector of longitude (x) and latitude (y) in the form ⁠(xmin, ymin, xmax, ymax)⁠, an sf object or an sfc object. See Details.
amenity	A character vector of amenities to look up, for example c("pub", "restaurant"). See osm_amenities.
limit	A positive integer giving the maximum number of results to return per query. Nominatim returns at most 50 results per query.
full_results	If TRUE, return all available fields from the Nominatim API. If FALSE, return only query metadata, geometry and requested address columns.
return_addresses	If TRUE, include single-line addresses in the results.
verbose	If TRUE, displays detailed messages in the console.
nominatim_server	A string giving the base URL of the Nominatim server. Defaults to "https://nominatim.openstreetmap.org/".
progressbar	If TRUE, displays a progress bar when processing multiple queries.
custom_query	A named list of additional API parameters, for example list(countrycodes = "US"). See Details.
strict	If TRUE, keeps only results inside bbox. If FALSE (the default), Nominatim may return results outside the bounding box.
points_only	If TRUE, return only point geometries. If FALSE, the API may return other geometry types. See About geometry types.

Details

Bounding boxes can be located using online tools such as https://boundingbox.klokantech.com/.

For a full list of valid amenities, see https://wiki.openstreetmap.org/wiki/Key:amenity and osm_amenities.

See https://nominatim.org/release-docs/latest/api/Search/ for additional parameters to be passed to custom_query.

Value

An sf object with the results that match the query.

About geometry types

The points_only argument controls whether the results contain only points. All Nominatim results have at least a point geometry.

When points_only = FALSE, the geometry type depends on the matching feature. Administrative areas and major buildings are returned as polygons, rivers and roads are returned as lines and amenities may still be returned as points.

This function is vectorized, allowing multiple addresses to be searched. With points_only = FALSE, multiple geometry types may be returned.

See Also

Amenity lookup functions: geo_amenity(), osm_amenities

Address search functions: geo_address_lookup(), geo_address_lookup_sf(), geo_amenity(), geo_lite(), geo_lite_sf(), geo_lite_struct(), geo_lite_struct_sf()

Spatial output functions: bbox_to_poly(), geo_address_lookup_sf(), geo_lite_sf(), geo_lite_struct_sf(), reverse_geo_lite_sf()

Examples

# Usera, Madrid

library(ggplot2)
mad <- geo_lite_sf("Usera, Madrid, Spain", points_only = FALSE)

# Restaurants, pubs and schools

rest_pub <- geo_amenity_sf(mad, c("restaurant", "pub", "school"),
  limit = 50
)

if (!all(sf::st_is_empty(rest_pub))) {
  ggplot(mad) +
    geom_sf() +
    geom_sf(data = rest_pub, aes(color = query, shape = query))
}

---

Address search API (free-form query)

Description

Searches for addresses supplied as a character vector and returns matching results as a tibble. Use geo_lite_sf() to return an sf object instead.

This function performs the free-form address search described in the API endpoint.

Usage

geo_lite(
  address,
  lat = "lat",
  long = "lon",
  limit = 1,
  full_results = FALSE,
  return_addresses = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  progressbar = TRUE,
  custom_query = list()
)

Arguments

address	A character vector of single-line addresses, for example "1600 Pennsylvania Ave NW, Washington" or c("Madrid", "Barcelona").
lat	A string giving the name of the latitude column in the output. Defaults to "lat".
long	A string giving the name of the longitude column in the output. Defaults to "lon".
limit	A positive integer giving the maximum number of results to return per query. Nominatim returns at most 50 results per query.
full_results	If TRUE, return all available fields from the Nominatim API. If FALSE, return only query metadata, location data and requested address columns.
return_addresses	If TRUE, include single-line addresses in the results.
verbose	If TRUE, displays detailed messages in the console.
nominatim_server	A string giving the base URL of the Nominatim server. Defaults to "https://nominatim.openstreetmap.org/".
progressbar	If TRUE, displays a progress bar when processing multiple queries.
custom_query	A named list of additional API parameters, for example list(countrycodes = "US"). See Details.

Details

See https://nominatim.org/release-docs/latest/api/Search/ for additional parameters to be passed to custom_query.

Value

A tibble with the results that match the query.

See Also

Address search functions: geo_address_lookup(), geo_address_lookup_sf(), geo_amenity(), geo_amenity_sf(), geo_lite_sf(), geo_lite_struct(), geo_lite_struct_sf()

Examples

geo_lite("Madrid, Spain")

# Multiple addresses
geo_lite(c("Madrid", "Barcelona"))

# Restrict the search to the United States and return all fields
geo_lite(c("Madrid", "Barcelona"),
  custom_query = list(countrycodes = "US"),
  full_results = TRUE
)

---

Address search API with sf output (free-form query)

Description

Searches for addresses and returns matching results as an sf object. Use geo_lite() to return a tibble instead.

This function performs the free-form address search described in the API endpoint.

Usage

geo_lite_sf(
  address,
  limit = 1,
  return_addresses = TRUE,
  full_results = FALSE,
  verbose = FALSE,
  progressbar = TRUE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  custom_query = list(),
  points_only = TRUE
)

Arguments

address	A character vector of single-line addresses, for example "1600 Pennsylvania Ave NW, Washington" or c("Madrid", "Barcelona").
limit	A positive integer giving the maximum number of results to return per query. Nominatim returns at most 50 results per query.
return_addresses	If TRUE, include single-line addresses in the results.
full_results	If TRUE, return all available fields from the Nominatim API. If FALSE, return only query metadata, geometry and requested address columns.
verbose	If TRUE, displays detailed messages in the console.
progressbar	If TRUE, displays a progress bar when processing multiple queries.
nominatim_server	A string giving the base URL of the Nominatim server. Defaults to "https://nominatim.openstreetmap.org/".
custom_query	A named list of additional API parameters, for example list(countrycodes = "US"). See Details.
points_only	If TRUE, return only point geometries. If FALSE, the API may return other geometry types. See About geometry types.

Details

See https://nominatim.org/release-docs/latest/api/Search/ for additional parameters to be passed to custom_query.

Value

An sf object with the results that match the query.

About geometry types

The points_only argument controls whether the results contain only points. All Nominatim results have at least a point geometry.

When points_only = FALSE, the geometry type depends on the matching feature. Administrative areas and major buildings are returned as polygons, rivers and roads are returned as lines and amenities may still be returned as points.

This function is vectorized, allowing multiple addresses to be searched. With points_only = FALSE, multiple geometry types may be returned.

See Also

Address search functions: geo_address_lookup(), geo_address_lookup_sf(), geo_amenity(), geo_amenity_sf(), geo_lite(), geo_lite_struct(), geo_lite_struct_sf()

Spatial output functions: bbox_to_poly(), geo_address_lookup_sf(), geo_amenity_sf(), geo_lite_struct_sf(), reverse_geo_lite_sf()

Examples

# Point geometries
library(ggplot2)

string <- "Statue of Liberty, NY, USA"
sol <- geo_lite_sf(string)

if (!all(sf::st_is_empty(sol))) {
  ggplot(sol) +
    geom_sf()
}

sol_poly <- geo_lite_sf(string, points_only = FALSE)

if (!all(sf::st_is_empty(sol_poly))) {
  ggplot(sol_poly) +
    geom_sf() +
    geom_sf(data = sol, color = "red")
}
# Multiple matches

madrid <- geo_lite_sf("Comunidad de Madrid, Spain",
  limit = 2,
  points_only = FALSE, full_results = TRUE
)

if (!all(sf::st_is_empty(madrid))) {
  ggplot(madrid) +
    geom_sf(fill = NA)
}

---

Address search API (structured query)

Description

Searches for addresses already split into components and returns matching results as a tibble. Use geo_lite_struct_sf() to return an sf object instead.

This function performs the structured address search described in the API endpoint. To perform a free-form search, use geo_lite().

Usage

geo_lite_struct(
  amenity = NULL,
  street = NULL,
  city = NULL,
  county = NULL,
  state = NULL,
  country = NULL,
  postalcode = NULL,
  lat = "lat",
  long = "lon",
  limit = 1,
  full_results = FALSE,
  return_addresses = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  custom_query = list()
)

Arguments

amenity	A string giving the name or type of amenity. See geo_amenity().
street	A string giving the house number and street name.
city	A string giving the city.
county	A string giving the county.
state	A string giving the state.
country	A string giving the country.
postalcode	A string giving the postal code.
lat	A string giving the name of the latitude column in the output. Defaults to "lat".
long	A string giving the name of the longitude column in the output. Defaults to "lon".
limit	A positive integer giving the maximum number of results to return per query. Nominatim returns at most 50 results per query.
full_results	If TRUE, return all available fields from the Nominatim API. If FALSE, return only query metadata, location data and requested address columns.
return_addresses	If TRUE, include single-line addresses in the results.
verbose	If TRUE, displays detailed messages in the console.
nominatim_server	A string giving the base URL of the Nominatim server. Defaults to "https://nominatim.openstreetmap.org/".
custom_query	A named list of additional API parameters, for example list(countrycodes = "US"). See Details.

Details

A structured address search accepts an address already split into components. Each argument represents an address field. All components are optional, so provide only those relevant to the address you want to find.

See https://nominatim.org/release-docs/latest/api/Search/ for additional parameters to be passed to custom_query.

Value

A tibble with the results that match the query.

See Also

Address search functions: geo_address_lookup(), geo_address_lookup_sf(), geo_amenity(), geo_amenity_sf(), geo_lite(), geo_lite_sf(), geo_lite_struct_sf()

Examples

pl_mayor <- geo_lite_struct(
  street = "Plaza Mayor", country = "Spain",
  limit = 50, full_results = TRUE
)

dplyr::glimpse(pl_mayor)

---

Address search API with sf output (structured query)

Description

Searches for addresses already split into components and returns matching results as an sf object. Use geo_lite_struct() to return a tibble instead.

This function performs the structured address search described in the API endpoint. To perform a free-form search, use geo_lite_sf().

Usage

geo_lite_struct_sf(
  amenity = NULL,
  street = NULL,
  city = NULL,
  county = NULL,
  state = NULL,
  country = NULL,
  postalcode = NULL,
  limit = 1,
  full_results = FALSE,
  return_addresses = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  custom_query = list(),
  points_only = TRUE
)

Arguments

amenity	A string giving the name or type of amenity. See geo_amenity().
street	A string giving the house number and street name.
city	A string giving the city.
county	A string giving the county.
state	A string giving the state.
country	A string giving the country.
postalcode	A string giving the postal code.
limit	A positive integer giving the maximum number of results to return per query. Nominatim returns at most 50 results per query.
full_results	If TRUE, return all available fields from the Nominatim API. If FALSE, return only query metadata, geometry and requested address columns.
return_addresses	If TRUE, include single-line addresses in the results.
verbose	If TRUE, displays detailed messages in the console.
nominatim_server	A string giving the base URL of the Nominatim server. Defaults to "https://nominatim.openstreetmap.org/".
custom_query	A named list of additional API parameters, for example list(countrycodes = "US"). See Details.
points_only	If TRUE, return only point geometries. If FALSE, the API may return other geometry types. See About geometry types.

Details

A structured address search accepts an address already split into components. Each argument represents an address field. All components are optional, so provide only those relevant to the address you want to find.

See https://nominatim.org/release-docs/latest/api/Search/ for additional parameters to be passed to custom_query.

Value

An sf object with the results that match the query.

About geometry types

The points_only argument controls whether the results contain only points. All Nominatim results have at least a point geometry.

When points_only = FALSE, the geometry type depends on the matching feature. Administrative areas and major buildings are returned as polygons, rivers and roads are returned as lines and amenities may still be returned as points.

This function is vectorized, allowing multiple addresses to be searched. With points_only = FALSE, multiple geometry types may be returned.

See Also

Address search functions: geo_address_lookup(), geo_address_lookup_sf(), geo_amenity(), geo_amenity_sf(), geo_lite(), geo_lite_sf(), geo_lite_struct()

Spatial output functions: bbox_to_poly(), geo_address_lookup_sf(), geo_amenity_sf(), geo_lite_sf(), reverse_geo_lite_sf()

Examples

# Structured address search

pl_mayor <- geo_lite_struct_sf(
  street = "Plaza Mayor",
  county = "Comunidad de Madrid",
  country = "Spain", limit = 50,
  full_results = TRUE, verbose = TRUE
)

# Administrative boundary
ccaa <- geo_lite_sf("Comunidad de Madrid, Spain", points_only = FALSE)

library(ggplot2)

if (any(!sf::st_is_empty(pl_mayor), !sf::st_is_empty(ccaa))) {
  ggplot(ccaa) +
    geom_sf() +
    geom_sf(data = pl_mayor, aes(shape = addresstype, color = addresstype))
}

---

OpenStreetMap amenities

Description

A dataset of amenity values available on OpenStreetMap.

Format

A tibble with 136 rows and three columns:

category

The category of the amenity.

amenity

The value of the amenity.

comment

A brief description of the type of amenity.

Note

The data were extracted on April 3, 2024.

Source

https://wiki.openstreetmap.org/wiki/Key:amenity

See Also

Amenity lookup functions: geo_amenity(), geo_amenity_sf()

Examples

data("osm_amenities")

osm_amenities

---

Reverse geocoding API

Description

Finds addresses from latitude and longitude coordinates and returns the matching results as a tibble. Latitude values must be in $\left[-90, 90 \right]$ and longitudes in $\left[-180, 180 \right]$. Use reverse_geo_lite_sf() to return an sf object instead.

Usage

reverse_geo_lite(
  lat,
  long,
  address = "address",
  full_results = FALSE,
  return_coords = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  progressbar = TRUE,
  custom_query = list()
)

Arguments

lat	Numeric latitude values in the range $\left[-90, 90 \right]$.
long	Numeric longitude values in the range $\left[-180, 180 \right]$.
address	A string giving the name of the address column in the output. Defaults to "address".
full_results	If TRUE, return all available fields from the Nominatim API. If FALSE, return only query metadata, location data and requested address columns.
return_coords	If TRUE, returns the input coordinates with the results.
verbose	If TRUE, displays detailed messages in the console.
nominatim_server	A string giving the base URL of the Nominatim server. Defaults to "https://nominatim.openstreetmap.org/".
progressbar	If TRUE, displays a progress bar when processing multiple queries.
custom_query	A named list of API-specific parameters, for example list(zoom = 3). See Details.

Details

See https://nominatim.org/release-docs/latest/api/Reverse/ for additional parameters to be passed to custom_query.

Value

A tibble with the results that match the query.

About zooming

Set custom_query = list(zoom = 3) to adjust the output. Selected zoom levels correspond to these address details:

zoom	address_detail
3	country
5	state
8	county
10	city
14	suburb
16	major streets
17	major and minor streets
18	building

See Also

Reverse geocoding functions: reverse_geo_lite_sf()

Examples

reverse_geo_lite(lat = 40.75728, long = -73.98586)

# Multiple coordinate pairs
reverse_geo_lite(lat = c(40.75728, 55.95335), long = c(-73.98586, -3.188375))

# Set the zoom to country level
sev <- reverse_geo_lite(
  lat = c(40.75728, 55.95335), long = c(-73.98586, -3.188375),
  custom_query = list(zoom = 0, extratags = TRUE),
  verbose = TRUE, full_results = TRUE
)

dplyr::glimpse(sev)

---

Reverse geocoding API with sf output

Description

Finds addresses from latitude and longitude coordinates and returns the matching results as an sf object. Latitude values must be in $\left[-90, 90 \right]$ and longitude values in $\left[-180, 180 \right]$. Use reverse_geo_lite() to return a tibble instead.

Usage

reverse_geo_lite_sf(
  lat,
  long,
  address = "address",
  full_results = FALSE,
  return_coords = TRUE,
  verbose = FALSE,
  nominatim_server = "https://nominatim.openstreetmap.org/",
  progressbar = TRUE,
  custom_query = list(),
  points_only = TRUE
)

Arguments

lat	Numeric latitude values in the range $\left[-90, 90 \right]$.
long	Numeric longitude values in the range $\left[-180, 180 \right]$.
address	A string giving the name of the address column in the output. Defaults to "address".
full_results	If TRUE, return all available fields from the Nominatim API. If FALSE, return only query metadata, geometry and requested address columns.
return_coords	If TRUE, returns the input coordinates with the results.
verbose	If TRUE, displays detailed messages in the console.
nominatim_server	A string giving the base URL of the Nominatim server. Defaults to "https://nominatim.openstreetmap.org/".
progressbar	If TRUE, displays a progress bar when processing multiple queries.
custom_query	A named list of API-specific parameters, for example list(zoom = 3). See Details.
points_only	If TRUE, return only point geometries. If FALSE, the API may return other geometry types. See About geometry types.

Details

See https://nominatim.org/release-docs/latest/api/Reverse/ for additional parameters to be passed to custom_query.

Value

An sf object with the results that match the query.

About zooming

Set custom_query = list(zoom = 3) to adjust the output. Selected zoom levels correspond to these address details:

zoom	address_detail
3	country
5	state
8	county
10	city
14	suburb
16	major streets
17	major and minor streets
18	building

About geometry types

The points_only argument controls whether the results contain only points. All Nominatim results have at least a point geometry.

When points_only = FALSE, the geometry type depends on the matching feature. Administrative areas and major buildings are returned as polygons, rivers and roads are returned as lines and amenities may still be returned as points.

This function is vectorized, allowing multiple addresses to be searched. With points_only = FALSE, multiple geometry types may be returned.

See Also

Reverse geocoding functions: reverse_geo_lite()

Spatial output functions: bbox_to_poly(), geo_address_lookup_sf(), geo_amenity_sf(), geo_lite_sf(), geo_lite_struct_sf()

Examples

library(ggplot2)

# Colosseum coordinates
col_lon <- 12.49309
col_lat <- 41.89026

# Colosseum as a polygon
col_sf <- reverse_geo_lite_sf(
  lat = col_lat,
  long = col_lon,
  points_only = FALSE
)

dplyr::glimpse(col_sf)

if (!all(sf::st_is_empty(col_sf))) {
  ggplot(col_sf) +
    geom_sf()
}

# City of Rome: same coordinates with zoom 10

rome_sf <- reverse_geo_lite_sf(
  lat = col_lat,
  long = col_lon,
  custom_query = list(zoom = 10),
  points_only = FALSE
)

dplyr::glimpse(rome_sf)

if (!all(sf::st_is_empty(rome_sf))) {
  ggplot(rome_sf) +
    geom_sf()
}

---