SGLocationService


Update and retrieve records from SimpleGeo.

Superclass: NSObject
Declared In: SGLocationService.h

Discussion

All methods that create an HTTP request return a response identifier. The response identifier is used to identify which response is being returned when either locationService:succeededForResponseId:responseObject: or locationService:failedForResponseId:error: is called for all delegates. The class allows multiple records to be registered using addDelegate: . Delegates will continue recieving notifications so it is important to removeDelegate: when that object no longer wants to recieve notifications.

The location service requires that HTTPAuthorizer be set with a valid instance of SGOAuth . Since the only type of authorization supported by SimpleGeo is OAuth, this property must be set or all HTTP requests will result in an error.

All HTTP requests are sent as NSInvocationOperations. Currently, the SimpleGeo API only offers get/add/delete methods for only a single record. When using a method like updateRecordAnnotations: , a single NSInvocationOperation is used to update all of the records. It does not create a new operation for each SGRecordAnnotation that is passed through.

This interface provides two different avenues when it comes to storing and retrieving records. The first is using the standard NSString parameratized methods like retrieveRecord:layer: . Calling this method only requires the knowledge of the desired recordId and the layer to which it belongs to. The alternative method would be to use retrieveRecordAnnotation: which requires an NSObject that implements SGRecordAnnotation . SGRecord is provided as a standard class that implements the protocol. The advantage to using the second method is that everytime a response succeeds, the delegate can use the responseObject that is passed in via locationService:succeededForResponseId:responseObject: to update the SGRecord by calling updateRecordWithGeoJSONObject:.



Methods

-addDelegate:

Adds an instance of SGLocationServiceDelegate to be notified when a HTTP request fails or succeeds.

+callbackOnMainThread:

Determines whether or not to use the main thread to call delegate methods. Default is YES.

-deleteRecord:layer:
-deleteRecordAnnotation:

Deletes a SGAnnotationRecord from SimpleGeo.

-deleteRecordAnnotations:

Deletes an array of SGAnnotationRecord from SimpleGeo.

-densityForCoordinate:day:

Returns a GeoJSON FeatureCollection that contains SpotRank data for a specific point.

-densityForCoordinate:day:hour:

Returns a GeoJSON Feature that contains SpotRank data for a specific point.

-densityForCoordinate:day:hour:

Returns a GeoJSON FeatureCollection that contains SpotRank data for a specific point.

-layerInformation:

Retrieves information for a given layer.

-removeDelegate:

Removes the SGLocationServiceDelegate from the group of delegates.

-retrieveHistory:layer:
-retrieveRecord:layer:

Retrieves information about a record within a layer.

-retrieveRecordAnnotation:

Retrieves information about a SGRecordAnnotation from SimpleGeo.

-retrieveRecordAnnotationHistory:
-retrieveRecordAnnotations:

Retreives information about an array of SGRecordAnnotation from Simplegeo.

-retrieveRecordHistory:layer:
-retrieveRecordsForCoordinate:radius:layer:types:limit:

Get records that are located within a radius of coordinate.

-retrieveRecordsForCoordinate:radius:layer:types:limit:

Get records that are located within a radius of a coordinate and within a given interval. To make use of our time based index, the difference between start and end must not be greater than 60 minutes.

-retrieveRecordsForCoordinate:radius:layer:types:limit:start:end:

Get records that are located within a radius of a coordinate and within a given interval. To make use of our time based index, the difference between start and end must not be greater than 60 minutes.

-retrieveRecordsForGeohash:layer:type:limit:

Gets records that are located in a specific geohash and within a given interval. To make use of our time based index, the difference between start and end must not be greater than 60 minutes.

-retrieveRecordsForGeohash:layer:types:limit:

Gets records that are located in a specific geohash.

-retrieveRecordsForGeohash:layer:types:limit:start:end:

Gets records that are located in a specific geohash and within a given interval. To make use of our time based index, the difference between start and end must not be greater than 60 minutes.

-reverseGeocode:

Returns resource information for a given pair lat/lon coordinate.

+sharedLocationService

The shared instance of SGLocationService .

-updateRecord:layer:coord:properties:

Updates a record with the given properties.

-updateRecord:layer:properties:

Updates a record with the given properties.

-updateRecordAnnotation:

