suggest_places {arcgisgeocode}

Search Suggestion

Description

This function returns candidate locations based on a partial search query. It is designed to be used in an interactive search experience in a client facing application.

Usage

suggest_places(
  text,
  location = NULL,
  category = NULL,
  search_extent = NULL,
  max_suggestions = NULL,
  country_code = NULL,
  preferred_label_values = NULL,
  geocoder = default_geocoder(),
  token = arc_token()
)

Arguments

text

a scalar character of search key to generate a place suggestion.

location

an sfc_POINT object that centers the search. Optional.

category

a scalar character. Place or address type that can be used to filter suggest results. Optional.

search_extent

an object of class bbox that limits the search area. This is especially useful for applications in which a user will search for places and addresses within the current map extent. Optional.

max_suggestions

default NULL. The maximum number of suggestions to return. The service default is 5 with a maximum of 15.

country_code

default NULL. An ISO 3166 country code. See iso_3166_codes() for valid ISO codes. Optional.

preferred_label_values

default NULL. Must be one of "postalCity" or "localCity". Optional.

geocoder

default default_geocoder().

token

an object of class httr2_token as generated by auth_code() or related function

Details

Unlike the other functions in this package, suggest_places() is not vectorized as it is intended to provide search suggestions for individual queries such as those made in a search bar.

Utilizes the ⁠/suggest⁠ endpoint.

Value

A data.frame with 3 columns: text, magic_key, and is_collection.

Examples

# identify a search point
location <- sf::st_sfc(sf::st_point(c(-84.34, 33.74)), crs = 4326)

# create a search extent from it
search_extent <- sf::st_bbox(sf::st_buffer(location, 10))

# find suggestions from it
suggestions <- suggest_places(
  "bellwood",
  location,
  search_extent = search_extent
)

# get address candidate information
# using the text and the magic key
find_address_candidates(
  suggestions$text,
  magic_key = suggestions$magic_key
)