iOS SearchKit SDK Quick Start and User Guide

Prerequisites

The user must be familiar with the Mac^® Operating System, Xcode^® development environment, and Objective-C^® programming language.
The Xcode (version 10 or above) must be installed.

Note	The iPhone^® Operating System (iOS) SearchKit Software Development Kit (SDK) supports Apple^® iOS Programming Interfaces (APIs) with a minimum version of 8.0 and above. This SDK targets the iOS APIs with version 12.4.

About API Key

The API key is used to track API requests of the project for usage and billing. API key often acts as a unique identifier and a secret token for authentication. The API key can be requested by filling in details and submitting the form at https://locationstudio.zendesk.com/hc/en-us/requests/new?ticket_form_id=360001758513.

Quick Start Steps

These following steps provide information to start using the iOS SearchKit SDK.

Getting the SDK

To obtain the iOS SDK, perform the following steps.

Go to https://git.location.studio/location.studio/iOSSDK.
Register or sign in to your existing Comtech Location Studio^® Git account.
If you created a new account, access it by clicking the Confirm your account link, sent to the registered email ID.
On home page under the Project tab, click on the download icon to save the iOS SDK zip package to your local drive. As an alternative, you can clone the repository to your local system, using the following command.

git clone https://git.location.studio/location.studio/iOSSDK.git

After you have downloaded and extracted the zip package or cloned the repository, follow the steps described in the next sections to begin using the SDK.

Getting Started
Creating a Suggestion Search Request
Creating a Single Search
- SingleSearchRequestDelegate
Category Search
Geocoding
Reverse Geocoding
- ReverseGeocodeRequest
SearchKit Errors
Building and Running the SearchKit Sample App
Appendix: Search Category Codes

Getting Started

Follow the next sections to perform a simple keyword search in a sample iOS application.

Project Setup

The following steps explain the project setup required to create a Search sample app using the iOS SearchKit SDK.

Start Xcode.
Start a new Xcode project.

Select Simple View App project and click Next.

Figure 1. Selecting Single View App

In the Choose options for your new project screen, enter your desired values for Product Name, Organization Name, and all other fields as shown in the following screenshot.

Note	iOS SDK supports both Objective-C and Swift™ programming languages. For this sample project, we are selecting Objective-C in the Language dropdown.

Figure 2. Configuring the Project

Note	Other types of available projects can also be selected during the project setup, but this tutorial uses Single View App project for easy understanding.

Dependency Setup

This section describes the dependency set up for iOS SearchKit SDK APIs. The SDK contains the following two libraries.

locationToolKitCommon.framework
SearchKit.framework

The following steps perform the dependency set up.

Import the locationToolKitCommon.framework as described in the following steps.
- Under the Build Phases tab, select the drop-down, Link Binary With Libraries and click the '+' icon highlighted in the following screenshot.

Figure 3. Adding Files to SearchSampleApp

In the Choose frameworks and libraries to add window, click Add Other, as highlighted in the following screenshot.

Figure 4. Clicking Add Other

Select LocationToolKitCommon.framework highlighted in the following screenshot and click Open to add it.

Figure 5. Selecting LocationToolKitCommon.framework

Locate SearchKit.framework in the Frameworks folder and repeat the activities in Step 1 to import the SearchKit.framework package.
Under the Build Phases tab, select the drop-down Link Binary With Libraries and add the frameworks listed below.
- libz.TBD
- CoreTelephony.framework
- libC++.1.tbd

The frameworks to be added are highlighted in the following screenshot.

Figure 6. Adding Frameworks

Adding Permissions to Info.plist File

First, add Search to the ViewController. Open ViewController.m and add the following code snippet before @interface ViewController ().

#import <LocationToolKitCommon/LTKContext.h>
#import <SearchKit/SingleSearchRequestWrapper.h>

Then, the following permissions must be declared inside the Info.plist file. These permissions are needed for network requests and for loading the search. You need to declare these permissions before using the SearchKit classes.

<key>NSAppTransportSecurity</key> <dict>
<key>NSAllowsArbitraryLoads</key>
<true/>
</dict>

The network permissions which must be enabled are highlighted in the following screenshot.

Figure 7. Adding Permissions in Info.plist File

Creating a Sample Search Request

This class is the entry point for the single search request. To create a sample search request you need to provide LTKContext, user location, and search location as shown in the following code snippet to perform a keyword search for “hotel".

