Alohar SDK Reference


Alohar offers a mobile device Location Behavior Platform allowing developers to respond user behaviors by analyzing location and device sensor data. Alohar delivers real time device data from location, motion, wifi and timing data. Its advanced functionality gives competitive advantages in applications than a conventional location based services (LBS) platform.

Alohar platform is now available for iOS SDK and Android SDK. Alohar SDK is ideal for applications such as smart personal assistants, location-based games, mobile health apps, mobile shopping/coupon apps, social networking apps and mobile dating apps.

Smart things you can do with the Alohar SDK

The beauty of the Alohar SDK is that you can focus on your application-specific functionalities, rather than low level user location and behavior, and therefore achieve a fast time to market.

For Alohar Beginners. We recommend you to review getting started guide. For details on a method or class, please refer to the Alohar API documentation.

Alohar SDK Requirements

Alohar SDK requires Xcode 4.2+ for development, and iOS 5.0+ for both development and distribution and to access advanced location features of iOS. You can update your software from Apple's developer portal:

Initialization / Session Delegate

Alohar SDK provides a single global interface to manage its core service and other major components. Developer can manage the core service, place manager and motion manager within Alohar SDK. By calling the register or authenticate methods, a new Alohar session is initialized and monitoring can begin.

Alohar handles the developer’s identity in an anonymous fashion. The developer manages the authentication of their own application end-users. Alohar does not require the identity of the users of the third-party application. Instead, the application developer only provides an anonymous user id to Alohar, which Alohar uses to manage each user’s data. This way, Alohar never sees the real identity of the user of the developer’s application.

Alohar SDK requires the app developer to register each of their user with the Alohar SDK using [Alohar registerWithAppID:andAPIKey]. Note that the developer does not need to pass the application-specific username to Alohar SDK. registerWithAppID generates a unique UserId (UID). This UserId is for Alohar SDK to manage the specific user’s info.

It is the developer’s responsibility to record the unique UID generated by register() to do authentication and retrieve data from Alohar in the future. The developer is responsible to maintain the mapping of their users and the Alohar userids.

The second time the app is run for the specific user, the app uses the UID and calls Alohar.authenticate() from Alohar context to authenticate the user. Once the user is authenticated, the app can start to manage the core service and access user information from Alohar platform.

User Registration

After the Alohar context is initialized, the developer needs to register and authenticate their user in Alohar system. Alohar SDK manages the authentication and authorization and securely communicate with the Alohar servers.

To register a new end user of the developer’s app, use the following register method of the Alohar class, which returns an unique UserID (UID) if the call is valid. Again, your app must manage the userID to allow data retrieval in the future.

Active Methods


Call this method to start an Alohar session for a new user. Your app ID and API key are used to associate this user with your Alohar developer account.

You can obtain AppleID by following the steps in getting started guide.

+ (void)registerWithAppID:(NSString *)appID
                andAPIKey:(NSString *)APIKey


