The SimpleGeo Objective-C client interface.
Objective-C C
Pull request Compare This branch is 6 commits ahead of rkabir:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
Classes
Resources
SGClient.xcodeproj
Tests
.gitignore
LICENSE
README
build_dist

README

PLEASE NOTE: This has been (mostly) replaced by SimpleGeo.framework
(https://github.com/simplegeo/SimpleGeo.framework). It is not a one for one
replacement; SGClient includes a number of utility classes and methods when
doing iOS development. We intend to extract these over tiem.

SGClient v0.4.1

================================================================================
ABSTRACT:

Interfaces with the SimpleGeo API.

================================================================================
DISCUSSION:

Along with an Objective-C client, this library also provides a nice couple of
features that might be useful to the common iPhone developer.

The SGLocationManager is a wrapper class around the CLLocationManager class
that allows callback notifications for region entry and exit. SimpleGeo offers
a service called PushPin which can return a set of polygons for a given
coordinate. Using the SGLocationManager class will give developers the
ability to be notified when a user exists or enters a new region.

With the release of the iPhone OS 4.0, applications can now gather and update
end-user records while running in the background. The SGLocationService class
offers the ability to register records that can be tracked in the background.
What happens is that everytime the location is updated, the tracked records
will be updated automatically. Updates can also be cached when the application
is moved back into the foreground. See BACKGOUND_LOCATION.markdown for
further instruction.

Note: Running the SGClientTests target will create hundreds of requests that will
be attributed to your account with SimpleGeo. You shouldn't have a need to run 
them.

================================================================================
USAGE:

1. Run ./build_dist
2. Add /path/to/SGClient-v*.*.*/Headers to the "Header Search Paths" setting.
3. Add /path/to/SGClient-v*.*.*/$(PLATFORM_NAME) to "Library Search Paths" setting.
3. Add the following frameworks: CoreLocation, Foundation
4. Goto your target's info and add "-all_load -ObjC -l SGClient" to the "Other Linker Flags" setting under the Build tag. This will
inform the linker to load the categories from the static library.

Once the files have been imported into the Xcode project, initialize a shared
instance of SGLocationService and add the proper OAuth credentials.

SGLocationService* locationService = [SGLocationService sharedLocationService];
SGOAuth* oAuth = [[SGOAuth alloc] initWithKey:@"my_key" secret:@"my_secret"];
locationSErvice.HTTPAuthorizer = oAuth;

The next step will be to register an object as a delegate with the SGLocationService.
The delegate will receive callback notificaitions whenever a HTTP request returns
from http://api.simplegeo.com.

[locationService addDelegate:self]

* * *

- (void) locationService:(SGLocationService*)service succeededForResponseId:(NSString*)requestId responseObject:(NSObject*)responseObject
{
    NSLog(@"Got me a response back from SimpleGeo!");

    // Do something with the responseObject.
    NSDictionary* featureCollection = (NSDictionary*)responseObject;
    for(NSDictionary* feature in featureCollection)
        NSLog([feature description]);
}

Once we have implemeneted the deleagte methods defined by SGLocationServiceDelegate, we can
start to fire off requests.

// Fire off a nearby query for a layer
SGLatLonNearbyQuery* query = [[SGLatLonNearbyQuery alloc] initWithLayer:@"my_layer"];
CLLocationCoordinate coordinate = {40.1235, -105.213}
query.coordinate = coordinate;
query.radius = 10.0;

[locationService nearby:query];


In this instance, invoking the nearby: method will spawn an async request to http://api.simplegeo.com/0.1/nearby/my_layer/40.1235,-105.213.json.
The results of the query will be returned in the responseObject parameter of the locationService:succeededForResponseId:resposneObject:
delegate method.

For an example application, checkout http://github.com/simplegeo/SGDemoApp.

================================================================================
BUILD REQUIREMENTS:

iPhone SDK 3.1

Frameworks
- MapKit
- CoreLocation
- Foundation
- UIKit

================================================================================
PACKAGING LIST:

Documentation
All the HTML files generated by HeaderDoc.

	SGClient.html
	The table of contents for the entire documentation structure.

libSGClient.a
The static library built for the iPhone Device.
	
libSGClient-sim.a
The static library built for the iPhone Simulator.

Headers

    SGClient.h
    Defines all the header values used in the SGClient.
				
	SGAuthorization.h
	Defines a protocol that wraps an HTTP request sent by SGLocationService
	with the proper authentication protocol.
			
	SGGeoJSONEncoder.h
	Defines a GeoJSON coder/decoder.
	
	SGLayer.h
	Defines an object that can update and retrieve SGRecordAnnotations within
	a given layer.
		
	SGLocationService.h
	Defines the ObjC interface for interacting with the SimpleGeo API.
	
	SGLocationTypes.h
	Defines structures that are used by SGLocationService.
		
	SGOAuth.h
	Defines a two-legged, OAuth wrapper class used by SGLocationService.
		
	SGRecord.h
	Defines a class that represents a SimpleGeo record.
	
	SGRecordAnnotation.h
	Defines a protocol that represents a SimpleGeo record.
	    
    GeoJSON+NSDictionary.h
    A category to help access GeoJSON keys.
    
    GeoJSON+NSArray.h
    A category to help access GeoJSON keys.
    
    SGGeoJSON+NSDictionary
    A category to help access the SimpleGeo specific
    keys of a GeoJSON object.
    
    CLLocationAdditions.h
    A category for the CLLocation class.
    
    NSArrayAdditions.h
    A category for the NSArray class.
    
    NSStringAdditions.h
    A category for the NSString class
    
    SGAddititons.h
    All categories used by the client.
    
    SGCacheHandler
    Handles manipulations of cached files.
    
    SGCommitLog.h
    An attempt at creating a commit log that can be used
    to replay committed data.
    
    SGLocationManager.h
    A wrapper around the CLLocationManager that provides
    notifications for region exit and entry.
    
    SGQuery.h
    A query object the encompasses holds onto information 
    such as response cursor id for pagination and the most
    recent request Iid.
    
    SGNearbyQuery.h
    A subclass of SGQuery that defines the information required
    to send a nearby request to SimpleGeo.
    
    SGGeohashNearbyQuery.h
    A subclas of SGNearbyQuery that uses a geohash in order to 
    accomplish the nearby query.
    
    SGLatLonNearbyQuery.h
    A subclass of SGLatLonNearbyQuery that uses a lat/lon coordinate
    in order to accomplish the nearby query.
    
    SGHistoryQuery.h
    A subclass of SGQuery that defines information required to 
    send a nearby history request to SimpleGeo.
    
    SGPointHelper.h
    Helps convert lists of CLLocation2DCoordinates to GeoJSON
    point geometries and vice-versa.
    
    SGGeoJSON.h
    Helps initialize simple GeoJSON objects (e.g. geometry
    collection).

================================================================================
CHANGES FROM PREVIOUS VERSIONS:
Version 0.4.1
- Fixed linking issues that were present in the Release configuration

Version 0.4.0
- SGRecordAnnotations can now be updated in the background and tracked
in the foreground
- A wrapper around CLLocationManager provides the delegate with notifications
of when the device enters and leaves a region defined by SimpleGeo's PushPin
service

Version 0.3.9
- SGLayer objects can use pagination automatically

Version 0.3.8
- Added pagination to both the nearby and history endpoints

Version 0.3.7
- Fixed a bug where the type of a record wasn't being properly stored, in some
cases

Version 0.3.6
- Added access to the new PushPin endpoints: contains, overlaps and boundary

Version 0.3.5
- Changed the nearby methods to use the single layer endpoint instead of the
multi-layer endpoint.

Version 0.3.4
- Added the SpotRank endpoint

Version 0.3.3
- Nearby requests can now use the temporal indexes

Version 0.3.2
- Added license

Version 0.3.1
- Restructured project.

Version 0.3.0
- Upgraded SGLocationService to use version 0.1 of the SimpleGeo API
- Models have been updated to reflect the new GeoJSON format returned
from SimpleGeo queries
- Added a new NSDictionary and NSArray category to help access key specific
to GeoJSON format
- Replaced updateRecordWithGeoJSONDictionary: with updateRecordWithGeoJSONObject:
- Removed userDefinedProperties from SGRecordAnnotation and replaced it with
properties
- Reworked the SGGeoJSONEncoder

Version 0.2.3
- Updated the default container images.
- Updated SGRadar to present target images that are on the border of
the radar. 
- Update SGLayerMapView to load more records based on a time interval.
- Added media as a filter type.

Version 0.2.1
- Allow filtering by types in nearby requests.

Version 0.2.0
- Added reverse geocoding.
- Implemented the new SimpleGeo endpoints that allow multiple records to be
added and retrieved.

Version 0.1.9
- SGLayer objects will now update records as they are recieved from the SGLocaitonService.
- SGRecord defines a new property that stores user defined properties.
- SGOAuth objects can be restored from a save point.
- Nearby searchs can be done using a Geohash or a lat/lon coordinate paired with a radius.

Version 0.1.8
- First version.

================================================================================
Copyright (C) 2010 SimpleGeo Inc. All rights reserved.