com.citygrid.content.places.search
Class CGPlacesSearch

java.lang.Object
  extended by com.citygrid.content.places.search.CGPlacesSearch
All Implemented Interfaces:
Serializable, Cloneable

public class CGPlacesSearch
extends Object
implements Serializable, Cloneable

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

The most popular use case for CityGrid is to be able to perform a places search to show results for places around a lat/lon or zip code, show a detail as a result of any user interaction, and call the tracker on each interaction to earn money.

Let's pretend the user chose to find Movie Theater's in 90045 through your application. This would typically be ready from your UI or model.

// Pretends the user chose to find Movie Theater's in 90045 within the application
    // and this is read from your UI or model
    CGPlacesSearch search = CityGrid.placesSearch();
    search.setType(CGPlacesSearchType.MovieTheater);
    search.setWhere("90045");
    search.setHistograms(true);

    CGPlacesSearchResults results = search(search);

    for (CGPlacesSearchLocation location : results.getLocations()) {
        // do something with the location...
    }

Next, pretend the user selected a location and wanted to view the profile as a result. The selected location might have come from any one from the list of locations, but for the purpose of an example this will chose the first location.

// Pretend the user selected the first location result and wants to display the full location data
    // Usually this is a navigation to a detail view.
    CGPlacesSearchLocation searchLocation = results.getLocations()[0];

    // Get the detail (This will populate the locationId and impressionId for you)
    // You could alternatively use the locationId and impressionId yourself, but this is easier
    CGPlacesDetailLocation detailLocation = searchLocation.placesDetailLocation();
    // do something with the location detail.

The location is displayed, but we also have to track that the location was displayed. Also, if the user clicks on or navigates on any content be sure to track that as well.

try {
        detailLocation.track(
                MY_MUID,
                MY_MOBILE_TYPE,
                CGAdsTrackerActionTarget.ClickToCall);
    }
    catch (CGException e) {
        e.printStackTrace();
    }

See Also:
Serialized Form

Field Summary
private static String CGPlacesSearchLatLonUri
           
private static String CGPlacesSearchWhereUri
           
private  int chain
          Restricts search to listings with the given chain id.
private  int connectTimeout
          The network connect connectTimeout used when performing a search.
private  String first
          Restricts search to entities whose name begins with the given character, or if "#", then to entities beginning with any digit.
private  boolean histograms
          An optional property for providing information on how many listings are in given groups and categories.
private  String impressionId
          An optional property for grouping API calls for tracking purposes.
private  CGLatLon latlon
          Latitude and longitude of the center of a circle for a geographic search.
private  CGLatLon latlon2
          Second latitude and longitude used when performing a manual box search.
private  boolean offers
          Whether to return only listings that have offers associated with them.
private  int page
          The page number of the result set to display.
private  String placement
          An optional property for storing additional information you would like CityGrid Media to log for this view.
private  String publisher
          The publisher code that identifies you.
private  float radius
          Radius of a circle search.
private  int readTimeout
          The network read connectTimeout used when performing a search.
private  int resultsPerPage
          The number of results to be displayed/returned in a page.
private  CGPlacesSearchSort sort
          Sort criterion for the results.
private  int tag
          Restricts search to listings with the given tag id.
private  CGPlacesSearchType type
          Restricts results to listings of the given type
private  String what
          Search term text
private  String where
          The geographic location

 
Constructor Summary
CGPlacesSearch(String publisher)
          Create a places search with the publisher.
 
Method Summary
private  Map<String,Object> build()
           
 Object clone()
           
 boolean equals(Object o)
           
 int getChain()
           
 int getConnectTimeout()
           
 String getFirst()
           
 String getImpressionId()
           
 CGLatLon getLatlon()
           
 CGLatLon getLatlon2()
           
 int getPage()
           
 String getPlacement()
           
 String getPublisher()
           
 float getRadius()
           
 int getReadTimeout()
           
 int getResultsPerPage()
           
 CGPlacesSearchSort getSort()
           
 int getTag()
           
 CGPlacesSearchType getType()
           
 String getWhat()
           
 String getWhere()
           
 int hashCode()
           
 boolean isHistograms()
           
 boolean isOffers()
           
static CGPlacesSearch placesSearch()
          Returns a search builder that is initialized to the global publisher ande timeout values.
static CGPlacesSearch placesSearchWithPlacement(String placement)
          Returns a search builder that is initialized to the global connectTimeout values.
static CGPlacesSearch placesSearchWithPublisher(String publisher)
          Returns a search builder that is initialized to the global connectTimeout values.
static CGPlacesSearch placesSearchWithPublisherAndPlacement(String publisher, String placement)
          Returns a search builder that is initialized to the global connectTimeout values.
private  String[] processCategories(org.codehaus.jackson.JsonNode node)
           
private  CGPlacesSearchLocation[] processLocations(org.codehaus.jackson.JsonNode locationsNode)
           
(package private)  CGPlacesSearchResults processResults(org.codehaus.jackson.JsonNode rootNode)
           
 CGPlacesSearchResults search()
          Performs a where search as documented by http://docs.citygridmedia.com/display/citygridv2/Places+API#PlacesAPI-SearchUsingWhere
 void setChain(int chain)
           
 void setConnectTimeout(int connectTimeout)
           
 void setFirst(String first)
           
 void setHistograms(boolean histograms)
           
 void setImpressionId(String impressionId)
           
 void setLatlon(CGLatLon latlon)
           
 void setLatlon2(CGLatLon latlon2)
           
 void setOffers(boolean offers)
           
 void setPage(int page)
           
 void setPlacement(String placement)
           
 void setPublisher(String publisher)
           
 void setRadius(float radius)
           
 void setReadTimeout(int readTimeout)
           
 void setResultsPerPage(int resultsPerPage)
           
 void setSort(CGPlacesSearchSort sort)
           
 void setTag(int tag)
           
 void setType(CGPlacesSearchType type)
           
 void setWhat(String what)
           
 void setWhere(String where)
           
 String toString()
           
