Skip to contents

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

Source: R/geo_lite_sf.R
geo_lite_sf.Rd

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.

Value

An sf object with the results that match the query.

Details

See https://nominatim.org/release-docs/latest/api/Search/ for additional parameters to be passed to custom_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

# \donttest{
# 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)
}

# }