Quickstart with the Swift API client

Supported platforms

The Algolia Swift API client requires Swift version 5.0 or later and supports iOS, macOS, tvOS, and watchOS platforms.

Install

Install via Swift Package Manager

To add the API client to your Swift project, follow these steps:

1. Open your project in Xcode.

2. Go to File > Add Packages. In the search, enter the URL to the GitHub repository of the API client:

   Copy

   1
   https://github.com/algolia/algoliasearch-client-swift
   

   Select the package algoliasearch-client-swift and click Copy Dependency.

3. If you have a Package.swift file, add the repository as a dependency:

   Swift

   Copy

   1
   2
   3
   4
   5
   6
   7
   8
   9
   10
   11
   12
   13
   14
   15
   16
   17
   18
   19
   20
   let package = Package(
     dependencies: [
       .package(
         url: "https://github.com/algolia/algoliasearch-client-swift",
         from: "8.0.0"
       )
     ],
     targets: [
       // Add the client as dependency to your targets
       .executableTarget(
         name: "algolia-example",
         dependencies: [
           .product(
             name:"AlgoliaSearchClient",
             package: "algoliasearch-client-swift"
           )
         ]
       )
     ]
   )
   

Install via CocoaPods

To install the Algolia Swift API client with CocoaPods, add the following line to your Podfile:

1
pod 'AlgoliaSearchClient', '~> 8.0'

Then, run the following command:

1
pod update

Install via Carthage

To install the Algolia Swift API client with Carthage, add the following line to your Cartfile:

1
github "algolia/algoliasearch-client-swift" ~> 8.0.0

In your project directory, run these commands:

1
2
3
carthage update
./Carthage/Checkouts/algoliasearch-client-swift/carthage-prebuild
carthage build

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
3
4
import AlgoliaSearchClient

let client = SearchClient(appID: "YourApplicationID", apiKey: "YourWriteAPIKey")
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 frontend, nor share it with anyone. In your frontend, only use the search-only API key or any other key that has search-only rights.

If you’re building a native app on mobile, don’t 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 contacts in the contacts index using the following code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
struct Contact: Encodable {
  let firstname: String
  let lastname: String
  let followers: Int
  let company: String
}

let contacts: [Contact] = [
  .init(firstname: "Jimmie", lastname: "Barninger", followers: 93, company: "California Paint"),
  .init(firstname: "Warren", lastname: "Speach", followers: 42, company: "Norwalk Crmc")
]

let index = client.index(withName: "contacts")
index.saveObjects(contacts, autoGeneratingObjectID: true) { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}

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
8
9
10
let settings = Settings()
  .set(\.customRanking, to: [.desc("followers")])
index.setSettings(settings) { result in
  switch result {
  case .failure(let error):
    print("Error when applying settings: \(error)")
  case .success:
    print("Success")
  }
}

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

Algolia suggests results as you type, which means you’ll generally search by prefix. In this case, the order of attributes is crucial in deciding which hit is the best.

1
2
3
4
5
6
7
8
9
10
let settings = Settings()
  .set(\.searchableAttributes, to: ["lastname", "firstname", "company", "email", "city", "address"])
index.setSettings(settings) { result in
  switch result {
  case .failure(let error):
    print("Error when applying settings: \(error)")
  case .success:
    print("Success")
  }
}

Search

Once configured, you can search for contacts by attributes such as firstname, lastname, or company (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: "jimmie") { result in
  if case .success(let response) = result {
    print("Response: \(response)")
  }
}
// Search for a first name with typo
index.search(query: "jimie") { result in
    if case .success(let response) = result {
      print("Response: \(response)")
    }
}
// Search for a company
index.search(query: "california paint") { result in
    if case .success(let response) = result {
      print("Response: \(response)")
    }
}
// Search for a first name and a company
index.search(query: "jimmie paint") { result in
    if case .success(let response) = result {
      print("Response: \(response)")
    }
}