Package 'location'

Geocode a place name string

Description

Queries the Nominatim geocoding API (OpenStreetMap) to look up coordinates for one or more place name strings. Returns a data frame with one row per input.

Usage

loc(
  x,
  limit = 1L,
  full = FALSE,
  api_url = "https://nominatim.openstreetmap.org"
)

Arguments

x	character vector of place names, e.g. "Jackson, TN" or "Davis Station, Antarctica".
limit	integer. Maximum number of results to return per query. Usually 1 is what you want. The Nominatim API caps this at 50.
full	logical. If TRUE, return all fields from the Nominatim response as list-columns. If FALSE (default), return only query, lon, lat, name, query, and osm_type.
api_url	base URL for the Nominatim API. Override to use a local instance: "http://localhost:7070".

Details

Results are cached for the duration of the R session, so repeated calls with the same query string are free. The cache can be inspected with loc_cache_show() and cleared with loc_cache_clear().

Nominatim's usage policy requires a descriptive User-Agent and a maximum rate of one request per second. loc() enforces the rate limit automatically and warns if the service is being queried heavily. See https://operations.osmfoundation.org/policies/nominatim/.

Value

A data frame with columns:

lon

longitude (numeric, or NA if not found)

lat

latitude (numeric, or NA if not found)

name

full place name as returned by Nominatim

query

the original input string

osm_type

OSM object type: "node", "way", or "relation"

When full = TRUE, all additional Nominatim fields are included as list-columns.

Examples

## Not run: 
loc("Hobart")
loc("Jackson, TN")
loc(c("Davis Station", "Casey Station", "Mawson Station"))

# repeated calls hit the cache, not Nominatim
loc("Hobart")

# inspect what's been cached this session
loc_cache_show()

## End(Not run)

---

Clear the session cache

Description

loc() caches results within the R session so repeated queries don't hit Nominatim again. Call this if you need fresh results, e.g. after updating your query strings.

Usage

loc_cache_clear()

Value

invisibly NULL

---

Show the session cache

Description

Show the session cache

Usage

loc_cache_show()

Value

a data frame of all cached results, or an empty data frame if the cache is empty.

---

Look up the timezone for a place name

Description

A convenience wrapper that geocodes a place name with loc() and then looks up the IANA timezone via the lutz package.

Usage

loc_tz(x, method = "fast", ...)

Arguments

x	character vector of place names.
method	passed to lutz::tz_lookup_coords(): "fast" (default, Rcpp-based, no sf dependency) or "accurate" (sf polygon intersection).
...	passed to loc().

Value

A character vector of IANA timezone names (e.g. "America/Chicago"), the same length as x. NA where geocoding or timezone lookup failed.

Examples

## Not run: 
loc_tz("Jackson, TN")
loc_tz("Davis Station, Antarctica")
loc_tz(c("Hobart", "McMurdo"))

## End(Not run)

---