SingleSearchRequestWrapper *searchRequest = [SingleSearchRequestWrapper singleSearchRequestWithContext:ltkContext keyWords:@"hotel"
currentLatitude:userLocation.latitude longitude:userLocation.longitude searchLatitude:searchLocation.latitude longitude:searchLocation.longitude];
[searchRequest setDelegate:Self];
[searchRequest startRequest];

Creating a LTKContext Object

For using the Location ToolKit (LTK) services, you must create a LTKContext object, a singleton instance of services through which you can configure the API Key, language, country, and so on as shown in the following code snippet. To get started, this code snippet is added to the ViewControllers’s viewDidLoad() method.

LTKContext* ltkContext = [[LTKContext alloc]
init:@"PUT_YOUR_API_KEY_HERE"
language:@"en-US"
countryCode:@"US"
mdn:nil
productName: @"default"
pushMessageGUID:nil];

Replace “PUT_YOUR_API_KEY_HERE”, with the API key received from Comtech, in the above code snippet.

Defining User Location

To make a search request, you need to provide the user location as shown in the following code snippet by setting the SKLatLonPoint.

SKLatLonPoint *userLocation =[[SKLatLonPoint alloc] init] ;
SKLatLonPoint *searchLocation = [[SKLatLonPoint alloc] init];

Building and Running the Sample App

Using the preceding code snippets in Getting Started, you can test the initialization and creation of the simple search request in the sample app. On building and running the sample app, you can see the search result shown below.

Figure 8. Search Result

Creating a Suggestion Search Request

The following code snippet shows creation of the Suggestion Search Request using the method suggestionRequestWithContext.

SKLatLonPoint *userLocation =[[SKLatLonPoint alloc] init] ;
SKLatLonPoint *searchLocation = [[SKLatLonPoint alloc] init];

userLocation.latitude = 33.580822;
userLocation.longitude = -117.736617;

searchLocation.latitude = 33.5596;
searchLocation.longitude = -117.792;

SingleSearchRequestWrapper *searchRequest =  [SingleSearchRequestWrapper suggestionRequestWithContext:ltcontext keyWords:@"SEARCH_TEXT" currentLatitude:userLocation.latitude longitude:userLocation.longitude searchLatitude:searchLocation.latitude longitude:searchLocation.longitude];
searchRequest.delegate = self;
[searchRequest startRequest];

Note	Replace the `“SEARCH_TEXT”` with the search input given in UISearchBar.

The following screenshot shows suggestion search results.

Figure 9. Suggestion Search

Creating a Single Search

This section describes the delegate and objects to facilitate a single search.

SingleSearchRequestDelegate

The SingleSearchRequestDelegate returns the search result. This acts as a delegate to provide the result of the single search request.

Various objects supported in this SingleSearchRequestDelegate are described in the following sections.

SKInformation

SKInformation object represents the search response. It returns complete search information, if search request is successful. It has methods to obtain the search results count and Point of Interest (POI) information, which includes distance, name, address, position, image, SKSuggestion and so on.

SKSuggestion

SKSuggestion represents a suggestion search result. Using this you can get the result count as well as matched locations along with their suggestion type, name, address, and so on from this.

If search request fails, an error is returned through NSError object. When search request is in progress, the NSInteger object updates the search status.

The following code snippet gives search results using the objects described above.

- (void)singleSearchRequest:(SingleSearchRequestWrapper*)request completeWithResultInformation:(SKInformation*)information;
- (void)singleSearchRequest:(SingleSearchRequestWrapper *)request failedWithError:(NSError*)error;
- (void)singleSearchRequest:(SingleSearchRequestWrapper *)request updateProgress:(NSInteger)progress;

Category Search

To perform category search, pass the categoryCode in searchRequest as shown in the following code snippet.

searchRequest = [SingleSearchRequestWrapper singleSearchRequestWithContext: ltkContext
categoryCode: searchCategory
currentLatitude:currentLatitude
longitude:currentLongitude
searchLatitude:searchLatitude
longitude:searchLongitude];

The following screenshot shows some of the categories available in the category search of iOS.

Figure 10. Available Search Categories In iOS

To know the details of search category codes, go to Appendix: Search Category Codes.

Geocoding

