Get Started | Search SDK | iOS

To use the Search SDK, you must first configure your credentials and then add the SDK as a dependency in your project. Here's a brief overview of the steps:

Configure credentials

To download and install the iOS SDK, follow the steps below. Start by logging into your Mapbox account, then create and configure a secret access token, and lastly add your public access token to your Info.plist.

Step 1: Log in/Sign up for a Mapbox account

If you haven't done so already, sign up for a Mapbox account and log into it.

You can sign up or sign in by clicking the buttons in the top right corner of your browser.

This account will allow you to create tokens and will create a default public token for you upon creation.

Step 2: Create a secret token

A secret token can enable access to various products/services at Mapbox, including the ability to download an SDK. To allow download access to an SDK, follow these steps:

From your account's tokens page, click the Create a token button.
From the token creation page, give your token a name and make sure the box next to the Downloads:Read scope is checked.
Click the Create token button at the bottom of the page to create your token.
The token you've created is a secret token, which means you will only have one opportunity to copy it somewhere secure.

Protect secret access tokens

Store secret tokens in secure a location, outside of your project folder to make sure unauthorized users cannot find it.

Step 3: Configure your secret token

To use your secret token, you will need to store it in a .netrc file in your home directory (not your project folder). This approach helps avoid accidentally exposing your secret token by keeping it out of your application's source code.

To create a .netrc file follow these steps:

Step 3-1: Check if you have already created a .netrc file on your computer.

Go to your home directory.
Type file .netrc into your terminal and see if anything returns.
If you have a .netrc file already, skip step 3-2.

Step 3-2: Create the .netrc file.

Open up your terminal in your home directory.
Type touch .netrc.

Step 3-3: Open the .netrc file.

Type open .netrc from the same terminal window from Step 3-2

Step 3-4: Add login instructions to the .netrc

To set up the credentials required to download the SDK, add the following entry to your .netrc file:


machine api.mapbox.com
login mapbox
password <INSERT SECRET ACCESS TOKEN>

Step 3-5: Set .netrc file permissions

Go to your home directory: /Users/[CurrentUser].
- If you do not see the .netrc file, press Command + Shift + .(the period key).
Right click on the .netrc.
Click Get Info.
Scroll down to Sharing & Permissions.
Under your current username, make sure to set Privilege to Read & Write.

Step 4: Configure your public token

To configure your public access token, follow these steps:

Open your project's Info.plist file
Hover over a key and click the plus button
Type MBXAccessToken into the key field
Click the value field and paste in your public access token.

Rotating Tokens

When you need to rotate your access token, you will need to update the token value in your Info.plist file.

GUIDE

Access token best practices

Learn how to keep access tokens private in mobile apps.

Add the dependency

Mapbox provides the Search SDK via Swift Package Manager and CocoaPods.

Swift Package Manager

CocoaPods

The Mapbox Search SDK can be consumed via Swift Package Manager (SPM). To add the Search SDK with SPM, you will need to configure your environment to download it from Mapbox. This requires a Mapbox access token with the Downloads:Read scope. In a previous step, you added this token to your .netrc file.

Open your Xcode project or workspace, then go to File > Swift Packages > Add Package Dependency.
Enter https://github.com/mapbox/search-ios.git as the URL, press Enter to pull in the package, and click Next.
Set Version to Exact and enter 2.5.0. Click Next.
Once Xcode finishes fetching and checking out all the dependencies, select the MapboxSearchUI library (or MapboxSearch if you don’t need any UI components). Click Next.
In your code, you can now import MapboxSearch as well as any of the other packages that were downloaded as dependencies.

Notes

If you need to update your packages, you can click on File > Swift Packages > Update To Latest Package Versions.
Sometimes, artifacts cannot be resolved or errors can occur, in this case select File > Swift Packages > Reset Package Cache.
If your Xcode crashes, delete your derived data folder.

Add search to an app

You can start by adding a search UI to your application using Swift.

Insert the following code snippets into your ViewController.


import UIKit
 
import MapboxSearch
 
import MapboxSearchUI

class ViewController: UIViewController {
 
    let searchController = MapboxSearchController()

    override func viewDidLoad() {
        super.viewDidLoad()
 
        searchController.delegate = self
 
        let panelController = MapboxPanelController(rootViewController: searchController)
 
        addChild(panelController)
    }
}

 
extension ViewController: SearchControllerDelegate {
 
    func searchResultSelected(_ searchResult: SearchResult) { }
 
    func categorySearchResultsReceived(category: SearchCategory, results: [SearchResult]) { }
 
    func userFavoriteSelected(_ userFavorite: FavoriteRecord) { }
 
}