Swiftpack.co - Package - algolia/algoliasearch-client-swift

Build Status Carthage compatible SwiftPM Compatible CocoaPods CocoaPods Swift 4.0 Objective-C compatible

Algolia Search API Client for Swift and Objective-C

Algolia Search is a hosted full-text, numerical, and faceted search engine capable of delivering realtime results from the first keystroke. The Algolia Search API Client lets you easily use the Algolia Search REST API from your Swift code.

That being said, the library is 100% compatible with Objective-C

As a complement to this readme, you can browse the automatically generated reference documentation. (See also the offline-enabled version.)

API Documentation

You can find the full reference on the Algolia's website.

Table of Contents

  1. Supported platforms

  2. Install

  3. Quick Start

  4. Getting Help

Getting Started

Supported platforms

Our Swift client is supported on iOS, macOS, tvOS and watchOS, and is usable from both Swift and Objective-C.

Install

  1. Add a dependency on InstantSearchClient:
    • CocoaPods: add pod 'InstantSearchClient', '~> 5.0' to your Podfile.
    • Carthage: add github "algolia/algoliasearch-client-swift" to your Cartfile.
    • SwiftPM: add .package(url:"https://github.com/algolia/algoliasearch-client-swift", from: "5.0.0") to your package dependencies array in Package.swift, then add InstantSearchClient to your target dependencies.
  2. 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

You first need to initialize the client. For that you need your Application ID and API Key. You can find both of them on your Algolia account.

let client = Client(appID: "YourApplicationID", apiKey: "YourAPIKey")

Push data

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

// 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"])

Search

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

// search by firstname
index.search(Query(query: "jimmie"), completionHandler: { (content, error) -> Void in
	if error == nil {
		print("Result: \(content)")
	}
})
// search a firstname 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 firstname & company
index.search(Query(query: "jimmie paint"), completionHandler: { (content, error) -> Void in
	if error == nil {
		print("Result: \(content)")
	}
})

Configure

Settings can be customized to tune the search behavior. For example, you can add a custom sort by number of followers to the already great built-in relevance:

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 (first = most important):

Note: Since the engine is designed to suggest results as you type, you'll generally search by prefix. In this case the order of attributes is very important to decide which hit is the best:

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!)")
	}
})

Notes

Previous Objective-C API Client

In July 2015, we released a new version of our Swift client, able to work with Swift and Objective-C. As of version 3 (April 2016), Swift has become the reference implementation for both Swift and Objective-C projects. The Objective-C API Client is no longer under active development. It is still supported for bug fixes, but will not receive new features. If you were using our Objective-C client, read the migration guide from Objective-C.

Migration guides

If you were using version 2.x of our Swift client, read the migration guide to version 3.x.

Swift 3

You can use this library with Swift by one of the following ways:

  • pod 'AlgoliaSearch-Client-Swift', '~> 4.8.1'
  • pod 'AlgoliaSearch-Client-Swift', :git => 'https://github.com/algolia/algoliasearch-client-swift.git', :branch => 'swift-3'

Getting Help

Github

link
Stars: 111
Help us keep the lights on

Dependencies

Used By

Total:

Releases

5.1.7 - May 4, 2018

Bug Fix

Aggregate "facet_stats" to the response when doing disjunctive faceting #522 Also fix a memory leak coming from NRURLSession #522

5.0.3 - Oct 3, 2017

New features

  • Index: Add deleteBy method and deprecate deleteByQuery method
  • PlacesClient: Add getObject(withID:completionHandler) method

5.0.1 - Oct 3, 2017

Support for Swift 4

4.8.1 - Apr 18, 2017

Miscellaneous changes

  • [offline] Better error reporting when building offline indices

4.8 - Apr 3, 2017

New features

  • Compatibility with Swift 3.1. (#294) Note: Swift 3.1 being source-compatible with Swift 3.0, version 4.7 was already compatible out of the box, but this one eliminates a few compile-time warnings.
  • Support new search parameters in the Query class:
    • disableExactOnAttributes (#369)
    • offset & length (#369)
    • percentileComputation (#365)
    • restrictHighlightAndSnippetArrays (#366)
  • Properties of the query classes (AbstractQuery and its derivates) are now KVO-observable (#339)
  • Add an option to choose a custom queue for completion handlers (#334). By default, the main queue is used.

Other changes

  • The userAgents property (managing the User-Agent HTTP header) is now a static property of the Client class. This should ease its use by other libraries, most notably InstantSearch Core.
  • [offline] Unify Index and OfflineIndex under a new Searchable protocol. This makes possible generic algorithms that work with any kind of index (MirroredIndex being a subclass of Index already).
  • Shorter README. The complete reference is now only on https://www.algolia.com/doc/api-client/swift/.