Geocoding is the process of converting addresses, like a street address, into geographic coordinates like latitude and longitude. These coordinates can be used to place markers on a map or to position the map. In SearchKit, there is no separate interface for geocoding, and it can be done using the same singleSearchRequest that is being used for keyword search. The matching locations are obtained when the SKInformation throws the SingleSearchRequestDelegate.

SingleSearchRequestWrapper *searchRequest = [SingleSearchRequestWrapper singleSearchRequestWithContext:ltkContext keyWords:@"City Hall Park, New York, USA"
currentLatitude:userLocation.latitude longitude:userLocation.longitude searchLatitude:searchLocation.latitude longitude:searchLocation.longitude];
[searchRequest setDelegate:Self];
[searchRequest startRequest];

Reverse Geocoding

Reverse geocoding is the process of converting geographic coordinates into a human-readable address.

ReverseGeocodeRequest

To create a reverse geocode request, you need to provide latitude and longitude through searchLocation. The response is returned through SearchRequestDelegate as shown in the following code snippet.

search = [SingleSearchRequestWrapper singleSearchRequestWithContext: ltkContext
location: searchLocation];

SearchKit Errors

Errors from SearchKit that occur while executing a search request are captured via SearchRequestDelegate as shown in the following code snippet.

- (void)singleSearchRequest:(SingleSearchRequestWrapper *)request failedWithError:(NSError*)error
{
NSLog(@"Search Error: %li - %@",(long)[error code],[error description]);
}

Building and Running the SearchKit Sample App

Comtech provides an example application SearchSampleApp that demonstrates various features of the iOS SearchKit SDK.

Use the following steps to import and run the SearchSampleApp project.

Browse to the path iOSSDK/SampleApp/SearchSampleApp.
Double-click the SearchSampleApp.xcodeproj highlighted in the following figure.

Figure 11. Importing the Project

Run the SearchSampleApp to explore various search features. The main screen has all the available search options.

Appendix: Search Category Codes

The following table describes various search category codes available in the iOS SearchKit SDK.

