Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Cocoa iOS/Mac SDK for the Sensis SAPI API

branch: master

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 Sensis SAPI.xcodeproj
Octocat-spinner-32 Sensis SAPI
Octocat-spinner-32 Sensis SAPITests
Octocat-spinner-32 Test iPhone App
Octocat-spinner-32 .gitignore
Octocat-spinner-32 .gitmodules
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.md
README.md

Sensis SAPI Cocoa SDK SAPI LogoYellow Pages Logo

The Sensis API (SAPI) gives you access to Australian local business listings from Yellow Pages and White Pages.

SAPI is implemented using a REST HTTP style and this project provides an easy to use Cocoa interface.

Synopsis

#import "SAPI.h"
#import "SAPISearch.h"

[SAPI setKey:@"your_sapi_application_key"];
[SAPI setEnvironment:SAPIEnvironmentTest];

SAPISearch * searchQuery = [[SAPISearch alloc] init];
searchQuery.query = @"Apple";

[searchQuery performQueryAsyncSuccess:^(SAPISearchResult *result) {

    NSLog(@"Page 1 of %d results: %@", result.totalPages, result.results);

} failure:^(SAPIError *error) {

    NSLog(@"Error fetching results: %@", [error localizedDescription]);

}];

See the Classes section below for information about the other endpoints SAPIGetListingById, SAPIReport and SAPIMetadata.

Table of Contents

Adding the SAPI SDK to your project

