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_POINTobject 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
bboxthat 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. Seeiso_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_tokenas generated byauth_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.
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
)
#> Simple feature collection with 5 features and 61 fields
#> Geometry type: POINT
#> Dimension: XY
#> Bounding box: xmin: -84.34272 ymin: 33.74034 xmax: -84.34272 ymax: 33.74034
#> Geodetic CRS: WGS 84
#> input_id result_id loc_name status score match_addr
#> 1 1 NA <NA> M 100 Bellwood Coffee
#> 2 2 NA <NA> M 100 Bellwood Homes
#> 3 3 NA <NA> M 100 Bellwood, Atlanta, Georgia
#> 4 4 NA <NA> M 100 Bellwood Coffee
#> 5 5 NA <NA> M 100 Bellwood Church
#> long_label
#> 1 Bellwood Coffee, 1366 Glenwood Ave SE, Atlanta, GA, 30316, USA
#> 2 Bellwood Homes, 736 Jefferson St NW, Atlanta, GA, 30318, USA
#> 3 Bellwood, Atlanta, GA, USA
#> 4 Bellwood Coffee, 1776 Peachtree St NW, Atlanta, GA, 30309, USA
#> 5 Bellwood Church, Atlanta, GA, USA
#> short_label addr_type type_field place_name
#> 1 Bellwood Coffee POI Snacks Bellwood Coffee
#> 2 Bellwood Homes POI Other Shops and Service Bellwood Homes
#> 3 Bellwood Locality City Bellwood
#> 4 Bellwood Coffee POI Snacks Bellwood Coffee
#> 5 Bellwood Church POI Church Bellwood Church
#> place_addr phone url rank
#> 1 1366 Glenwood Ave SE, Atlanta, Georgia, 30316 <NA> <NA> 19
#> 2 736 Jefferson St NW, Atlanta, Georgia, 30318 (404) 977-5801 <NA> 19
#> 3 Atlanta, Georgia <NA> <NA> 20
#> 4 1776 Peachtree St NW, Atlanta, Georgia, 30309 <NA> <NA> 19
#> 5 Atlanta, Georgia <NA> <NA> 24
#> add_bldg add_num add_num_from add_num_to add_range side st_pre_dir
#> 1 <NA> 1366 <NA> <NA> <NA> <NA> <NA>
#> 2 <NA> 736 <NA> <NA> <NA> <NA> <NA>
#> 3 <NA> <NA> <NA> <NA> <NA> <NA> <NA>
#> 4 <NA> 1776 <NA> <NA> <NA> <NA> <NA>
#> 5 <NA> <NA> <NA> <NA> <NA> <NA> <NA>
#> st_pre_type st_name st_type st_dir bldg_type bldg_name level_type
#> 1 <NA> Glenwood Ave SE <NA> <NA> <NA>
#> 2 <NA> Jefferson St NW <NA> <NA> <NA>
#> 3 <NA> <NA> <NA> <NA> <NA> <NA> <NA>
#> 4 <NA> Peachtree St NW <NA> <NA> <NA>
#> 5 <NA> <NA> <NA> <NA> <NA> <NA> <NA>
#> level_name unit_type unit_name sub_addr st_addr block sector
#> 1 <NA> <NA> <NA> <NA> 1366 Glenwood Ave SE <NA> <NA>
#> 2 <NA> <NA> <NA> <NA> 736 Jefferson St NW <NA> <NA>
#> 3 <NA> <NA> <NA> <NA> <NA> <NA> <NA>
#> 4 <NA> <NA> <NA> <NA> 1776 Peachtree St NW <NA> <NA>
#> 5 <NA> <NA> <NA> <NA> <NA> <NA> <NA>
#> nbrhd district city metro_area subregion region region_abbr territory
#> 1 <NA> <NA> Atlanta <NA> DeKalb County Georgia GA <NA>
#> 2 <NA> <NA> Atlanta <NA> Fulton County Georgia GA <NA>
#> 3 <NA> Bellwood Atlanta <NA> Fulton County Georgia GA <NA>
#> 4 <NA> <NA> Atlanta <NA> Fulton County Georgia GA <NA>
#> 5 <NA> <NA> Atlanta <NA> Fulton County Georgia GA <NA>
#> zone postal postal_ext country cntry_name lang_code distance x
#> 1 <NA> 30316 <NA> USA United States ENG 0 -84.34272
#> 2 <NA> 30318 <NA> USA United States ENG 0 -84.41127
#> 3 <NA> <NA> <NA> USA United States ENG 0 -84.41243
#> 4 <NA> 30309 <NA> USA United States ENG 0 -84.39418
#> 5 <NA> <NA> <NA> USA United States ENG 0 -84.41521
#> y display_x display_y xmin xmax ymin ymax ex_info
#> 1 33.74034 -84.34272 33.74034 -84.34372 -84.34172 33.73935 33.74135 <NA>
#> 2 33.77591 -84.41127 33.77591 -84.41227 -84.41027 33.77491 33.77691 <NA>
#> 3 33.77455 -84.41243 33.77455 -84.42343 -84.40143 33.76355 33.78555 <NA>
#> 4 33.80282 -84.39418 33.80282 -84.39518 -84.39318 33.80182 33.80382 <NA>
#> 5 33.77288 -84.41521 33.77288 -84.42021 -84.41021 33.76788 33.77788 <NA>
#> extents geometry
#> 1 -84.34372, 33.73935, -84.34172, 33.74135 POINT (-84.34272 33.74034)
#> 2 -84.41227, 33.77491, -84.41027, 33.77691 POINT (-84.41127 33.77591)
#> 3 -84.42343, 33.76355, -84.40143, 33.78555 POINT (-84.41243 33.77455)
#> 4 -84.39518, 33.80182, -84.39318, 33.80382 POINT (-84.39418 33.80282)
#> 5 -84.42021, 33.76788, -84.41021, 33.77788 POINT (-84.41521 33.77288)