Table 1. Search Category Codes
Category	Code	Category	Code
Restaurants	AE	Houseware Stores	AKU
American	AEA	Office Supplies and Stationery Stores	AKV
Burger	AEOA	Wholesale Clubs	AKX
Bars and Nightclubs	AEC	Photographers	AKAA
Brewery/Pubs	AEOB	Photography Store	AKAB
Wine Bars	AEQJ	Children’s Clothing Store	AKAC
Chinese	AED	Men’s Clothing Store	AKAD
Coffee Shops	AEE	Women’s Clothing Store	AKAE
Fast Food	AEF	Shoe Store	AKAF
Indian	AEG	Pet Store	AKAG
Italian	AEH	All Health Care	AN
Sushi	AEOC	Dentists	ANA
Japanese	AEI	Hospitals	ANB
Mexican	AEJ	Pharmacies	ANC
Pizza	AEK	Chiropractors	AND
Seafood	AEL	Physicians	ANE
Vegan	AEOD	Dermatologists	ANEA
Vegetarian	AEM	Family Practice Physicians	ANEB
Barbecue/Southern	AEYA	Internal Medicine Physicians	ANEC
Californian	AEYC	Obstetricians and Gynecologists	ANED
Filipino	AEYD	Ophthalmologists	ANEE
French	AEYE	Pediatricians	ANEF
German	AEYF	Other Health Practitioners	ANEH
Greek	AEYG	Medical Laboratories	ANF
Hawaiian/Polynesian	AEYH	Nursing Homes and Residential Care Facilities	ANG
Jewish/Kosher	AEYI	Other Outpatient Care Centers	ANH
Korean	AEYJ	Psychiatric and Substance Abuse Hospitals	ANI
Bagels	AEOE	Specialty Hospitals	ANJ
Doughnuts	AEOF	Opticians and Optical Centers	ANK
Bakeries	AEOG	Optometrists	ANO
Argentinean	AEOH	Eye Care Centers	ANL
Brazilian	AEOI	Emergency Rooms	ANM
Peruvian	AEOJ	Urgent Care Clinics	ANN
Latin American	AEYK	Entertainment and Recreation	AB
Middle Eastern	AEYL	Nightclubs	ABM
Moroccan	AEOK	Casinos	ABB
Sandwich/Deli	AEYM	Conventions	ABC
Spanish	AEYN	Golf Courses	ABD
Steak House	AEYO	Movie Theaters	ABE
Thai	AEYP	Museums	ABF
Vietnamese	AEYQ	Amusement Parks	ABN
Cajun	AEOL	Amusement Places	ABO
Caribbean	AEOM	Parks	ABP
Bistro	AEON	Zoos	ABQ
British	AEOO	Aquariums	ABAC
Continental	AEOP	Stadiums and Arenas	ABR
Finnish	AEOQ	Performing Arts/Live Theaters	ABS
Grill	AEOR	Bowling Alleys	ABT
International	AEOS	Fishing	ABU
Russian	AEOT	Hunting	ABV
Snacks and Beverages	AEOU	Marinas	ABW
Breakfast	AEOV	Race Tracks	ABX
Chicken	AEOW	Ice Skating	ABY
Ice Cream	AEOX	Paint Ball	ABZ
Tapas	AEOY	Wineries	ABJ
Irish	AEOZ	Gambling	ABAA
Malaysian	AEPA	Comedy Clubs	ABAB
Fusion	AEPB	Banks and ATMs	AA
Creole	AEPC	ATMs	AAA
Creperie	AEPD	Banks	AAB
Pastries	AEPE	Currency Exchange	AAC
Indonesian	AEPF	Check Cashing	AAD
Fondue	AEPG	Public Offices and Services	AF
Chilean	AEPI	Police Stations	AFI
Azerbaijani	AEPJ	Courts	AFA
Baltic	AEPK	Libraries	AFB
Belorussian	AEPL	Police Stations	AFC
Caucasian	AEPM	Post Offices	AFD
African	AEPO	Schools	AFE
Australian	AEPR	Colleges/Universities	AFF
Austrian	AEPS	Fire Stations	AFG
Balkan	AEPT	Travel and Tourism	AL
Belgian	AEPU	Airports	ALA
Bohemian	AEPV	Tourist Attractions	ALF
Canadian	AEPX	Tourist Info	ALG
Dutch	AEPY	Historical Sites	ALD
East European	AEPZ	Landmarks	ALP
Hungarian	AEQA	Bus Stations	ALB
Maltese	AEQB	Car Rental	ALC
Polish	AEQC	Parking	ALE
Portuguese	AEQD	Train Stations	ALH
Scandinavian	AEQE	Car Service	ALI
Southwestern	AEQF	Limousine Service	ALJ
Surinamese	AEQG	Taxicabs	ALK
Swiss	AEQH	Airlines	ALL
Turkish	AEQI	Travel Agents	ALM
Logging	AH	Ferry Terminal	ALN
Hotels	AHC	Rest Area	ALO
Bed and Breakfasts	AHA	Personal Services	AI
Skiing and Ski Resorts	AHD	Barbers	AIJ
Campgrounds	AHB	Beauty Salons	AIK
R V Parks	AHF	Copying and Duplicating	AIB
Resorts	AHG	Laundries and Cleaners	AIF
Vacation Rentals	AHH	Mailing and Shipping Services	AIG
Shopping	AK	Churches	AIU
Department Stores	AKC	Synagogues	AIV
Grocery Stores	AKD	Temples	AIW
Malls and Shopping Centers	AKH	Mosques	AIX
Clothing Stores	AKI	Places of Worship	AII
Pharmacies	AKE	Automotive	AC
Retail Shops	AKF	Gas Stations	ACC
Sporting Goods	AKG	Auto Parts Stores	ACE
Convenience Stores	AKB	Auto Repair Shops	ACF
Book Stores	AKA	Oil Change Shops	ACG
Food Markets	AKJ	Tire Shops	ACH
Antiques	AKK	Auto Dealers	ACB
Florists	AKL	Auto Clubs	ACI
General Merchandise	AKM	Car Washes	ACJ
Hardware and Building Materials	AKN	Truck Stops	ACK
Liquor, Wine and Beer Stores	AKO	Motorcycle Dealers	ACL
Variety Stores	AKP	Auto Body Shops	ACM
Music Stores	AKQ	Truck Rental	ACN
Newsstands	AKR	Smog Inspection Stations	ACO
Lawn and Garden Stores	AKS	Electric Charging Stations	ACP
Furniture Stores	AKT

Note	To know more about all the interfaces and methods, see the SearchKit iOS API Reference Document