CGPlacesSearch.h


Builder to invoke the Places Search

Discussion

A builder for invoking the CityGrid Places Search API as documented at http://docs.citygridmedia.com/display/citygridv2/Places+API



Groups

Initialization

Group members:

-placesSearchWithPublisher:placement:
-Returns

 

NSObject

Group members:

-isEqualToPlacesSearch:

 

Actions

Group members:

-search:

 

Properties

Group members:

property chain

Restricts search to listings with the given chain id.

property first

Restricts search to entities whose name begins with the given character, or if "#", then to entities beginning with any digit.

property histograms

An optional property for providing information on how many listings are in given groups and categories.

property impressionId

An optional property for grouping API calls for tracking purposes.

property latlon

Latitude and longitude of the center of a circle for a geographic search.

property latlon2

Second latitude and longitude used when performing a manual box search.

property offers

Whether to return only listings that have offers associated with them.

property page

The page number of the result set to display.

property placement

An optional property for storing additional information you would like CityGrid Media to log for this view.

property publisher

The publisher code that identifies you. This is required.

property radius

Radius of a circle search.

property resultsPerPage

The number of results to be displayed/returned in a page.

property sort

Sort criterion for the results.

property tag

Restricts search to listings with the given tag id.

property timeout

The network timeout used when performing a search.

property type

Restricts results to listings of the given type.

property what

Search term text.

property where

The geographic location


Functions

property chain

Restricts search to listings with the given chain id.

property first

Restricts search to entities whose name begins with the given character, or if "#", then to entities beginning with any digit.

property histograms

An optional property for providing information on how many listings are in given groups and categories.

property impressionId

An optional property for grouping API calls for tracking purposes.

property latlon

Latitude and longitude of the center of a circle for a geographic search.

property latlon2

Second latitude and longitude used when performing a manual box search.

property offers

Whether to return only listings that have offers associated with them.

property page

The page number of the result set to display.

property placement

An optional property for storing additional information you would like CityGrid Media to log for this view.

property publisher

The publisher code that identifies you. This is required.

property radius

Radius of a circle search.

property resultsPerPage

The number of results to be displayed/returned in a page.

property sort

Sort criterion for the results.

property tag

Restricts search to listings with the given tag id.

property timeout

The network timeout used when performing a search.

property type

Restricts results to listings of the given type.

property what

Search term text.

property where

The geographic location


property chain


Restricts search to listings with the given chain id.

@property (
    nonatomic,
    assign) NSInteger chain;  
Discussion

Chain ids are internal CityGrid identifiers and subject to change. This parameter should only be used in queries that are obtained as "chain expansion urls" from previous searches.


property first


Restricts search to entities whose name begins with the given character, or if "#", then to entities beginning with any digit.

@property (
    nonatomic,
    retain) NSString* first;  


property histograms


An optional property for providing information on how many listings are in given groups and categories.

@property (
    nonatomic,
    assign) BOOL histograms;  
Discussion

Turning on histograms can affect performance.


property impressionId


An optional property for grouping API calls for tracking purposes.

@property (
    nonatomic,
    retain) NSString* impressionId;  
Discussion

The value should be set when making subsequent calls that are related to a previously made call. The user should never supply their own generated value for the impression_id.


property latlon


Latitude and longitude of the center of a circle for a geographic search.

@property (
    nonatomic,
    retain) CLLocation* latlon;  


property latlon2


Second latitude and longitude used when performing a manual box search.

@property (
    nonatomic,
    retain) CLLocation* latlon2;  


property offers


Whether to return only listings that have offers associated with them.

@property (
    nonatomic,
    assign) BOOL offers;  


property page


The page number of the result set to display.

@property (
    nonatomic,
    assign) NSInteger page;  


property placement


An optional property for storing additional information you would like CityGrid Media to log for this view.

@property (
    nonatomic,
    retain) NSString* placement;  
Discussion

An example: if you run a search engine marketing campaign for, say, Google and Yahoo!, you can set the placement property to "sem_google" or "sem_yahoo". Alternatively, if you publish CityGrid listings in different locations in your own site, you can set the placement property to values such as "home_page" or "search" (all up to you). CityGrid will organize reports for you by placement


property publisher


The publisher code that identifies you. This is required.

