Search SDK for iOS
Current version:v2.7.0-beta.1
- Add pre-built UI components to your app
- Search for places by name, category, or coordinate
- Save your favorite places
- Access your search history
If you are using the Search SDK together with Mapbox Maps or Navigation SDK in your app, note that all the SDKs should have the same versions of the Common SDK for interoperability. The Common SDK versions used in each Mapbox SDK are provided in the corresponding release notes on GitHub:
The Mapbox Search SDK for iOS provides the necessary tools to integrate a search function into your app. This SDK offers multiple components that can either be used individually or in combination, allowing for a customized experience. You can quickly add a pre-built user interface to your app in a few minutes.
Structure of the Search SDK
The Search SDK consists of two frameworks: Search Core (MapboxSearch) and the Search UI SDK (MapboxSearchUI).
Search Core
The Search Core consists of classes that streamline the process of configuring, sending, and parsing search requests. It seamlessly interacts with the device to fetch its location and language settings. Additionally, it caches search results directly on the device and serves as the foundation for the Search UI SDK.
Search UI SDK
The Search UI SDK extends the Search Core, offering pre-designed search UI components for your application. These components allow for both style adjustments and result customization..
Supported Search Patterns
The Search SDK offers classes to do different types of search for addresses, places and POIs.
Search by Text
The PlaceAutocomplete class allows you to get the location of places by typing place names or addresses. This is also known as forward geocoding. For example, you can type in Lincoln Memorial and retrieve the geographic location of a place that matches that query (-77.050,38.889).
Search by Category
The Discover class allows you to select a category (for example, restaurants) and retrieve a list of points of interest (POIs) that belong to that category. For example, if you want to display restaurants within walking distance of a theater on a map, you can use category search with the restaurants category.
Search by Coordinate (Reverse geocoding)
You can also use the PlaceAutocomplete class to do reverse geocoding. Reverse geocoding allows you to retrieve place names and addresses by providing geographic coordinates. For example, entering -77.050, 38.889 and retrieve 2 Lincoln Memorial Circle NW.
Search History and Favorites
The Search SDK is designed to enhance user experience by utilizing past search data. If a user has before conducted searches in your application, the SDK will automatically suggest results from their search history. Additionally, if the user has a list of favorite search results, the SDK will not only suggest recent results but also include any favorites that correspond to the current query.
History
History includes the most recent search results chosen by a user on a device. Each time a user selects a result, the Search SDK automatically appends it to the user's history.
The Search UI SDK utilizes search history in the following ways:
- When a user clicks on the empty search bar, the SDK will automatically display recent searches in reverse chronological order.
- When a user begins to type a query, the SDK leverages the search history to populate the suggestions in the dropdown menu.
Additionally, you can access a device's search history using the Search Core via the ServiceProvider (ServiceProvider.shared.localHistoryProvider).
Favorites
"Favorites" refers to a collection of before executed searches that a user has deliberately saved for future use.
The Search UI SDK incorporates favorites in two distinct manners:
- Users have the ability to click on the star icon within the search results. This action triggers the favorites menu, enabling users to save the selected location.
- Users can also manage their saved favorites via the "Favorites" component. This feature allows users to delete or rename their saved favorites.
Developers can also retrieve a device's favorites using the Search Core. This can be achieved through the ServiceProvider class, specifically by using ServiceProvider(ServiceProvider.shared.localFavoritesProvider).
Why you should use the SDK?
If your search application is intended for mobile devices (iOS & Android), we highly recommend using our Search SDK. By using the Search SDK, you can enjoy:
Fewer lines of code
Developers can quickly start the SDK with a few lines of code. This ensures the code is easy to read, maintain, and less prone to errors.
Drop-in UI support
If you don't require a custom UI and are ready to get started, we've got you covered. Our Search SDK provides an easy-to-integrate UI that doesn't need extensive binding to your existing components and navigation flow.
Stable SDK API
Our goal is to support a consistent interface for our use cases, even when the underlying implementation evolves. This approach ensures that updating the SDK version will resolve any issues you may face, without necessitating changes to your application or its integration code.
Guarding Against Errors and Pitfalls
Having a pre-built integration example allows you to speed up experimentation and circumvent common issues associated with non-standard API usage.
Requirements
The Mapbox Search SDK for iOS can be used with iOS 11.0 and Xcode 11.3.
Pricing
The cost of using the Search SDK is determined by the specific Mapbox search service you use.
Several Mapbox services contribute to the underlying functionalities of the Search SDK. These services and their corresponding SDK modules are outlined below:
| Feature | SDK Class | API Endpoint | Pricing |
|---|---|---|---|
| Search by Text | PlaceAutocomplete(TEXT) | /search/v1/suggest | Search Box API (Sessions) |
| Search by Category | Discover() | /search/v1/category | Search Box API (Requests) |
| Search by Coordinate | PlaceAutocomplete(COORDINATE) | /search/v1/reverse | Search Box API (Requests) |
| Address Form Fill | AddressAutofill() | /autofill/v1 | Address Auto Fill (Sessions) |