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.
-
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.
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
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.
-
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. |
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.
-
-
In the Choose frameworks and libraries to add window, click Add Other, as highlighted in the following screenshot.
-
Select LocationToolKitCommon.framework highlighted in the following screenshot and click Open to add it.
-
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.
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.
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.
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.
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.
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.
-
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.
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 |