All you really need to do is add all the.m and .h files in the Sensis SAPI subfolder (ie. https://github.com/pumptheory/SAPI-Cocoa-SDK/tree/master/Sensis%20SAPI), and also add the AFNetworking library to your project (see next section).

While you can simply drag and drop the files, we recommend you use git as your source control and add the SAPI SDK as a git submodule. Something like this:

cd path/to/your/project_root
mkdir Externals
git add Externals
git submodule add git://github.com/pumptheory/SAPI-Cocoa-SDK.git Externals/SAPI-Cocoa-SDK

When you clone your project repository somewhere else, after the git clone you also need to:

git submodule init
git submodule update

To learn more about git submodules, see http://help.github.com/submodules/ and http://book.git-scm.com/5_submodules.html.

Adding AFNetworking

The Cocoa SAPI SDK uses AFNetworking under the hood. To avoid linking problems, you need to add AFNetworking to your project yourself. AFNetworking may change of course - the sample app successfully uses AFNetworking as at commit

AFNetworking is added very much like the SAPI SDK. See Getting Started with AFNetworking for suggestions on how you can add AFNetworking to your project.

JSON Library

The Cocoa SAPI SDK requires a JSON parsing library. If you are targeting iOS 5 or OSX 10.7 (or higher), the Apple supplied NSJSON* classes will be used automatically with no actions required on your part. If you are targeting iOS 4 or OSX 10.6, you need to add one of the following JSON libraries to your project:

If you have any of these in your project (even if you are targeting iOS5 or OSX 10.7), they will be automatically preferred in the above order. If you have one of the above libraries and yet prefer the SAPI SDK to use the builtin NSJON* classes, you can put this in your code early enough for it to be loaded prior to the first time the SAPI SDK or AFNetworking files are preprocessed (your .pch header is a good candidate):

#define _AFNETWORKING_PREFER_NSJSONSERIALIZATION_

Getting a SAPI Application Key

For any of the SAPI requests to succeed, you need an API Key for the SAPI test environment. See http://developers.sensis.com.au/docs/getting_started/Apply_for_an_API_key for more information and http://developers.sensis.com.au to register. Test environment keys are provisioned automatically so apart from clicking a link in the confirmation email there is no waiting. Information on applying for a Production environment key is also at http://developers.sensis.com.au/.

Running the Unit Tests and Sample App

After you clone the SAPI SDK git repository you need to update the submodules used by the SDK and the sample app and unit tests:

git clone git://github.com/pumptheory/SAPI-Cocoa-SDK.git
cd SAPI-Cocoa-SDK
git submodule init
git submodule update

You then need to edit Test iPhone App/SAPITestAccountKey.h and replace put_your_sapi_key_here with a valid SAPI test environment application key (see above).

The one Xcode project contains the sample test app that you can run (⌘-R) and unit tests for each endpoint (⌘-U).

Classes

SAPI

This class has two class methods you use to set the API key and environment

+ (void)setKey:
+ (void)setEnvironment

Header: SAPI.h

SAPIError

A subclass of NSError which is set in the case of an error that resulted in you getting no results. You will want to check the error code to eg. differentiate between a server error and rate limiting (in the latter case retrying may work). The relevant codes are detailed in the header file, and you can see examples of checking the code in the unit tests.

NB: the SAPI REST interface confuses successful response codes and HTTP codes somewhat which results in a not-quite 1:1 mapping between the integer codes used by Cocoa SDK and REST interface. The best bet is to stick to using the constants described in the header file.

Header: SAPIError.h

Relevant SAPI REST Docs: See the relevant endpoint docs and HTTP Status Codes

Request Classes

SAPISearch

Implements the SAPI search endpoint.

Create an instance of SAPISearch, set properties relevant to your search criteria (at least one of query or location are required, then perform the query using either the asynchronous or synchronous method:

- (void)performQueryAsyncSuccess:(void (^)(SAPISearchResult * result))successBlock
                         failure:(void (^)(SAPIError * error))failureBlock;
- (SAPISearchResult *)performQueryWithError:(SAPIError **)error;

Headers: SAPISearch.hSAPIEndpoint.h

Relevant SAPI REST Docs: Search endpoint

SAPIGetListingById

Implements the SAPI getListingById endpoint.

Create an instance of SAPIGetListingById, set the businessId property (which you obtained from the id key of a search result), then perform the query using either the asynchronous or synchronous method:

- (void)performQueryAsyncSuccess:(void (^)(SAPISearchResult * result))successBlock
                         failure:(void (^)(SAPIError * error))failureBlock;
- (SAPISearchResult *)performQueryWithError:(SAPIError **)error;

Headers: SAPIGetListingById.hSAPIEndpoint.h

Relevant SAPI REST Docs: getListingById endpoint

SAPIMetadata

Implements the metadata endpoint for obtaining categories or categoryGroups metadata.

Headers: SAPIMetadata.hSAPIEndpoint.h

Relevant SAPI REST Docs: metadata endpoint

SAPIReport

Implements the reporting endpoint.

Headers: SAPIReport.hSAPIEndpoint.h

Relevant SAPI REST Docs: report endpoint; Reporting Usage Events

Result Classes

SAPISearchResult

An instance of this is returned, or passed into the success block, in the case of a successful search or getListingById query (in the latter case there will always be only zero or one dictionary in the results array).

The main results are in the results property, as an array of dictionaries formatted exactly as the JSON is returned. See the header for information on other properties, and the Listing Schema for information on the possible contents of the results array of dictionaries.

Headers: SAPISearchResult.hSAPIResult.h

Relevant SAPI REST Docs: Search endpoint; Listing Schema

SAPIMetadataResult

An instance of this is returned, or passed into the success block, in the case of a successful metadata query. Set the dataType property to one of SAPIMetadataCategoriesKey or SAPIMetadataCategoryGroupsKey before executing the query. One of the categories or categoryGroups array properties are set - depending on which query was performed.

Headers: SAPIMetadataResult.hSAPIEndpoint.h

Relevant SAPI REST Docs: metadata endpoint

SAPIReportResult

An instance of this is returned, or passed into the success block, in the case of a successful report query. Different properties are required for different reporting types. See the header and HTTP docs for more info.

Headers: SAPIReportResult.hSAPIEndpoint.h

Relevant SAPI REST Docs: report endpoint

Reporting Usage Events

Requirements

Because the SDK (and AFNetworking) rely on blocks, iOS 4, Mac OSX Lion, or higher, are required.

ARC is not used by either the SDK or AFNetworking, so if your project is ARC based you need to use the -fno-objc-arc compiler flag for the SAPI SDK and AFNetworking classes. How to do this is discussed in Getting Started with AFNetworking.

Bugs & Enhancements

Please report any bugs using GitHub Issues and feel free to send GitHub pull requests for bug fixes or enhancements.

Brought to you by Sensis and Pumptheory

This Cocoa SAPI SDK was developed by Pumptheory for the Sensis SAPI Hackathons. Follow the @sensisapi Twitter account for information about upcoming hackathons near you.

Something went wrong with that request. Please try again.