private  List<CGError> validate()
           
 
Methods inherited from class java.lang.Object
finalize, getClass, notify, notifyAll, wait, wait, wait
 

Field Detail

CGPlacesSearchWhereUri

private static final String CGPlacesSearchWhereUri
See Also:
Constant Field Values

CGPlacesSearchLatLonUri

private static final String CGPlacesSearchLatLonUri
See Also:
Constant Field Values

publisher

private String publisher
The publisher code that identifies you. This is required.


type

private CGPlacesSearchType type
Restricts results to listings of the given type


what

private String what
Search term text


tag

private int tag
Restricts search to listings with the given tag id.

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.


chain

private int chain
Restricts search to listings with the given chain id.

@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.


first

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


where

private String where
The geographic location

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


radius

private float radius
Radius of a circle search. If larger than 50 it defaults to 50.


page

private int page
The page number of the result set to display.


resultsPerPage

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


sort

private CGPlacesSearchSort sort
Sort criterion for the results.

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


placement

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

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


offers

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


histograms

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

Turning on histograms can affect performance.


latlon

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


latlon2

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


connectTimeout

private int connectTimeout
The network connect connectTimeout used when performing a search. In milliseconds.


readTimeout

private int readTimeout
The network read connectTimeout used when performing a search. In milliseconds.


impressionId

private String impressionId
An optional property for grouping API calls for tracking purposes.

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.

Constructor Detail

CGPlacesSearch

public CGPlacesSearch(String publisher)
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()

Method Detail

getPublisher

public String getPublisher()

setPublisher

public void setPublisher(String publisher)

getType

public CGPlacesSearchType getType()

setType

public void setType(CGPlacesSearchType type)

getWhat

public String getWhat()

setWhat

public void setWhat(String what)

getTag

public int getTag()

setTag

public void setTag(int tag)

getChain

public int getChain()

setChain

public void setChain(int chain)

getFirst

public String getFirst()

setFirst

public void setFirst(String first)

getWhere

public String getWhere()

setWhere

public void setWhere(String where)

getRadius

public float getRadius()

setRadius

public void setRadius(float radius)

getPage

public int getPage()

setPage

public void setPage(int page)

getResultsPerPage

public int getResultsPerPage()

setResultsPerPage

public void setResultsPerPage(int resultsPerPage)

getSort

public CGPlacesSearchSort getSort()

setSort

public void setSort(CGPlacesSearchSort sort)

getPlacement

public String getPlacement()

setPlacement

public void setPlacement(String placement)

isOffers

public boolean isOffers()

setOffers

public void setOffers(boolean offers)

isHistograms

public boolean isHistograms()

setHistograms

public void setHistograms(boolean histograms)

getLatlon

public CGLatLon getLatlon()

setLatlon

public void setLatlon(CGLatLon latlon)

getLatlon2

public CGLatLon getLatlon2()

setLatlon2

public void setLatlon2(CGLatLon latlon2)

getConnectTimeout

public int getConnectTimeout()

setConnectTimeout

public void setConnectTimeout(int connectTimeout)

getReadTimeout

public int getReadTimeout()

setReadTimeout

public void setReadTimeout(int readTimeout)

getImpressionId

public String getImpressionId()

setImpressionId

public void setImpressionId(String impressionId)

placesSearch

public static CGPlacesSearch placesSearch()
Returns a search builder that is initialized to the global publisher ande timeout values.

Returns:
A places search builder.

placesSearchWithPublisher

public static CGPlacesSearch placesSearchWithPublisher(String publisher)
Returns a search builder that is initialized to the global connectTimeout values.

Parameters:
publisher -
Returns:
A places search builder

placesSearchWithPlacement

public static CGPlacesSearch placesSearchWithPlacement(String placement)
Returns a search builder that is initialized to the global connectTimeout values.

Parameters:
placement -
Returns:
A places search builder

placesSearchWithPublisherAndPlacement

public static CGPlacesSearch placesSearchWithPublisherAndPlacement(String publisher,
                                                                   String placement)
Returns a search builder that is initialized to the global connectTimeout values.

Parameters:
publisher -
placement -
Returns:
A places search builder

validate

private List<CGError> validate()

search

public CGPlacesSearchResults search()
                             throws CGException
Performs a where search as documented by http://docs.citygridmedia.com/display/citygridv2/Places+API#PlacesAPI-SearchUsingWhere

Returns:
Places search result.
Throws:
CGException

build

private Map<String,Object> build()

processResults

CGPlacesSearchResults processResults(org.codehaus.jackson.JsonNode rootNode)

processLocations

private CGPlacesSearchLocation[] processLocations(org.codehaus.jackson.JsonNode locationsNode)

processCategories

private String[] processCategories(org.codehaus.jackson.JsonNode node)

equals

public boolean equals(Object o)
Overrides:
equals in class Object

hashCode

public int hashCode()
Overrides:
hashCode in class Object

toString

public String toString()
Overrides:
toString in class Object

clone

public Object clone()
             throws CloneNotSupportedException
Overrides:
clone in class Object
Throws:
CloneNotSupportedException


Copyright © 2011. All Rights Reserved.