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.

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close