Updates a record a SGRecordAnnotation in SimpleGeo.

-updateRecordAnnotations:

Updates an array of SGRecordAnnotations in SimpleGeo.


addDelegate:


Adds an instance of SGLocationServiceDelegate to be notified when a HTTP request fails or succeeds.

- (void) addDelegate:(id<SGLocationServiceDelegate>)delegate; 
Parameters
delegate

The delegate to add.


callbackOnMainThread:


Determines whether or not to use the main thread to call delegate methods. Default is YES.

+ (void) callbackOnMainThread:(BOOL)callback; 
Parameters
callback

YES to have the delegate methods be called on the main thread; otherwise NO.

Discussion

Since NSOpertaionQueue spawns new threads in order to fulfill its purpose, there are instances where it might be benefical to extend the life of that thread (e.g. loading objects into CoreData).

There are only two delegate methods defined by SGLocationServiceDelegate. If you plan on updating any UIViews, Apple recomends to us the main thread. So be careful. If you plan on updating a UITableView within your implementation of the delegate methods, be sure that this value is set to YES.


deleteRecord:layer:


- (NSString*) deleteRecord:(NSString*)recordId layer:(NSString*)layer; 
Parameters
recordId

The id of the record to delete.

layer

The layer in which the record is located.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

@abstractDeletes a single record from SimpleGeo. @discussionUse this method to delete a record from SimpleGeo.


deleteRecordAnnotation:


Deletes a SGAnnotationRecord from SimpleGeo.

- (NSString*) deleteRecordAnnotation:(id<SGRecordAnnotation>)record; 
Parameters
record

The record to delete.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

See deleteRecord:layer:


deleteRecordAnnotations:


Deletes an array of SGAnnotationRecord from SimpleGeo.

- (NSString*) deleteRecordAnnotations:(NSArray*)records; 
Parameters
records

The records to delete.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

See deleteRecord:layer:


densityForCoordinate:day:


Returns a GeoJSON FeatureCollection that contains SpotRank data for a specific point.

See Also:

densityForCoordinate:day:hour:

- (NSString*) densityForCoordinate:(CLLocationCoordinate2D)coord 
        day:(NSString*)day; 
Parameters
coord

The desired location.

day

See the defined SpotRank days in SGLocationTypes . (e.g. @"mon"). Default is nil.s

Discussion

See SpotRank for information about the data set. The data returned is a collection of tiles, bounding boxes with density data.


densityForCoordinate:day:hour:


Returns a GeoJSON Feature that contains SpotRank data for a specific point.

- (NSString*) densityForCoordinate:(CLLocationCoordinate2D)coord 
        day:(NSString*)day hour:(int)hour; 
Parameters
coord

The desired location.

day

See the defined SpotRank days in SGLocationTypes . (e.g. @"mon"). Default is nil.s

hour

An integer value between 0 and 24. The timezone depends on the location of the coord. Deafault is 12.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

See SpotRank for information about the data set. If hour is not specified, then a collection of of tiles, bounding boxes with density data, will be returned for the entire day.


densityForCoordinate:day:hour:


Returns a GeoJSON FeatureCollection that contains SpotRank data for a specific point.

See Also:

densityForCoordinate:day:

- (NSString*) densityForCoordinate:(CLLocationCoordinate2D)coord 
        day:(NSString*)day; 
Parameters
coord

The desired location.

day

See the defined SpotRank days in SGLocationTypes . (e.g. @"mon"). Default is nil.s

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

See SpotRank for information about the data set. The data returned is a collection of tiles, bounding boxes with density data.


layerInformation:


Retrieves information for a given layer.

- (NSString*) layerInformation:(NSString*)layerName; 
Parameters
layerName

The layer.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.


removeDelegate:


Removes the SGLocationServiceDelegate from the group of delegates.

- (void) removeDelegate:(id<SGLocationServiceDelegate>)delegate; 
Parameters
delegate

The delegate to remove.


retrieveHistory:layer:


See Also:

retrieveRecordHistory:layer:

- (NSString*) retrieveRecordHistory:(NSString*)recordId 
        layer:(NSString*)layer; 
Parameters
recordIdThe

id of the record that wants to know about its history.

layer

The layer in which the record is located in.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

This method allows retrieve the history of a record.


retrieveRecord:layer:


