Created: 2012-03-22 22:41
Updated: 2013-12-13 03:27
License: other

Sensis SAPI Cocoa SDK SAPI Logo Yellow 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.


#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., 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:// 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 and

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/AFNetworking@3484605935a6ba68ee6dabe7c69efedb80ee08a7

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):


Getting a SAPI Application Key

For any of the SAPI requests to succeed, you need an API Key for the SAPI test environment. See for more information and 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

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://
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).



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

+ (void)setKey:
+ (void)setEnvironment

Header: SAPI.h


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


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


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


Implements the metadata endpoint for obtaining categories or categoryGroups metadata.

Headers: SAPIMetadata.hSAPIEndpoint.h

Relevant SAPI REST Docs: metadata endpoint


Implements the reporting endpoint.

Headers: SAPIReport.hSAPIEndpoint.h

Relevant SAPI REST Docs: report endpoint; Reporting Usage Events

Result Classes


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


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


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


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.

Cookies help us deliver our services. By using our services, you agree to our use of cookies Learn more