Quick Start with the iOS API Client

Supported platforms

The API client is supported on iOS, macOS, tvOS and watchOS. You can use it from both Swift and Objective-C.

Install

• Add a dependency on InstantSearchClient:
  • CocoaPods: add pod 'InstantSearchClient', '~> 6.0' to your Podfile for Swift 4.2
  • CocoaPods: add pod 'InstantSearchClient', '~> 5.0' to your Podfile for Swift 4.1
  • Carthage: add github "algolia/algoliasearch-client-swift" ~> 6.0.0 to your Cartfile for Swift 4.2
  • Carthage: add github "algolia/algoliasearch-client-swift" ~> 5.0.0 to your Cartfile for Swift 4.1
• Add import InstantSearchClient to your source files

Quick Start

In 30 seconds, this quick start tutorial will show you how to index and search objects.

Initialize the client

To start, you need to initialize the client. To do this, you need your Application ID and API Key. You can find both on your Algolia account.

1
2
let client = Client(appID: "YourApplicationID", apiKey: "YourAdminAPIKey")
let index = client.index(withName: "your_index_name")

The API key displayed here is your Admin API key. To maintain security, never use your Admin API key on your front end, nor share it with anyone. In your front end, use the search-only API key or any other key that has search-only rights.

If you are building a native app on mobile, make sure not to include the search API key directly in the source code. You should instead consider fetching the key from your servers during the app’s startup.

Push data

Without any prior configuration, you can start indexing 500 contacts in the contacts index using the following code:

1
2
3
4
5
6
7
8
// Load content file
let jsonURL = Bundle.main.url(forResource: "contacts", withExtension: "json")
let jsonData = try! Data(contentsOf: jsonURL!)
let dict = try! JSONSerialization.jsonObject(with: jsonData!)

// Load all objects in the JSON file into an index named "contacts"
let index = client.index(withName: "contacts")
index.addObjects(dict["objects"])

Configure

You can customize settings to fine tune the search behavior. For example, you can add a custom ranking by number of followers to further enhance the built-in relevance:

1
2
3
4
5
6
7
let customRanking = ["desc(followers)"]
let settings = ["customRanking": customRanking]
index.setSettings(settings, completionHandler: { (content, error) -> Void in
    if error != nil {
        print("Error when applying settings: \(error!)")
    }
})

You can also configure the list of attributes you want to index by order of importance (most important first).

Algolia is designed to suggest results as you type, which means you’ll generally search by prefix. In this case, the order of attributes is crucial to decide which hit is the best.

1
2
3
4
5
6
7
let customRanking = ["lastname", "firstname", "company", "email", "city", "address"]
let settings = ["searchableAttributes": customRanking]
index.setSettings(settings, completionHandler: { (content, error) -> Void in
    if error != nil {
        print("Error when applying settings: \(error!)")
    }
})

Search

You can now search for contacts by firstname, lastname, company, etc. (even with typos):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Search for a first name
index.search(Query(query: "jimmie"), completionHandler: { (content, error) -> Void in
    if error == nil {
        print("Result: \(content)")
    }
})
// Search for a first name with typo
index.search(Query(query: "jimie"), completionHandler: { (content, error) -> Void in
    if error == nil {
       print("Result: \(content)")
    }
})
// Search for a company
index.search(Query(query: "california paint"), completionHandler: { (content, error) -> Void in
    if error == nil {
       print("Result: \(content)")
    }
})
// Search for a first name and a company
index.search(Query(query: "jimmie paint"), completionHandler: { (content, error) -> Void in
    if error == nil {
        print("Result: \(content)")
    }
})