Retrieves information about a record within a layer.

- (NSString*) retrieveRecord:(NSString*)recordId layer:(NSString*)layer; 
Parameters
recordId

The id of the record.

layer

The layer in which the record is located in.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

Use this method to retrieve information about a single record that is already stored in SimpleGeo.


retrieveRecordAnnotation:


Retrieves information about a SGRecordAnnotation from SimpleGeo.

- (NSString*) retrieveRecordAnnotation:(id<SGRecordAnnotation>)record; 
Parameters
record

The record.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

See retrieveRecord:layer:


retrieveRecordAnnotationHistory:


- (NSString*) retrieveRecordAnnotationHistory:(id<SGRecordAnnotation>)record; 
Parameters
record

The record

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

@abstractRetrieve the record history of a //simplegeo/ooc/intf/SGAnnotationRecord SGAnnotationRecord . @discussionSee retrieveHistory:layer:


retrieveRecordAnnotations:


Retreives information about an array of SGRecordAnnotation from Simplegeo.

- (NSString*) retrieveRecordAnnotations:(NSArray*)records; 
Parameters
records

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

See retrieveRecord:layer:


retrieveRecordHistory:layer:


See Also:

retrieveHistory:layer:

- (NSString*) retrieveRecordHistory:(NSString*)recordId 
        layer:(NSString*)layer; 
Parameters
recordIdThe

id of the record that wants to know about its history.

layer

The layer in which the record is located in.

Discussion

This method allows retrieve the history of a record.


retrieveRecordsForCoordinate:radius:layer:types:limit:


Get records that are located within a radius of coordinate.

- (NSString*) retrieveRecordsForCoordinate:(CLLocationCoordinate2D)coord radius:(double)radius layer:(NSString*)layer types:(NSArray*)types limit:(NSInteger)limit; 
Parameters
coord

The origin of the radius.

radius

The radius of the search space. (km)

layer

The layer to search in.

types

An array of types that will help filter the search.

limitThe

amount of records to obtain.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.


retrieveRecordsForCoordinate:radius:layer:types:limit:


Get records that are located within a radius of a coordinate and within a given interval. To make use of our time based index, the difference between start and end must not be greater than 60 minutes.

See Also:

retrieveRecordsForCoordinate:radius:layer:types:limit:start:end:

- (NSString*) retrieveRecordsForCoordinate:(CLLocationCoordinate2D)coord radius:(double)radius layer:(NSString*)layer types:(NSArray*)types limit:(NSInteger)limit start:(double)start end:(double)end; 
Parameters
coord

The origin of the radius.

radius

The radius of the search space. (km)

layer

The layer to search in.

types

An array of types that will help filter the search.

limitThe

amount of records to obtain.

start

An Epoch timestamp that is the beginning of the time interval in seconds.

end

An Epoch timestamp that is the end of the time interval in seconds.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.


retrieveRecordsForCoordinate:radius:layer:types:limit:start:end:


Get records that are located within a radius of a coordinate and within a given interval. To make use of our time based index, the difference between start and end must not be greater than 60 minutes.

See Also:

retrieveRecordsForCoordinate:radius:layer:types:limit:

- (NSString*) retrieveRecordsForCoordinate:(CLLocationCoordinate2D)coord radius:(double)radius layer:(NSString*)layer types:(NSArray*)types limit:(NSInteger)limit start:(double)start end:(double)end; 
Parameters
coord

The origin of the radius.

radius

The radius of the search space. (km)

layer

The layer to search in.

types

An array of types that will help filter the search.

limitThe

amount of records to obtain.

start

An Epoch timestamp that is the beginning of the time interval in seconds.

end

An Epoch timestamp that is the end of the time interval in seconds.


retrieveRecordsForGeohash:layer:type:limit:


Gets records that are located in a specific geohash and within a given interval. To make use of our time based index, the difference between start and end must not be greater than 60 minutes.

See Also:

retrieveRecordsForGeohash:layer:types:limit:start:end:

- (NSString*) retrieveRecordsForGeohash:(SGGeohash)geohash layer:(NSString*)layer types:(NSArray*)types limit:(NSInteger)limitend start:(double)start end:(double)end; 
Parameters
geohash

The geohash that should be searched.

layer

The layer to search in.

