Search Suggestion

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

Value

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

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)

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.