[Alohar registerWithAppID:@"appID" 


Use this method when you have an existing user token to associate this account with. This is only necessary for associating a single user across multiple devices.

+ (void)authenticateWithAppID:(NSString *)appID
                    andAPIKey:(NSString *)APIKey
                    andUserID:(NSString *)userID


This starts the motion and location monitoring, which is necessary for collection of userstays and motion state. .

[Alohar startMonitoringUser]


This ends the motion and location monitoring, which is necessary for collection of userstays and motion state. When this method is called, all user data collection and transmission is stopped. No further location data or motion data will be available until startMonitoringUser is called again.

[Alohar stopMonitoringUser]



This method is called by Alohar when a user is successfully logged in. The user ID is a globally unique NSString that identifies that user across devices. If you pass this ID in the authentication method, Alohar will be able to use the existing user data across devices and installs. This callback is a good time to call startMonitoring user to begin data collection.

- (void)aloharDidLogin:(NSString *)userID;


This method is called when there is an issue with the Alohar service. This can be due to a failed signup/login, or an unexpected termination of service. This method will also be called when location is not available for a user (it can be determined by user preference or caused by device issues).

- (void)aloharDidFailWithError:(NSError *)error;

Request Delegate

Alohar's request structure allows queries to be made against the collected data. Each of these queries uses blocks to return the results asynchronously. Here's an example:


+ (void)getDetailsForStay:(NSInteger)stayId
               completion:(void (^)(ALResponse *response, NSError *error))completion;


[Alohar getDetailsForStay:stayID completion:^(ALResponse *response, NSError *error) {
    if (error) {
        NSLog(@"Request Failed. Error %@", error);
    } else {
        NSLog(@"Request Succeeded!");
        //The resulting user stay is stored in the variable 'response'

Active Methods

There are several methods to search through a user's stay history.


Calling this method with an NSDate will return all user stays that overlap with that 24-hour period.

+ (void)getUserStaysForDate:(NSDate *)date
                 completion:(void (^)(ALResponse *response, NSError *error))completion;


This method returns all user stays that overlap with the period between two NSDates.

+ (void)getUserStaysFromDate:(NSDate *)startDate
                      toDate:(NSDate *)endDate
                  completion:(void (^)(ALResponse *response, NSError *error))completion;


Get user's user stays within a time period and a location boundary.

 + (void)getUserStaysFromDate:(NSDate *)startDate
                       toDate:(NSDate *)endDate
                   atLocation:(CLLocation *)location
                       radius:(NSInteger)radius limit:(NSInteger)limit
                   completion:(void (^)(ALResponse *response, NSError *error))completion;


This method returns all ALPlaces that the user has ever visited. NOTE: The response size depends on total number of visits -- for long-term users, this can be hundreds of KB. We recommend using getPlaces:withCategory:withDelegate to return more manageable results.

 + (void)getAllPlacesWithCompletion:(void (^)(ALResponse *response, NSError *error))completion;


This method returns all ALPlaces that match the namePattern regex NSString passed to it. For example, passing @"^McDo" will return all places with names that start with @"McDo" (likely a list of McDonalds visits).

+ (void)getPlacesWithPattern:(NSString *)namePattern
                  completion:(void (^)(ALResponse *response, NSError *error))completion;


This method returns all ALPlaces that match the namePattern regex NSString passed to it. For example, calling [Alohar getPlaces:@".*" withCategory:@"^rest" withDelegate:self] will return all places with categories starting with rest -- likely a list of restaurants and possibly rest stops.

+ (void)getPlacesWithPattern:(NSString *)namePattern
                andCategory:(NSString *)catPattern
                  completion:(void (^)(ALResponse *response, NSError *error))completion;


This is the most advanced filter we provide for user stays. See the "Parameters" section below for guidance on each value.

+ (void)getPlacesWithPattern:(NSString *)namePattern
         fromDate:(NSDate *)startDate
           toDate:(NSDate *)endDate
     withCategory:(NSString *)catPattern
       completion:(void (^)(ALResponse *response, NSError *error))completion;


This method returns all of the possible places a user stay could refer to. The Alohar SDK attempts to choose the right place, but orders all possibilities into a candidate list.

+ (void)getPlaceCandidatesForStay:(NSInteger)stayId
                       completion:(void (^)(ALResponse *response, NSError *error))completion;


This method returns all user stays for a given place.

+ (void)getStaysForPlace:(NSInteger)placeId
              completion:(void (^)(ALResponse *response, NSError *error))completion;


This method returns the full details for a place.

+ (void)getDetailsForPlace:(NSInteger)placeId
                completion:(void (^)(ALResponse *response, NSError *error))completion;


This method returns the full details for a user stay.

+ (void)getDetailsForStay:(NSInteger)stayId
               completion:(void (^)(ALResponse *response, NSError *error))completion;

Change Delegate

The change delegate allows you to receive callbacks when the user's state changes. This includes motion state (e.g. walking, driving), as well as location and user stay updates.

Active Methods


Use this method to register for motion state callbacks. If Alohar is currently monitoring the user (see startMonitoringUser), Alohar will call didUpdateToMotionState:fromMotionState on this delegate when the user changes their motion state.

+ (void)setMotionDelegate:(id <ALMotionDelegate>)delegate;


Use this method to register for user stay callbacks. If Alohar is currently monitoring the user (see startMonitoringUser), Alohar will call userArrivedAtPlaceWithLocation, currentUserStayIdentified, and userDepartedPlaceWithLocation on this delegate (see callback descriptions below).

+ (void)setUserStayDelegate:(id <ALUserStayDelegate>)delegate;



This callback is sent to the delegate when Alohar detects that the user has changed their motion state. See the ALMotionState object for possible user states.

- (void)didUpdateToMotionState:(ALMotionState *)newMotionState 
           fromMotionState:(ALMotionState *)oldMotionState;


This callback is sent to the delegate when Alohar detects that the user has arrived at a new place. This callback includes latitude and longitude with a optional personal place if it is close enough to the centroid of the arrival -- once the final place of the stay has been determined, the delegate will receive currentUserStayIdentified.

- (void)userArrivedAtPlace:(ALPlace *)personalPlace withLocation:(CLLocation *)location;


This callback is sent to the delegate when Alohar detects that the user has left their current place. This callback includes the latitude and longitude of the place the user has left.

- (void)userArrivedAtPlaceWithLocation:(CLLocation *)location;


This callback is sent to the delegate when Alohar detects a new user stay. This ALUserStay object includes location, place name, and several other valuable pieces of data. See the ALUserStay object for further details.

- (void)currentUserStayIdentified:(ALUserStay *)newStay;


This callback is sent to the delegate when an error occurs with either motion state or user stays

- (void)aloharDidFailWithError:(NSError *)error;

Non-delegate methods

These methods return immediately. They are called directly on the Alohar class -- for example, to get the current user stay, simply call [Alohar currentUserStay].


This returns the user stay the user is currently in, or nil if no user stay exists.

+ (ALUserStay *)currentUserStay;


This returns the latest known location for the user.

+ (CLLocation *)currentLocation;


This returns the current motion state for the user. See ALMotionState for possible states.

+ (ALMotionState *)currentMotionState;


This method returns TRUE if the device is not moving, FALSE in all other cases.

+ (BOOL)isStationary;


This method returns FALSE if the user is currently staying at a place, TRUE in all other cases.

+ (BOOL)isBetweenUserStays;


This method can be used to see if Alohar is tracking the user, and will return TRUE if user monitoring is on.

+ (BOOL)monitoringUser;


This method returns TRUE if the user has valid credentials and has an active Alohar session, FALSE in all other cases.

+ (BOOL)isLoggedIn;


Alohar provides a few useful object types to give more data details.


The ALUserStay object represents a user's visit to a place.


NSInteger stayID The unique identifier for this user stay

CLLocation *centroidLocation The estimated location of the user stay

NSInteger startTime Unix time the user arrived at this location

NSInteger endTime Unix time the user left this location

ALPlace *selectedPlace The place Alohar believes corresponds to this visit

NSArray *candidates The full list of possible place options


The ALPlace object represents a point of interest, e.g. a coffee shop.


NSInteger placeID; The unique identifier for this place

NSInteger visitCount The number of times the user has visited this place

NSString *name *The name of this place, e.g. "Pizza Hut"

CLLocation *location The location of the center of this place.

NSString *address The street address

NSString *phone The phone number if available

NSString *iconURL URL for an icon that depicts this place's category

NSString *webURL URL for the Google Places page for this place

NSString *category Description of the type of place, e.g. Home

NSString *subCategory More detailed description, e.g. Italian Bistro


The ALMotionState object represents a category of motion from the user.

Possible Motion States:

NSNumber *state The raw state value (see above to find the meaning of each number

Call [motionState stateDiscription] for a pretty NSString version of the current state. Possible values are Stationary, Big Move, Driving, Walking, and unknown.

- (NSString *)stateDescription;


The ALMobileState object represents a category of high level movement from the user.

Possible Mobile States:

NSNumber *state The raw state value (see above to find the meaning of each number

Call [mobileState stateDiscription] for a pretty NSString version of the current state. Possible values are Not Moving, Slow Moving, Fast Moving, and unknown.

- (NSString *)stateDescription;


The ALResponse object is a wrapper for the return values for all requests to the Alohar service.

Request Types:

NSDate *timeStamp The date that this request was returned

NSMutableArray *objects *The returned values from the request. Even if there is only one result, unless it is NIL otherwise it will always be wrapped in an NSMutableArray.

ALRequestType requestType *The type of request this response is from. See Request Types above for the available options.

Copyright 2011-2012 Alohar Mobile Inc. All rights reserved.

curl -X POST -d "name=Alohar SDK" --data-urlencode > documentation.html && open documentation.html