Search suggestions

  • Call the getSearchSuggestions method on the ContextualSearchRuntime to retrieve search suggestions, customizing it with text or location-based context.

  • The returned SearchSuggestions object is opaque and primarily used for rendering suggestions within the UI.

  • Display search suggestion chips using SearchSuggestionsViewController in UIKit or SearchSuggestionsView in SwiftUI, ensuring they are integrated into your view hierarchy.

  • Location-based suggestions require setting latitude, longitude, radius, and optionally, start time and geo types within the LocationSuggestionsContext.

Get Suggested Searches

To get search suggestions, call the getSearchSuggestions method on the ContextualSearchRuntime. This method takes a single GetSearchSuggestionsOptions where you can specify the text to use to get search suggestions for.

The returned SearchSuggestions object does not contain any accessible properties. It contains all of the necessary information to render search suggestions, but otherwise is opaque.

Swift uses the Swift Concurrency style, Objective-C uses a callback function.

Swift

getSearchSuggestions(withOptions:)

Task {
    let suggestions = try await searchRuntime.getSearchSuggestions(
            withOptions: GetSearchSuggestionsOptions(withTextContext:['Sample Query', 'Another query string']))
}

Objective-C

getSearchSuggestionsWithOptions

  [searchRuntime
      getSearchSuggestionsWithOptions:
            [[GetSearchSuggestionsOptions alloc] initWithTextContext: @[@'Sample Query', @'Another query string' ]]
                             completionHandler:^(SearchSuggestions *_Nullable suggestions,
                                                 NSError *_Nullable error) {
                              // error will be not null if there is an error.
                              // On success, suggestions will be non null.
                            }];

Get Location-based Suggested Searches

The getSearchSuggestions request also supports location-based search suggestions. Build a GetSearchSuggestionsOptions object with a LocationSuggestionsContext.

Follow these steps to build the LocationSuggestionsContext class:

  1. (Required) Set latitude, longitude and radiusMeters to match the requested area.
  2. (Optional) Set startTime to match the requested time at which the search suggestions should apply.
  3. (Optional) Set geoTypes list with the requested geo types. Provided types are used to adjust the ranking and filtering of results returned by the service. The supported values are documented in LocationSuggestionsContext.

Swift

getSearchSuggestions(withOptions:)

Task {
    let locationContext: LocationSuggestionsContext = {
      let context = LocationSuggestionsContext()
      context.latitude = 40.748595
      context.longitude = -73.992365
      context.radiusMeters = 2500
      context.startTime = try?
        Date.ISO8601FormatStyle.iso8601.parse("2024-03-14T19:20:30.000+02:00")
      context.geoTypes = ["restaurant", "cafe"]
      return context
    }()
    let suggestions = try await searchRuntime.getSearchSuggestions(
            withOptions: GetSearchSuggestionsOptions(locationContext: [
              locationContext
            ]))
}

Objective-C

getSearchSuggestionsWithOptions


  LocationSuggestionsContext *locationContext;
  locationContext = [[LocationSuggestionsContext alloc] init];
  locationContext.latitude = 40.748595;
  locationContext.longitude = -73.992365;
  locationContext.radiusMeters = @2500;
  [searchRuntime
      getSearchSuggestionsWithOptions:
            [[GetSearchSuggestionsOptions alloc] initWithLocationContext: locationContext]
                             completionHandler:^(SearchSuggestions *_Nullable suggestions,
                                                 NSError *_Nullable error) {
                              // error will be not null if there is an error.
                              // On success, suggestions will be non null.
                            }];

Display

To display search suggestions chips, use the following methods (the style varies if you're using UIKit versus SwiftUI).

Swift UIKit

Display search suggestion chips using the SearchSuggestionsViewController.

// Create the SearchSuggestionsViewController with specified display options.
var searchSuggestionsController = SearchSuggestionsViewController(options: viewOptions)
...
// Add the view controller to the existing view hierarchy
searchSuggestionsController.addToViewContoller(self)
view.addSubview(searchSuggestionsController.view)
...
// Assign a specific set of search suggestions to this view controller.
searchSuggestionsController.searchSuggestions = suggestions

Objective-C

Display search suggestion chips using the SearchSuggestionsViewController.

// Create the SearchSuggestionsController with specified display options.
SearchSuggestionsViewController *_searchSuggestionsController =
      [[SearchSuggestionsViewController alloc] initWithOptions:_customizationOptions];
...
// Add the view controller to the existing view hierarchy
[_searchSuggestionsController addToViewController:self];
[self.view addSubview:_searchSuggestionsController.view];
...
// Assign a specific set of search suggestions to this view controller.
_searchSuggestionsController.searchSuggestions = suggestions

SwiftUI

Search suggestions can be displayed with a SearchSuggestionsView

SearchSuggestionsView(suggestions: suggestions, options: options)

Next: Display search results