> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/ios/navigation/llms.txt)

# Search SDK Integration

The Mapbox [Search SDK](https://docs.mapbox.com/ios/search/guides/) provides the tools to add a search experience to your navigation application. Integrating the Search SDK with your application allows users to search for locations by place name, address, category, or coordinate. It also provides access to search history and saves searches as Favorites.

You can provide a search programmatically to integrate the Search SDK into your application. Use your own UI implementation with the search API from `MapboxSearch` package for higher customization and flexibility.

Before starting to integrate your application with the Search SDK, you'll need to add the Search SDK as a dependency. Mapbox provides the Search SDK via CocoaPods and Swift Package Manager (SPM), but SPM is the recommended method for integrating the Search SDK. To install, follow the [steps](https://docs.mapbox.com/ios/search/guides/install/#add-the-dependency) for adding the Search SDK as a dependency to your application. The secret access token with `Downloads:Read` scope that you use for your Navigation SDK application will work.

> **Related content (troubleshooting): [Running into problems installing?](https://docs.mapbox.com/help/troubleshooting/ios-sdk-installation/)**
> 
> The Navigation SDK and Search SDK share a dependency. If the package manager fails to install the dependencies, check that the versions of the Navigation SDK and Search SDK have compatible versions of `MapboxCommon`. Read more about version compatibility issues in our troubleshooting guide.

## Integrating with the Search SDK

For the simplicity and speed of the Search SDK integration, we provide a ready-to-use search panel `SearchPanel`, but if you want higher customization and flexibility, you can use the Search API without predefined UI. For both options, there are a few things you will still need to make sure the Search SDK can interact with the Navigation SDK application.

### Send a search result to the Navigation SDK

A Search SDK selected query will return a [`SearchResult`](https://docs.mapbox.com/ios/search/api/core/2.28.3/Protocols/SearchResult.html) for the user's desired destination. A `SearchResult` is a search object with populated fields such as its result name, description, coordinates, and [`RoutablePoint`](https://docs.mapbox.com/ios/search/api/core/2.28.3/Structs/RoutablePoint.html)s that will allow you to display search results on the map as well as navigate to a desired result. After you retrieve a `SearchResult`, you will need to send it to the Navigation SDK to navigate to the desired result.

Here is an example of handling a search result selection:

```swift
func handleSearchResultSelection(_ searchResult: SearchResult) {
    let coordinate = searchResult.routablePoints?.first?.point ?? searchResult.coordinate
    var destinationWaypoint = Waypoint(coordinate: coordinate, name: "\(searchResult.name)")
    destinationWaypoint.targetCoordinate = searchResult.coordinate
    let navigationRouteOptions = NavigationRouteOptions(waypoints: [userWaypoint, destinationWaypoint])

    let task = mapboxNavigation.routingProvider().calculateRoutes(options: navigationRouteOptions)

    Task { [weak self] in
        switch await task.result {
        case let .failure(error):
            print(error.localizedDescription)

        case let .success(routes):
            guard let self else { return }

            navigationRoutes = routes
            // Handle NavigationRoutes
        }
    }
}
```

When implementing, hand the retrieved [`SearchResult`](https://docs.mapbox.com/ios/search/api/core/2.28.3/Protocols/SearchResult.html) itself to the Navigation SDK instead of using its coordinate or [`RoutablePoint`](https://docs.mapbox.com/ios/search/api/core/2.28.3/Structs/RoutablePoint.html)s individually.

[`searchResult.coordinate`](https://docs.mapbox.com/ios/search/api/core/2.28.3/Protocols/SearchResult.html#/s:12MapboxSearch0B6ResultP10coordinateSo22CLLocationCoordinate2DVvp) provides the center coordinates of a search result while [`searchResult.routablePoints`](https://docs.mapbox.com/ios/search/api/core/2.28.3/Protocols/SearchResult.html#/s:12MapboxSearch0B6ResultP14routablePointsSayAA13RoutablePointVGSgvp) provides coordinates that correspond to a building's entrance. Not all search results will include `RoutablePoint`s, but when included in the result you should use them to navigate the user to their destination.

The sample code above does this here:

`let coordinate = searchResult.routablePoints?.first?.point ?? searchResult.coordinate`

To set this coordinate as a destination for your user, create a [`Waypoint`](https://docs.mapbox.com/ios/navigation/api/3.28.3/navigation/documentation/mapboxdirections/waypoint/) with the `coordinate` and pass it as the destination waypoint. When requesting a route from the [Directions API](https://docs.mapbox.com/api/navigation/directions/) and using this `RoutablePoint` as a destination, the returned route will snap to the road and originate from the optimal direction. To further optimize the user experience you can set the [`Waypoint.targetCoordinate`](https://docs.mapbox.com/ios/navigation/api/3.28.3/navigation/documentation/mapboxdirections/waypoint/targetcoordinate/) to the building centerpoint and -- if you want your user to arrive curbside -- set [`Waypoint.allowsArrivingOnOppositeSide`](https://docs.mapbox.com/ios/navigation/api/3.28.3/navigation/documentation/mapboxdirections/waypoint/allowsarrivingonoppositeside/).

If you choose to display search results as annotations on the map, make sure to remove the results before displaying the route.

### Send coordinates from the Navigation SDK to the Search SDK

You can use the Search SDK's [`SearchEngine`](https://docs.mapbox.com/ios/search/api/core/2.28.3/Classes/SearchEngine.html) class to do reverse geocoding which allows users to search for place names and addresses by providing geographic coordinates. For example, the user can tap the map to find places nearby or see places near their destination.

If you want to long tap on the map and display places nearby, you can use the following code:

```swift
func navigationMapView(_: NavigationMapView, userDidLongTap mapPoint: MapPoint) {
    let searchOptions = ReverseGeocodingOptions(point: mapPoint.coordinate)
    searchEngine.reverse(options: searchOptions) { [weak self] geocodingResult in
        switch geocodingResult {
        case let .success(searchResults):
            guard let self else { return }
            // Display search results
            guard let searchResult = searchResults.first else { return }

            let view = UILabel() // Can be customized in any way
            view.text = searchResult.name
            view.backgroundColor = .white
            view.textAlignment = .center

            let annotation = ViewAnnotation(coordinate: searchResult.coordinate, view: view)
            annotation.variableAnchors = .all
            navigationMapView.mapView.viewAnnotations.removeAll()
            navigationMapView.mapView.viewAnnotations.add(annotation)
        case let .failure(searchError):
            print(searchError.localizedDescription)
        }
    }
}
```

> **Related content (guide): [View annotations](https://docs.mapbox.com/ios/maps/guides/markers-and-annotations/view-annotations/)**
> 
> Maps SDK guide on how to configure `ViewAnnotation`.

### Add an autocomplete search view to the navigation view

Besides displaying a user's favorites and search history, you can also add an autocomplete search view that suggests queries based on the input text using a custom search box. Incorporating autocomplete enhances the search experience by allowing the user to click on the desired result before finishing the query. As the user types in the query, results update in real-time and your application receives updates as [`SearchSuggestion`](https://docs.mapbox.com/ios/search/api/core/2.28.3/Protocols/SearchSuggestion.html)s through the [`SearchEngineDelegate`](https://docs.mapbox.com/ios/search/api/core/2.28.3/Protocols/SearchEngineDelegate.html) protocol.

```swift

searchEngine.delegate = self
searchEngine.query = textField.text!

// ...

extension ViewController: SearchEngineDelegate {
    func suggestionsUpdated(suggestions: [SearchSuggestion], searchEngine: SearchEngine) {
        // Handle suggestions
    }
    //...
}
```

A `SearchSuggestion` contains only enough information to display the suggestion in a list. To get a coordinate or detailed address information for navigation, pass the suggestion back to the [`SearchEngine.select(suggestion:)`](https://docs.mapbox.com/ios/search/api/core/2.28.3/Classes/SearchEngine.html#/s:12MapboxSearch0B6EngineC6select10suggestionyAA0B10Suggestion_p_tF) method in response to a user selection.

## Additional notes

Pricing for the Navigation SDK and Search SDK are calculated separately. For pricing information for the Search SDK, see the [pricing guide](https://docs.mapbox.com/ios/search/guides/#pricing).