@property (
    nonatomic,
    retain) NSString* publisher;  


property radius


Radius of a circle search.

@property (
    nonatomic,
    assign) Float32 radius;  
Discussion

If larger than 50 it defaults to 50.


property resultsPerPage


The number of results to be displayed/returned in a page.

@property (
    nonatomic,
    assign) NSInteger resultsPerPage;  


property sort


Sort criterion for the results.

@property (
    nonatomic,
    assign) CGPlacesSearchSort sort;  
Discussion

Use alpha to sort results alphabetically, and dist to sort by increasing distance from the center of the search region. The dist request is only valid for address-based and circle searches. If this parameter is omitted, the results will be ranked by relevance for keyword searches and distance for latitude and longitude


property tag


Restricts search to listings with the given tag id.

@property (
    nonatomic,
    assign) NSInteger tag;  
Discussion

Tag ids are internal CityGrid identifiers and subject to change. This parameter should only be used in queries that are obtained as "refinement urls" from previous searches.


property timeout


The network timeout used when performing a search.

@property (
    nonatomic,
    assign) NSTimeInterval timeout;  


property type


Restricts results to listings of the given type.

@property (
    nonatomic,
    assign) CGPlacesSearchType type;  


property what


Search term text.

@property (
    nonatomic,
    retain) NSString* what;  


property where


The geographic location

@property (
    nonatomic,
    retain) NSString* where;  
Discussion

Address-based search is performed when this parameter starts with a number and contains non-numeric characters; it is much slower than searching a named region

Methods

-init:
-isEqualToPlacesSearch:
-placesSearch
-placesSearchWithPlacement:
-placesSearchWithPublisher:
-placesSearchWithPublisher:placement:
-Returns
-Returns
-Returns
-search:

init:


- (id) init:(NSString*) publisher;  
Discussion

Create a places search with the publisher. Although, this is available to use it's recommended to use one of the following:

  1. +[CityGrid placesSearch]
  2. -[CGPlacesSearch placesSearch]
  3. -[CGPlacesSearch placesSearchWithPublisher:]


isEqualToPlacesSearch:


- (BOOL) isEqualToPlacesSearch:(CGPlacesSearch*) other;  
Return Value

YES if equivalent

Discussion

Compares this builder to another. This is faster than -[CityGrid isEqual:]


placesSearch


+ (id) placesSearch;  
Return Value

An autoreleased places search builder.

Discussion

Returns a search builder that is initialized to the global +[CityGrid publisher] and +[CityGrid timeout] values.


placesSearchWithPlacement:


+ (id) placesSearchWithPlacement:(NSString*) placement;  
Return Value

An autoreleased places search builder

Discussion

a search builder that is initialized to the global +[CityGrid timeout] values.


placesSearchWithPublisher:


+ (id) placesSearchWithPublisher:(NSString*) publisher;  
Return Value

An autoreleased places search builder

Discussion

a search builder that is initialized to the global +[CityGrid timeout] values.


placesSearchWithPublisher:placement:


+ (id) placesSearchWithPublisher:(NSString*) publisher 
        placement:(NSString*) placement;  
Return Value

An autoreleased places search builder

Discussion

a search builder that is initialized to the global +[CityGrid timeout] values.


Returns


+ (id) placesSearchWithPublisher:(NSString*) publisher;  
Return Value

An autoreleased places search builder

Discussion

a search builder that is initialized to the global +[CityGrid timeout] values.


Returns


+ (id) placesSearchWithPlacement:(NSString*) placement;  
Return Value

An autoreleased places search builder

Discussion

a search builder that is initialized to the global +[CityGrid timeout] values.


Returns


+ (id) placesSearchWithPublisher:(NSString*) publisher 
        placement:(NSString*) placement;  
Return Value

An autoreleased places search builder

Discussion

a search builder that is initialized to the global +[CityGrid timeout] values.


search:


- (CGPlacesSearchResults*) search:(NSArray**) errors;  
Parameters
errors

An output array of any errors that occurred

Return Value

The autoreleased search results or nil if an error occurred.

Discussion

Performs a where search as documented by http://docs.citygridmedia.com/display/citygridv2/Places+API#PlacesAPI-SearchUsingWhere

Last Updated: Wednesday, January 18, 2012