types

An array of types that will help filter the search.

start

An Epoch timestamp that is the beginning of the time interval in seconds.

end

An Epoch timestamp that is the end of the time interval in seconds.

limit

The amount of records to obtain.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.


retrieveRecordsForGeohash:layer:types:limit:


Gets records that are located in a specific geohash.

- (NSString*) retrieveRecordsForGeohash:(SGGeohash)geohash layer:(NSString*)layer types:(NSArray*)types limit:(NSInteger)limit; 
Parameters
geohash

The geohash that should be searched.

layer

The layer to search in.

types

An array of types that will help filter the search.

limit

The amount of records to obtain.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.


retrieveRecordsForGeohash:layer:types:limit:start:end:


Gets records that are located in a specific geohash and within a given interval. To make use of our time based index, the difference between start and end must not be greater than 60 minutes.

See Also:

retrieveRecordsForGeohash:layer:type:limit:

- (NSString*) retrieveRecordsForGeohash:(SGGeohash)geohash layer:(NSString*)layer types:(NSArray*)types limit:(NSInteger)limitend start:(double)start end:(double)end; 
Parameters
geohash

The geohash that should be searched.

layer

The layer to search in.

types

An array of types that will help filter the search.

start

An Epoch timestamp that is the beginning of the time interval in seconds.

end

An Epoch timestamp that is the end of the time interval in seconds.

limit

The amount of records to obtain.


reverseGeocode:


Returns resource information for a given pair lat/lon coordinate.

- (NSString*) reverseGeocode:(CLLocationCoordinate2D)coord; 
Parameters
coord

The coordinate to use for reverse geocoding.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

This method does not use MapKit's reverse geocoding methods. SimpleGeo offers its own reverse geocoding endpoint. The response object is a GeoJSON dictionary where the properties key contains a dictionary with the following keys:

street_number, country, street, postal_code, county_name, county_code, state_code, place_name

Reverse geocoding is only supported within the US; however, other countries will be offered in the coming months.


sharedLocationService


The shared instance of SGLocationService.

+ (SGLocationService*) sharedLocationService; 
Return Value

The shared instance of SGLocationService.


updateRecord:layer:coord:properties:


Updates a record with the given properties.

See Also:

updateRecord:layer:properties:

- (NSString*) updateRecord:(NSString*)recordId layer:(NSString*)layer 
        coord:(CLLocationCoordinate2D)coord properties:(NSDictionary*)properties; 
Parameters
recordId

The id of the record.

layer

The layer in which the record is located in.

properties

The new properties for the record.

Discussion

Use this method to update records in SimpleGeo. If the record id is not found in the layer then a new record will be created.


updateRecord:layer:properties:


Updates a record with the given properties.

See Also:

updateRecord:layer:coord:properties:

- (NSString*) updateRecord:(NSString*)recordId layer:(NSString*)layer 
        coord:(CLLocationCoordinate2D)coord properties:(NSDictionary*)properties; 
Parameters
recordId

The id of the record.

layer

The layer in which the record is located in.

properties

The new properties for the record.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

Use this method to update records in SimpleGeo. If the record id is not found in the layer then a new record will be created.


updateRecordAnnotation:


Updates a record a SGRecordAnnotation in SimpleGeo.

- (NSString*) updateRecordAnnotation:(id<SGRecordAnnotation>)record; 
Parameters
record

The record to update.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

See updateRecord:layer:properites:


updateRecordAnnotations:


Updates an array of SGRecordAnnotations in SimpleGeo.

- (NSString*) updateRecordAnnotations:(NSArray*)records; 
Parameters
records

An array of records.

Return Value

A response id that is used to identifier the return value from SimpleGeo. You can use this value in delegate.

Discussion

See updateRecord:layer:properties:

Properties

HTTPAuthorizer

The type of authorization to apply to all HTTP requests.

operationQueue

The operation queue that is used to send HTTP requests.


HTTPAuthorizer


The type of authorization to apply to all HTTP requests.

@property (
    nonatomic,
    assign) id<SGAuthorization> HTTPAuthorizer; 


operationQueue


The operation queue that is used to send HTTP requests.

@property (
    nonatomic,
    readonly) NSOperationQueue* operationQueue; 

© SimpleGeo Last Updated: 03/31/2010