Places API

Introduction

The CityGrid Places API enables developers to create web and mobile applications that find local businesses, organizations, and points of interest by a variety of search criteria and display content associated with these places. Developers can use search results to position places on a map, perform further refinement or expansion searches, or access full details of a given place. Future versions of the Places API will allow submission of user reviews, photos, and other content.

If you qualify as a CityGrid partner, you can get paid for using the Places API through Places that Pay. Simply use the Places that Pay tracking features to notify CityGrid about impressions and referrals.

The Places API consists of two endpoint categories:

#Places Search — Returns the set of places that match your search criteria. Only basic place information is provided with each search result.
#Places Detail — Returns detailed information and associated content for a single place.

Audience

The Places API is intended for developers of web and mobile applications who want to give their applications the ability to search for and display profiles of local businesses and points of interest.

Version 2 Updates

The following are changes for version 2, updated from version 1

Added support for SSL
New endpoint URLs beginning with http://api.citygridmedia.com/content/places/v2/.
New parameters for search requests:
- histograms
- lat2
- lon2
- has_offers
- i (impression_id)
Changes to the Places Search response:
- Added impression_id.
- If there is no featured, an empty element is still provided in the response.
- If there is no distance, an empty element is still provided in the response.
- If there is no image, an empty element is still provided in the response.
- If there is no fax_number, an empty element is still provided in the response.
- If there is no tagline, an empty element is still provided in the response.
- If there is no website, an empty element is still provided in the response.
- If there is no has_video, an empty element is still provided in the response.
- If there is no has_offers, an empty element is still provided in the response.
- If there is no expansion, an empty element is still provided in the response.
- If there are no spelling suggestions, an empty element/attribute is still provided in the response.
Changes involving geocoding:
- For the XML response, there is now a regions element around a collection of region results.
- If there are no regions, an empty element/attribute is still provided in the response.
Changes involving histograms, if histogramsis set to "true":
- For the XML response, there is now a histograms element around a collection of histogram results.
- For the XML response, there is now an items element around a collection of item results
- If there are no histograms, an empty element/attribute is still provided in the response.
New parameters for detail requests:
- i (impression_id)
- image_count
- image_size_min
- image_size_max
Changes to the Places Details response:
- Added impression_id.
- review_date, editorial_date, and offer_expiration_date are in ISO 8601 format.
- For both JSON and XML responses, reviews has been renamed to review_info.
- For the JSON response, review has been renamed to reviews.
- For the XML response, there is now a reviews element around a collection of review elements.
- Attributes nameid and parentid associated with category are now name_id and parent_id.
- Attribute groupid associated with group is now group_id.
- Attribute attributeid associated with attribute is now attribute_id.
- For the JSON response, markets is now an array of strings.
- For the JSON response, neighborhoods is now an array of strings.
- For the JSON response, bullets is now an array of strings.
- Added Google's Protocol Buffers as format option.
- Added geographies.
Changes to Places details error codes:
- Removal of review_count.out.of.range - If a supplied value is out of range, the default value is used (see Places Detail Request below).
- Removal of format.unacceptable - If a supplied value is not one of the expected values (see Places Detail Request below), the response will be returned in XML.
- Added image.count.illegal
- Added image.count.out.of.range
- Added image.size.range.invalid
- Added image.size.illegal

Lat-Lon search with a radius of 0.25 miles or under no longer requires what, type, tag or chain parameters

Places Search

The Places Search API provides programmatic access to CityGrid's local search engine, delivering basic place details together with metadata allowing subsequent refinement and expansion searches.

There are two endpoints for places search:

Where
Latitude and Longitude

Search Using Where

The where endpoint returns places whose geography is specified with free-form text. The text can consist of a zip code, the name of a neighborhood or city, or a street address.

Where Search HTTPS Endpoint

The following endpoint supports HTTPS GET:

https://api.citygridmedia.com/content/places/v2/search/where

Where Search Request

The following query string parameters are used with the Places API where endpoint:

Parameter	Description	Required	Valid Values	Default	Examples	Notes
type	Restricts search to listings of the given type (category)	See Notes below.	movie movietheater restaurant hotel travel barclub spabeauty shopping		movie hotel restaurant	A full list of types supported is available as a json list and as a json tree. Only one category may be provided.
what	Search term text	See Notes below.			pizza sporting%20goods plumbers
tag	Restricts search to listings with the given tag id	See Notes below.	An integer		1722	Tag ids are internal CityGrid identifiers and subject to change. A full list of types supported is available as a json list and as a json tree. This parameter may be used in queries that are obtained as "refinement urls" from previous searches
chain	Restricts search to listings with the given chain id.	See Notes below.	An integer		360861766 41859967	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	Restricts search to entities whose name begins with the given character, or if "#", then to entities beginning with any digit	No	A character		s c
where	The geographic location	Yes	A zip code, city-state pair, or street address (Spaces are optional following the comma between a city and state)		91011 Pasadena,%20CA Cambridge,MA 1%20Main,Miami,FL	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
page	The page number of the result set to display	No	Positive integer	1	8
rpp	Results per page	No	Positive integer between 1 and 50 inclusive	20	20
sort	Sort criterion for the results	No	dist alpha highestrated mostreviewed topmatches offers		dist	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
publisher	The publisher code that identifies you.	Yes			acme
format	The desired format for the results	No	json xml pbuf	xml	json	json = javascript object notation xml = extensible markup language pbuf = Google's Protocol Buffers
placement	An optional property for storing additional information you would like CityGrid Media to log for this view	No				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
has_offers	Restricts search to listings that have offers associated with them	No	true false	false	true false	If this parameter is set to false it ignores the flag and returns all listings regardless of having offers.
histograms	Provide information on how many listings are in given groups and categories.	No	true false	false		Turning on histograms can affect performance. More information is provided below.
call_id	Iddentify a single search requests over subsequent pages.					The value should be set when making subsequent calls for the same search, but a different page of the results. This user should never supply their own generated value for call_id, instead it should be taken from the search results's first page.
tag_refinement	Restricts search to listings containing specific tags.	No	Tag(s) separated by comma.		haircut,hair dye	This is for getting results that match ALL tags. To search for results that match ANY tags use the what parameter
site	Restricts search to listings at a specific location	No	Integer		12345	Site Ids are provided in Places Detail API response where valid. This is useful for finding all places at a given location (e.g. a mall, a shopping or medical center, etc.)

Note that there are four ways to specify the kind of places to return in a where search.

What. Use the what parameter and specify the geographic location
Type. Use the type parameter and specify the geographic location
Tag. Use the tag parameter and specify the geographic location
Chain. Use the chain parameter and specify the geographic location
See #Specifying the Where Parameter for more details on how to specify the geographic location.

Where Search Usage Examples

The following table provides some example uses and their corresponding URL with query parameters. Click on the links to try them out.

Usage	URL
Find movie theaters in zip code 90045	https://api.citygridmedia.com/content/places/v2/search/where?type=movietheater&where=90045&publisher=test
Find Italian restaurants in Chicago using placement “sec-5”	https://api.citygridmedia.com/content/places/v2/search/where?what=restaurant&where=chicago,IL&tag=11279&placement=sec-5&publisher=test
Find hotels in Boston, viewing results 1-5 in alphabetical order	https://api.citygridmedia.com/content/places/v2/search/where?what=hotels&where=boston,ma&page=1&rpp=5&sort=alpha&publisher=test
Find pharmacies near the L.A. County Music Center, sorted by distance	https://api.citygridmedia.com/content/places/v2/search/where?what=pharmacy&where=135+N+Grand,LosAngeles,ca&sort=dist&publisher=test

Specifying the Where Parameter

To search for a location with a string, use the where endpoint and set the where parameter to the location's name or zip code. The CityGrid service will automatically parse the text and determine the geographical region to be searched.

Example: https://api.citygridmedia.com/content/places/v2/search/where?type=movietheater&where=90045&publisher=test

Depending on the value submitted, if successfully determined, one of six different types of areas may be searched. The table below describes the types of areas, as well as the default sort order in which the areas are returned.

Type	Examples	Default Order	Explanation
Cities	Los Angeles, CA San Francisco, CA Chicago, IL	Highest relevance first
Neighborhoods	Hollywood (Los Angeles, CA) Midtown (Manhattan, NY)	Highest relevance first
Zip Codes	90210	Highest relevance first
Metro Areas	Los Angeles, CA Metro New York, NY Metro	Highest relevance first	Expanded metropolitan regions, often including smaller neighboring cities
Addresses	1234 My Street, West Hollywood, CA	Smallest distance from the address first	A point-radius search is performed.
Intersections	Broadway and 7th Ave, Manhattan, NY	Smallest distance from the intersection first	A point-radius search is performed.

Note

If a single region cannot be determined by the value submitted, the response may contain a list of suggested regions (see #Geocoding.)

Search Using Latitude and Longitude

The latlon endpoint allows you to search for places using a geographic region defined by latitude and longitude.

LatLon Search HTTPS Endpoint

The following endpoint supports HTTPS GET:

https://api.citygridmedia.com/content/places/v2/search/latlon

LatLon Search Request

The following query string parameters are used with the Places API latlon endpoint:

Parameter	Description	Required	Valid Values	Default	Examples	Notes
type	Restricts search to listings of the given type	See Notes below.	movie movietheater restaurant hotel travel barclub spabeauty shopping		movie hotel restaurant	A full list of types supported is available as a json list and as a json tree. Only one category may be provided.
what	Search term text	See Notes below.			pizza sporting%20goods plumbers	A full list of types supported is available as a json list and as a json tree
tag	Restricts search to listings with the given tag id	See Notes below.	An integer		1722	Tag ids are internal CityGrid identifiers and subject to change. A full list of types supported is available as a json list and as a json tree. This parameter may be used in queries that are obtained as "refinement urls" from previous searches.
chain	Restricts search to listings with the given chain id.	See Notes below.	An integer.		360861766 41859967	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	Restricts search to entities whose name begins with the given character, or if "#", then to entities beginning with any digit	No	A character		s c
lat	Latitude of the center of a circle for a geographic search.	Yes.			37.65056
lon	Longitude of the center of a circle to search.	Yes			-119.03639
lat2	Second latitude used when performing a manual box search	See Notes below.			37.65056	lat2 and lon2 represents the lower right corner of the box
lon2	Second longitude used when performing a manual box search	See Notes below.			-119.03639	lat2 and lon2 represents the lower right corner of the box
radius	Radius of a circle search	See Notes below.	Positive number between 0 and 50 inclusive	5	7.5	If larger than 50 it defaults to 50
page	The page number of the result set to display	No	Positive integer	1	8
rpp	Results per page	No	Positive integer between 1 and 50 inclusive	20	20
sort	Sort criterion for the results	No	dist alpha highestrated mostreviewed topmatches offers		dist	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
publisher	The publisher code that identifies you.	Yes			acme
format	The desired format for the results	No	json xml pbuf	xml	json	json = javascript object notation xml = extensible markup language pbuf = Google's Protocol Buffers
placement	Store additional information you would like CityGrid Media to log for this view	No				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
has_offers	Restricts search to listings that have offers associated with them	No	true false	false	true false
histograms	Provide information on how many listings are in given groups and categories.	No	true false	false		Turning on histograms can affect performance. More information is provided below.
call_id	Identify a single search requests over subsequent pages.					The value should be set when making subsequent calls for the same search, but a different page of the results. This user should never supply their own generated value for call_id, instead it should be taken from the search results's first page.
tag_refinement	Restricts search to listings containing specific tags.	No	Tag(s) separated by comma.		haircut,hair dye	This is for getting results that match ALL tags. To search for results that match ANY tags use the what parameter
site	Restricts search to listings at a specific location	No	Integer		12345	Site Ids are provided in Places Detail API response where valid. This is useful for finding all places at a given location (e.g. a mall, a shopping or medical center, etc.)

Arguments must be properly URL-encoded (spaces as %20 or +, ampersands as %26, and so on).

Note that there are four ways to specify the kind of places to return in a lat-lon search.

Free-form Query. Use the what parameter and specify the geographic shape
Type. Use the type parameter and specify the geographic shape
Tag. Use the tag parameter and specify the geographic shape
Chain. Use the chain parameter and specify the geographic shape
All Places in a small radius. You can search without specifying the what, type, tag, or chain parameters by specifying a Point-Radius Circle search where the circle radius is 0.25 miles or less; in this case, all places within that radius will be returned.
See #Specifying the Geography for more details on how to specify the geographic shape.

LatLon Search Usage Examples

The following table provides some example uses and their corresponding URL with query parameters. Click on the links to try them out.

Usage	URL
Find movie theaters within 5 miles of latitude 34.03N, longitude118.28W	https://api.citygridmedia.com/content/places/v2/search/latlon?type=movietheater&lat=34.03&lon=-118.28&radius=5&publisher=test

Specifying the Geography

If you want to specify a geography to search for places in terms of latitude and longitude, there are two ways accomplish this:

Point-Radius
#Box

These methods are mutually exclusive. Specifying parameters that belong to more than one method may result in either a geography.overspecified error or incorrect results.

Point-Radius

The point-radius search returns listings in a region with the specified radius. To use this search, specify the lat, lon, and radius parameters.

Example: https://api.citygridmedia.com/content/places/v2/search/latlon?type=movietheater&lat=34.03&lon=-118.28&radius=5&publisher=test

Usage

The point-radius search is good for when you desire listings that are near a location. Use for fast searches sorted by relevance.

Note that the point-radius search results can be computed either through a bounding circle or a bounding box; we reserve the right to change the implementation over time.

Box

The box search is similar to the point-radius search, except that it returns listings in a rectangular region rather than a square or circular one. It does not calculate distances between a place and a reference coordinate, so searches are often faster. To use this search, specify the lat, lon, lat2, and lon2 parameters.

Example: https://api.citygridmedia.com/content/places/v2/search/latlon?type=movietheater&lat=34.03&lon=-118.28&lat2=34.08&lon2=-118.23&publisher=test

Usage

The box search is good for when the two corner points can be determined easily, such as when a user can custom-define the region to be searched. An example of this is a click-and-drag map that can be panned and zoomed by a user, dynamically changing the search region.

When you specify the lat, lon, lat2, and lon2 parameters, the CityGrid service searches a rectangle where (lat,lon) and (lat2,lon2) represent points on two opposite corners of the rectangle. Results are returned sorted by relevance, most relevant results first. The distance from the center point is not returned.

Search Response

The Places Search results are returned in either XML, JSON, or Google's Protocol Buffers.

The following table describes the return elements:

Element	Parent Element	Attributes	Description
results		rpp - Number of results requested per page page - Current page of results last_hit - Position of the last result in this page of results out of the total number of hits first_hit - Position of first result in this page of results out of the total number of hits total_hits - Total number of hits that matched the search query_id - Generated id associated with the search	Metadata regarding the search results.
uri	results		Request URL processed.
call_id	results		Please send this as a parameter to search api when accessing the subsequent page of results for the same search request.
did_you_mean	results		Spelling suggestions if what parameter was provided and not enough results were retrieved.
regions	results		Because the geographic region provided in the where parameter contains free-form text, its value may be ambiguous. This is a collection of interpretations.
region	regions	type - The type of geography this region represents (e.g. city, neighborhood)	Because the geographic region provided in the where parameter contains free-form text, its value may be ambiguous. This is a collection of interpretations.
name	region		Name of the region.
latitude	region		Latitude associated with the region.
longitude	region		Longitude associated with the region.
default_radius	region		Approximate radius for the region. Represents the value used for the radius if an address or intersection is used as a value for the where parameter.
locations	results		Collection of businesses that matched the search.
location	locations	id - The unique CityGrid Media identifier for this business listing	Representation of a single business or organization.
featured	location		True if a CityGrid customer, false if not.
public_id	location		The CityGrid id of the business listing.
name	location		The name of the business or organization.
address	location		The address of the business.
street	address		The street portion of the address.
city	address		The city portion of the address.
state	address		The state portion of the address.
postal_code	address		The postal code portion of the address.
neighborhood	location		The neighborhoods to which this business is associated.
latitude	location		The latitude of the listing.
longitude	location		The longitude of the listing.
distance	location		The distance from the supplied lat and lon during a point/radius search.
image	location		URL to an image associated with the business.
phone_number	location		The phone number of the business.
fax_number	location		The fax number of the business.
rating	location		The average user rating of the business.
tagline	location		The business' tagline.
profile	location		URL to the business' profile.
website	location		URL of business' website.
has_video	location		True if video content is available, false if not.
has_offers	location		True if offers are available, false if not.
offers	location		Text of the offer expiring the soonest.
user_reviews_count	location		Total number of user reviews of the business.
sample_categories	location		An abbreviated list of tags associated with the business.
impression_id	location		The internal impression id generated for tracking.
expansion	location		Currently not used. Intended for businesses that are associated with chains/franchises.
business_operation_status	location		The status of the business: open (a value of "1"), closed (a value of "0"), or unknown (a null value)
tags	location		Collection of all tags associated with this event
tag	tags	id - internal id associated with the tag	The name of a tag.

XML Response

The following is an example of an XML response with blank data.

<?xml version="1.0" encoding="utf-8"?>
<results rpp="" page="" last_hit="" first_hit="" total_hits=""
    query_id="">
    <uri></uri>
    <did_you_mean />
    <regions>
        <region type="">
            <name></name>
            <latitude></latitude>
            <longitude></longitude>
            <default_radius></default_radius>
        </region>
    </regions>
    <locations>
        <location id="">
            <featured></featured>
            <name></name>
            <address>
                <street></street>
                <city></city>
                <state></state>
                <postal_code></postal_code>
            </address>
            <neighborhood></neighborhood>
            <latitude></latitude>
            <longitude></longitude>
            <distance />
            <image></image>
            <phone_number></phone_number>
            <fax_number />
            <rating></rating>
            <tagline />
            <profile></profile>
            <website />
            <has_video></has_video>
            <has_offers></has_offers>
            <offers />
            <user_review_count></user_review_count>
            <sample_categories></sample_categories>
            <impression_id></impression_id>
            <expansion />
            <tags>
                <tag id=""></tag>
            </tags>
            <public_id/>
        </location>
    </locations>
    <histograms>
        <histogram name="">
            <items>
                <item name="" count=""></item>
            </items>
        </histogram>
    </histograms>
</results>

JSON Response

The following is an example of a JSON response:

{
    "results": {
        "query_id": "",
        "uri": "",
        "first_hit": 1,
        "last_hit": 20,
        "total_hits": 163,
        "page": 1,
        "rpp": 20,
        "did_you_mean": "",
        "regions": [
            {
                "type": "",
                "name": "",
                "latitude": 34.10652,
                "longitude": -118.411509,
                "default_radius": 22.45
            }
        ],
        "locations": [
            {
                "id": 3663784,
                "featured": false,
                "name": "",
                "address": {
                    "street": "",
                    "city": "",
                    "state": "",
                    "postal_code": ""
                },
                "neighborhood": "",
                "latitude": 41.8902,
                "longitude": -87.6338,
                "distance": "",
                "image": "",
                "phone_number": "",
                "fax_number": "",
                "rating": 8,
                "tagline": "",
                "profile": "",
                "website": "",
                "has_video": false,
                "has_offers": false,
                "offers": "",
                "user_review_count": 265,
                "sample_categories": "",
                "impression_id": "",
                "expansion": {
                    "count": "",
                    "uri": ""
                },
                "tags": [
                {
                    "id": "",
                    "name: ""
                },
                "public_id": ""
                ]
            }
        ],
        "histograms": [
            {
                "name": "Categories",
                "items": [
                    {
                        "count": 137,
                        "name": "",
                        "uri": "",
                        "tag_ids": [
                            {
                                "tag_id": 10015
                            }
                         ]
                    }
                ]
            }
        ]
    }
}

Notes

If a callback parameter is supplied, the JSON response will be wrapped in a call as follows:

callback_name({"results": {...}})

Protocol Buffers Response

Google's Protocol Buffers is a format that can easily be processed by applications written in Java, C++, or Python. To use the protocol buffer format, run the protocol buffer compiler for your language on this proto file. The generated classes can then be used to populate, serialize, and read protocol buffer messages.

See Google's Tutorials for information on how to compile .proto files and use the generated classes.

Spelling suggestions

A query may return spelling suggestions if it appears that the user might have misspelled a word or listing. Spelling suggestions will appear in a didyoumean element. For example, a query containing what=computr+parts yields might return:

<did_you_mean>computer parts</did_you_mean>

Geocoding

Because the geographic region given in the where parameter contains free-form text, its value may be ambiguous. If there is ambiguity, we provide a collection of possible interpretations, and perform a search on the first one listed.

For example, the query string

where=vail&what=candy

might produce a result as follows:

<results>
...
<regions>
    <region type="city">
        <name>Vail, CO</name>
        <latitude>39.6388</latitude>
        <longitude>-106.3624</longitude>
        <default_radius>2.130000</default_radius>
    </region>
    <region type="city">
        <name>Vail, IA</name>
        <latitude>42.0598</latitude>
        <longitude>-95.2004</longitude>
        <default_radius>0.740000</default_radius>
    </region>
    <region type="neighborhood">
        <name>Vail Vista Estates, AZ</name>
        <latitude>32.0321</latitude>
        <longitude>-110.6999</longitude>
        <default_radius>0.350000</default_radius>
    </region>
    <region type="neighborhood">
        <name>Vail Ranch, AZ</name>
        <latitude>32.0512</latitude>
        <longitude>-110.6870</longitude>
        <default_radius>0.320000</default_radius>
    </region>
    <region type="neighborhood">
        <name>Old Vail Village (Tucson, AZ)</name>
        <latitude>32.0436</latitude>
        <longitude>-110.7114</longitude>
        <default_radius>0.270000</default_radius>
    </region>
</regions>
...
</results>

In the example above, the geography term "Vail" matched five different regions. The webservice found "Vail, CO" to be the best match and placed it first. The geocode match that appears first is the one used to produce the results that follow. Clients are free to check for multiple geocoded regions and suppress displaying results to their own users if they wish. The geocoder may return a latitude, longitude and “default radius” for each region. The latitude and longitude represent an approximate center point for the corresponding region. The "default radius" is an approximate radius for the corresponding region, and represents the value used for the radius if an address or intersection is used as a value for the where parameter. See #Specifying the Geography for more details.

If a search returns zero results for the specified geography, the webservice will expand the search to a larger geographical location and search again. If no results are found in the expanded geography, the service will then return an empty result set.

Histograms

Histograms provide information on how many listings are in given groups and categories.

Histograms Optional

The histograms feature will be disabled by default. If you require histograms as part of the response, then include the query parameter histograms=true in the query. Generating histograms requires additional processing and may slow down the query, so if they're not needed, leave this turned off.

Each non-empty successful response contains a set of zero or more histograms that give the number of results for each tag. Each histogram also contains uris to carry out refinement searches. For example, a search for “food” in a 0.7 mile radius around zip code 90004 yields three histograms:

<histograms>
    <histogram name="Cuisine">
        <items>
            <item name="Thai" count="4">
                <url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=11319&where=90004&radius=0.7&publisher=xyz</url>
                <tag_ids>
                    <tag_id>11319</tag_id>
                </tag_ids>
            </item>
            <item name="Chinese" count="3">
                <url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=11252&where=90004&radius=0.7&publisher=xyz</url>
                <tag_ids>
                    <tag_id>11252</tag_id>
                </tag_ids>
            </item>
            <item name="Mexican" count="1">
                <url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=11208&where=90004&radius=0.7&publisher=xyz</url>
                <tag_ids>
                    <tag_id>11208</tag_id>
                </tag_ids>
            </item>
        </items>
    </histogram>
    <histogram name="Categories">
        <items>
            <item name="Ice Cream Parlors" count="1">
                <url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=1730&where=90004&radius=0.7&publisher=xyz</url>
                <tag_ids>
                    <tag_id>1730</tag_id>
                </tag_ids>
            </item>
            <item name="Grocery Stores" count="20">
                <url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=1712&where=90004&radius=0.7&publisher=xyz</url>
                <tag_ids>
                    <tag_id>1712</tag_id>
                </tag_ids>
            </item>
            <item name="Coffeehouses" count="2">
                <url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=1726&where=90004&radius=0.7&publisher=xyz</url>
                <tag_ids>
                    <tag_id>1726</tag_id>
                </tag_ids>
            </item>
            <item name="Restaurants" count="26">
                <url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=1722&where=90004&radius=0.7&publisher=xyz</url>
                <tag_ids>
                    <tag_id>1722</tag_id>
                </tag_ids>
            </item>
        </items>
    </histogram>
    <histogram name="Health Food Store Products">
        <items>
            <item name="Vitamins" count="2">
                <url>http://api.citygridmedia.com/content/places/v2/search/where?what=food&tag=11164&where=90004&radius=0.7&publisher=xyz</url>
                <tag_ids>
                    <tag_id>11164</tag_id>
                </tag_ids>
            </item>
        </items>
    </histogram>
</histograms>

The refinement uri contains a tag parameter. The value of this parameter is valid for only a short period of time and should not be relied on for anything but a subsequent search.

Search Error Reporting

CityGrid Media provides error codes, rather than error messages. This allows you to customize the text and language for display. If a request can not be completed for any reason, an error document will be returned with a set of mnemonic error codes to help you troubleshoot the error.

Error Codes

A complete list of error codes follows:

Code	Description
query.underspecified	Neither type, what, tag, nor chain was specified
query.type.unknown	The query type parameter is not supported
query.overspecified	The parameter type was specified in addition to tag or chain
geography.underspecified	Neither where, lat, nor lon were given
geography.overspecified	Both where and one of lat or lon were given
radius.required	Both lat and lon were given, but radius was missing
geocode.failure	The geocoder could not find a match for the given where parameter
tag.illegal	The parameter tag was not an integer
chain.illegal	The parameter chain was not an integer
first.illegal	The parameter first was not a character
latitude.illegal	The parameter lat was not a valid number
longitude.illegal	The parameter lon was not a valid number
radius.illegal	The parameter radius was not a valid number
page.illegal	The parameter page was not an integer
rpp.illegal	The parameter rpp was not an integer
sort.illegal	The parameter sort contained an unknown value
radius.out.of.range	The parameter radius was below 1
page.out.of.range	The parameter page was less than 1
rpp.out.of.range	The parameter rpp was not in the range 1..50
publisher.required	The publisher parameter is missing
internal.error	An internal problem with the service occurred

XML Error Response

In the XML response, the error codes are contained within errors and error tags.

Element	Parent Element	Description
errors		Root node. A Collection of errors.
error	errors	An error code. See the table of error codes above.

For example, the following request:

https://api.citygridmedia.com/content/places/v2/search/where?what=food&where=los+angeles,ca

returns the following response:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error>publisher.required</error>
</errors>

JSON Error Response

In the JSON response, the error codes are values paired with error keys, as part of an errors array.

For example, the following request:

https://api.citygridmedia.com/content/places/v2/search/where?where=lax&page=q&lon=2&format=json

returns the following response:

{
    "errors": [
        {
            "error": "page.illegal"
        },
        {
            "error": "query.underspecified"
        },
        {
            "error": "geography.overspecified"
        },
        {
            "error": "publisher.required"
        }
    ]
}

Places Detail

The Places Details API provides programmatic access to CityGrid's local listings data, including businesses and events.

Detail HTTPS Endpoint

https://api.citygridmedia.com/content/places/v2/detail

Detail Request

The following query string parameters are used with the Places API search endpoint:

Parameter	Description	Required	Valid Values	Default	Examples	Notes
id	An id used to identify a place	Yes, if listing_id, infousa_id, public_id, or phone is not provided. If used, then id_type must also appear.	An applicable id string		3151050
id_type	A corresponding type passed in with id	Yes, if using id	List of id types		cg	If you are switching from the deprecated parameters to the new parameters id and id_type, here is the corresponding id type mappings: public_id : cg listing_id : cs infousa_id : iusa For the full list of legal id_type values, look here
(DEPRECATED) listing_id	A unique numeric id identifying a customer's business.	Yes, if infousa_id, public_id, or phone is not provided.	Positive integer		3151050	This field is deprecated. It is still supported but will be removed from future version.
(DEPRECATED) public_id	A unique text id identifying a customer's business, useful in forming URLs.	Yes, if infousa_id, listing_id, or phone is not provided.	String		pinks-hot-dogs-los-angeles	This field is deprecated. It is still supported but will be removed from future version.
(DEPRECATED) infousa_id	The InfoUSA identifier of the business.	Yes, if listing_id, public_id or phone is not provided.	Positive integer		934233230	This field is deprecated. It is still supported but will be removed from future version.
phone	Requests listings with this phone number.	Yes, if listing_id, public_id or infousa_id is not provided.	10 digits with no spaces or dashes		3105551212	Up to a maximum of 25 will be returned.
publisher	The publisher code that identifies you.	Yes			acme
customer_only	Whether you wish to restrict the results to places of CityGrid customers only.	No	true false	false	true
all_results	Whether you wish to have all results or as opposed to one result for a particular infousa_id or a phone.	No	true false	false	true
review_count	The maximum number of reviews you want shown in the response.	No	Positive integer between 0 and 20 inclusive	3	10
exclude_editorial	Whether you wish to receive a review of type "editorial_review" in the response	No	true, false	false	true
offer_count	The maximum number of offers you want shown in the response	No	Positive integer between 0 and 10 inclusive	10	3
placement	An optional property for storing additional information you would like CityGrid Media to log for this view.	No			sem_google sem_yahoo home_page search	An example: if you run a search engine marketing campaign for 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.
client_ip	The IP address of the client to whom you will be sending the place data.	Yes	Four numbers between 0 and 255 separated by periods.		123.45.67.89
format	The desired format for the results.	No	json xml pbuf	xml	json	json = javascript object notation xml = extensible markup language pbuf = Google's Protocol Buffers
callback	The name of (your own) JavaScript function that you would like to wrap your JSON response.	No			display cache
i	An optional property for grouping API calls for tracking purposes. The parameter name is shortened from impression_id.	No				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. For example, the impression_id from a Places Search API response would be used as a request to Places Detail API if the listing is clicked on.
mobile_type		This field designates publisher device type name or designates the usage of our content on your Wireless Application Protocol (WAP) site.		Required for mobile publishers
muid	The hash of user phone number and/or device ID as provided by the carrier. Max of 32 chars	Required for mobile publishers
ua		The client side user agent. Must be properly html encoded. Ignore if it's not.		Required for mobile publishers
sourcephone	The source phone for the click to call implementation on mobile phones. Could be the last 4,no dashes	Required for mobile publishers
image_count	An optional value that allows the user to limit the number of images returned.	No	0 and all positive 32-bit integers		0, 1, 50
image_size_min	An optional value that allows the user to return images that are of a minimum specified size.	No	A String consisting of the Width followed by the Height		100x200 50x150 1200x1200	When used in conjunction with the image_size_max parameter the width and height of the image_size_min parameter must be less than or equal to the image_size_max value.
image_size_max	An optional value that allows the user to return images that are of a maximum specified size.	No	A String consisting of the Width followed by the Height		100x200 50x150 1200x1200	When used in conjunction with the image_size_min parameter the width and height of the image_size_max parameter must be greater than or equal to the image_size_min value.

Arguments must be properly URL-encoded (spaces as %20 or +, ampersands as %26, and so on).

customer_message_url, listing_id, public_id, and infousa_id are deprecated. They will continue to work in this version but will eventually be removed in a future version. Please switch to using id and id_type as soon as possible.

Detail Usage Examples

The following table provides some example uses and their corresponding URL with query parameters. Click on the links to try them out.

Usage	URL
Find the place with listing id 10100230, placement "search_page", and client ip 123.4.56.78	https://api.citygridmedia.com/content/places/v2/detail?id=10100230&id_type=cs&placement=search_page&client_ip=123.4.56.78&publisher=test
Find the place with infousa ID of 412275828 and client IP of 123.124.123.124	https://api.citygridmedia.com/content/places/v2/detail?id=412275828&id_type=iusa&client_ip=123.124.123.124&publisher=test
Find the place with phone 323-256-9617 and client IP of 123.124.123.124	https://api.citygridmedia.com/content/places/v2/detail?phone=3232569617&client_ip=123.124.123.124&publisher=test
Find the place with phone 323-256-9617 and client IP of 123.124.123.124, and placement "search_page" and display all listings associated with that phone	https://api.citygridmedia.com/content/places/v2/detail?phone=3232569617&client_ip=123.124.123.124&placement=search_page&all_results=true&publisher=test
Find the place with phone 323-256-9617 and client IP of 123.124.123.124, and placement "search_page" and (at most) the first 10 reviews	https://api.citygridmedia.com/content/places/v2/detail?phone=3232569617&client_ip=123.124.123.124&placement=search_page&review_count=10&publisher=test

Detail Response

The Places Detail results are returned in either XML, JSON, or Google's Protocol Buffers.

The following table describes the return elements:

Element	Parent Element	Attributes	Description
locations			Wraps the returned places
location	locations		Representation of a single business or organization
id	location		The unique numeric identifier for the place, this is the CURRENT id for this place, if a merged or older id was used to search for this place, only the current id will be returned
public_id	location		The unique textual, url-friendly identifier for this place
infousa_id	location		The InfoUSA identifier for this place
reference_id	location		A secondary identifier for the place, used for tracking
impression_id	location		The internal impression id generated for tracking.
name	location		The name of the place
display_ad	location		Whether or not the ads should be displayed for this place
claimed	location		True if an owner has claimed their business and been verified by CityGrid
teaser	location		A brief, catchy line for the place
business_operation_status	location		The status of the business: open, closed, or unknown
address	location		Wraps the address individual address fields
years_in_business	location		Quantity in years that the place has been in business
last_update_time	location		Date that the place was last updated
street	address		The street portion of the address
delivery_point	address		An extension to the address (suite, floor, etc)
city	address		The city portion of the address
state	address		The state portion of the address
postal_code	address		The postal code portion of the address
cross_street	address		Cross street information
latitude	address		The latitude of the place
longitude	address		The longitude of the place
contact_info	location		Wraps the contact information fields
display_phone	contact_info		The phone number of the place to display
display_url	contact_info		The URL of the place to display
social_media	contact_info		Wraps contact info on supported social media platforms
twitter_username	social_media		Wraps twitter contact information
text	twitter_username		The Twitter handle
facebook_fanpage	social_media		Wraps facebook contact information
text	facebook_fanpage		The facebook username
url	facebook_fanpage		The URL of the place on facebook
markets	location		Wraps the returned markets
market	markets		Name of a single market
neighborhoods	location		Wraps the returned neighborhoods
neighborhood	neighborhoods		Name of a single neighborhood
urls	location		Wraps the set of urls for this place
profile_url	urls		The URL of the place on CityGrid
reviews_url	urls		The URL for the place's reviews
video_url	urls		The URL for the place's video
website_url	urls		The URL for the place's main website
menu_url	urls		The URL for the place's menu
reservation_url	urls		The URL at which one can make reservations for this place
map_url	urls		The URL for the listing's map
send_to_friend_url	urls		The URL at which one can notify friends about this place
email_link	urls		The URL at which one can email the place.
custom_link_1	urls		Additional URL provided by the place.
custom_link_2	urls		Additional URL provided by the place.
custom_link_3	urls	type - Type of link (i.e "menu")	Additional URL provided by the business.
custom_link_4	urls	type - Type of link (i.e "menu")	Additional URL provided by the business.
custom_links	urls		List of custom urls provided by a merchant - these are the clicks they are most interested in.
type	custom_link		The action_target the link corresponds to. A full list is available under Places That Pay
url	custom_link		The destination url of the link. This is usually to a specific page within an advertiser's website for lead gen (a form fill) or conversion (e.g. a booking). This is an obfuscated url and is not intended for a user to read.
display_text	custom_link		The text to display for the URL. For example "View Brochure" or "Book Now!"
	location		An encrypted Places that Pay tracking URL.
customer_content	location		Wraps the customer message, the customer message url, and the bullets
customer_message	customer_content	attribution_source - Unique identifier of the content provider attribution_logo - The logo of the content provider (typically an 88 x 33 jpeg) attribution_text - Name of the content provider, to be displayed in place of, or along side of, the attribution logo attribution_url - The URL for the for content provider, to be linked to from the logo and text	A short message about this business written by or on behalf of its owner
customer_message_url (DEPRECATED)	customer_content		The URL hosting the customer message on Citysearch.com
bullets	customer_content		Wraps the bullet points of the customer message
bullet	bullets		An individual bullet point within the customer message
offers	location	attribution_source - Unique identifier of the content provider attribution_logo - The logo of the content provider (typically an 88 x 33 jpeg) attribution_text - Name of the content provider, to be displayed in place of, or along side of, the attribution logo attribution_url - The url of the content provider	Wraps offer details
offer	offers		An offer
offer_name	offer		The name of the offer
offer_text	offer		The text of the offer
offer_description	offer		The description of the offer
offer_url	offer		The URL of the offer
offer_expiration_date	offer		The date on which the offer expires in ISO 8601 format.
categories	location		Wraps categorization information about this listing
category	categories	name_id - The CityGrid internal id of the category name - The name of the category parent_id - The id of the parent of the category parent - The name of the parent of the category, For example the parent of the "restaurant" category would be "Food and Dining" primary - If the category is primary or not	A category that tags this listing
group	category	group_id name	The group to which the category belongs. For example, the category "brunch" might belong to the group "restaurant features"
attributes	location		Wraps attribute information
attribute	attributes	attribute_id name - Part of the attribute's name-value pair value - Part of the attribute's name-value pair	A single attribute, or name-value pair, that gives further information about this listing
business_hours	location		The hours that the business is open, if known
parking	location		Parking details
tips	location		Wraps the tips for this listing
tip	tips		A single tip
tip_name	tip		The title of the tip (very short)
tip_text	tip		The text of the tip
images	location		Wraps information for the associated images
image	images	type - One of WEBSITE_THUMBNAIL (a thumbnail of the listing's own website), or GENERIC_IMAGE (a photo that is part of the listing's slideshow). attribution_source - Unique identifier of the content provider attribution_logo - The logo of the content provider (typically an 88 x 33 jpeg) attribution_text - Name of the content provider, to be displayed in place of, or along side of, the attribution logo	A single image
height	image		Height of the image
width	image		Width of the image
image_url	image		URL of the image
editorials	location		Wraps editorial reviews
editorial	editorials	attribution_source - Unique identifier of the content provider attribution_logo - The logo of the content provider (typically an 88 x 33 jpeg) attribution_text - Name of the content provider, to be displayed in place of, or along side of, the attribution logo	A single editorial review
editorial_id	editorial		The id of the editorial review
editorial_url	editorial		The url of the full editorial review
editorial_title	editorial		The title of the editorial review
editorial_author	editorial		The author of this editorial review
editorial_review	editorial		The content of the editorial review, which may be abbreviated
pros	editorial		Favorable bullet points written by the review author
cons	editorial		Unfavorable bullet points written by the review author
editorial_date	editorial		The date the editorial review was written in ISO 8601 format.
review_rating	editorial		The rating for the review
helpfulness_total_count	editorial		The number of times a review has been marked helpful or unhelpful
helpful_count	editorial		The number of times a review has been marked helpful
unhelpful_count	editorial		The number of times a review has been marked unhelpful
review_info	location		Review statistics
overall_review_rating	review_info		The rating for the review (a number between 0 and 10) or NA
total_user_reviews	review_info		The number of reviews that have been written for this listing
total_user_reviews_shown	review_info		The number of reviews shown in this response (may be less than the total number)
reviews	review_info		Collection of all reviews
review	reviews	attribution_source - Unique identifier of the content provider attribution_logo - The logo of the content provider (typically an 88 x 33 jpeg) attribution_text - Name of the content provider, to be displayed in place of, or along side of, the attribution logo attribution_url - The website of the reviews source.	A single review
review_id	review		The internal CityGrid id for the review
review_url	review		The URL of the review on CityGrid (required for link-back attribution)
review_title	review		The title given to the review by its author
review_author	review		The name of the user that wrote the review
review_text	review		The text of the review
pros	review		Favorable bullet points written by the review author
cons	review		Unfavorable bullet points written by the review author
review_date	review		The date the review was written in ISO 8601 format.
review_rating	review		The rating for the review (a number between 0 and 10)
helpfulness_total_count	review		The number of times a review has been marked helpful or unhelpful
helpful_count	review		The number of times a review has been marked helpful
unhelpful_count	review		The number of times a review has been marked unhelpful
review_type	review		The type of review. Current types are user_review and editorial_review
geographies	location		The geographic regions associated with the place.
geography	geographies		A single geography.
id	geography		Unique identifier for the specific region.
type	geography		A description of the region, one of: `city`, `county`, `market`, `neighborhood`, `postal.code`, `state`).
value	geography		The common name for the region. Examples: Venice, CA (neighborhood), Los Angeles, CA (city), Los Angeles, CA Metro (market).

XML Response

The following is an example of an XML response with blank data.

character data is required to be escaped, so you will likely see the character entities ", &, >, <, and '.

<locations>
    <location>
        <id></id>
        <reference_id></reference_id>
        <impression_id></impression_id>
        <display_ad></display_ad>
        <infousa_id></infousa_id>
        <name></name>
        <teaser></teaser>
        <address>
            <street></street>
            <delivery_point />
            <city></city>
            <state></state>
            <postal_code></postal_code>
            <cross_street />
            <latitude />
            <longitude />
        </address>
        <contact_info>
            <display_phone></display_phone>
            <display_url></display_url>
            <social_media>
                <twitter_username>
                    <image_icon></image_icon>
                    <text></text>
                    <url></url>
                </twitter_username>
                <facebook_fanpage>
                    <image_icon></image_icon>
                    <text></text>
                    <url></url>
                </facebook_fanpage>
            </social_media>
        </contact_info>
        <markets>
            <market></market>
            <market></market>
        </markets>
        <neighborhoods>
            <neighborhood></neighborhood>
            <neighborhood></neighborhood>
        </neighborhoods>
        <urls>
            <profile_url />
            <reviews_url />
            <video_url />
            <website_url />
            <menu_url />
            <reservation_url />
            <map_url />
            <send_to_friend_url />
            <email_link />
            <custom_link_1 />
            <custom_link_2 />
            <custom_link_3 type="" />
            <custom_link_4 type="" />
			<custom_links>
			     <custom_link>
			 		<type>online_enrollment</type>
				        <url>http://api.citygridmedia.com/rbl/content/places/v2/click?q=stcikV14e35E2qZXkN4</url>
				        <display_text>Enroll!</display_text>
				     </custom_link>
						</custom_links>
        </urls>
        <impression_url />
        <customer_content>
            <customer_message attribution_text="" attribution_logo="" attribution_source=""></customer_message>
            <bullets>
                <bullet></bullet>
                <bullet></bullet>
            </bullets>
            <customer_message_url></customer_message_url>
        </customer_content>
        <offers>
            <offer attribution_logo="" attribution_source="" attribution_text="" attribution_url="">
                <offer_name></offer_name>
                <offer_text></offer_text>
                <offer_description></offer_description>
                <offer_url></offer_url>
                <offer_expiration_date></offer_expiration_date>
            </offer>
        </offers>
        <categories>
            <category parent="" parent_id="" name="" name_id="" primary="">
                <groups>
                    <group name="" group_id=""/>
                </groups>
            </category>
        </categories>
        <attributes>
            <attribute value="" name="" attribute_id=""/>
        </attributes>
        <business_hours />
        <parking />
        <tips>
            <tip>
                <tip_name />
                <tip_text />
            </tip>
        </tips>
        <images>
            <image attribution_text="" attribution_logo="" attribution_source="" type="">
                <height/>
                <width/>
                <image_url/>
            </image>
        </images>
        <editorials>
            <editorial attribution_text="" attribution_logo="" attribution_source="">
                <editorial_id/>
                <editorial_url/>
                <editorial_title/>
                <editorial_author/>
                <editorial_review/>
                <pros/>
                <cons/>
                <editorial_date/>
                <review_rating/>
                <helpfulness_total_count/>
                <helpful_count/>
                <unhelpful_count/>
            </editorial>
        </editorials>
        <review_info>
            <overall_review_rating />
            <total_user_reviews />
            <total_user_reviews_shown />
            <reviews>
                <review attribution_text="" attribution_logo="" attribution_source="">
                    <review_id />
                    <review_url />
                    <review_title />
                    <review_author />
                    <review_text />
                    <pros />
                    <cons />
                    <review_date />
                    <review_rating />
                    <helpfulness_total_count />
                    <helpful_count />
                    <unhelpful_count />
                    <review_type />
                </review>
            </reviews>
        </review_info>
        <years_in_business/>
        <last_update_time/>
        <public_id/>
        <business_operation_status/>
        <geographies>
            <geography type="" id=""></geography>
        </geographies>
    </location>
</locations>

JSON Response

The following is an example of a JSON response with blank data:

{
    "locations" : [
        {
            "id" : 1,
            "reference_id" : "",
            "impression_id" : "",
            "display_ad" : true,
            "infousa_id" : 1,
            "name" : "",
            "teaser" : "",
            "address" : {
                "street" : "",
                "delivery_point" : "",
                "city" : "",
                "state" : "",
                "postal_code" : "",
                "cross_street" : "",
                "latitude" : 1.0,
                "longitude" : -1.0
            },
            "contact_info" : {
                "display_phone" : "",
                "display_url" : "",
                "social_media" : {
                    "twitter_username" : {
                        "image_icon" : "",
                        "text" : "",
                        "url" : ""
                    },
                    "facebook_fanpage" : {
                        "image_icon" : "",
                        "text" : "",
                        "url" : ""
                    }
                }
            },
            "markets" : [
                ""
            ],
            "neighborhoods" : [
                ""
            ],
            "urls" : {
                "profile_url" : "",
                "reviews_url" : "",
                "video_url" : "",
                "website_url" : "",
                "menu_url" : "",
                "reservation_url" : "",
                "map_url" : "",
                "send_to_friend_url" : "",
                "email_link" : "",
                "custom_link_1" : "",
                "custom_link_2" : "",
                "custom_link_3" : {
                     "type" : "",
                     "source" :""
                },
                "custom_link_4" : {
                     "type" : "",
                     "source" : ""
                },
				custom_links: [
					  type: "free_estimate",
					  url: "http://api.citygridmedia.com/rbl/content/places/v2/click?q=lakejr1po34urfwaeosdi",
					  display_text: "Request a FREE estimate"
				]
            },
            "impression_url" : "",
            "customer_content" : {
                "customer_message" : {
                    "attribution_source" : "",
                    "attribution_logo" : "",
                    "attribution_text" : "",
                    "value" : ""
                },
                "bullets" : [
                    ""
                ],
                "customer_message_url" : ""
            },
            "offers" : [
                {
                    "offer_name" : "",
                    "offer_text" : "",
                    "offer_description" : "",
                    "offer_url" : "",
                    "offer_expiration_date" : "",
                    "attribution_source" : "",
                    "attribution_logo" : "",
                    "attribution_text" : "",
                    "attribution_url" : ""
                }
            ],
            "categories" : [
                {
                    "name_id" : 1,
                    "name" : "",
                    "parent_id" : 1,
                    "parent" : "",
		    "primary": "",
                    "groups" : [
                        {
                            "group_id" : 1,
                            "name" : ""
                        }
                    ]
                }
            ],
            "attributes" : [
                {
                    "attribute_id" : 1,
                    "name" : "",
                    "value" : ""
                }
            ],
            "business_hours" : "",
            "parking" : "",
            "tips" : [
                {
                    "tip_name" : "",
                    "tip_text" : ""
                }
            ],
            "images" : [
                {
                    "type" : null,
                    "height" : null,
                    "width" : null,
                    "image_url" : null,
                    "attribution_source" : "",
                    "attribution_logo" : "",
                    "attribution_text" : ""
                }
            ],
            "editorials" : [
                {
                    "attribution_source" : "",
                    "attribution_logo" : "",
                    "attribution_text" : "",
                    "editorial_id" : 1,
                    "editorial_url" : "",
                    "editorial_title" : "",
                    "editorial_author" : "",
                    "editorial_review" : "",
                    "pros" : "",
                    "cons" : "",
                    "editorial_date" : "",
                    "review_rating" : 2.0,
                    "helpfulness_total_count" : 1,
                    "helpful_count" : 1,
                    "unhelpful_count" : 1
                }
            ],
            "years_in_business" : "",
            "last_update_time" : "",
            "public_id" : "",
            "business_operation_status" : "",

            "review_info" : {
                "overall_review_rating" : 2.0,
                "total_user_reviews" : 1,
                "total_user_reviews_shown" : 1,
                "reviews" : [
                    {
                        "attribution_source" : "",
                        "attribution_logo" : "",
                        "attribution_text" : "",
                        "review_id" : 1,
                        "review_url" : "",
                        "review_title" : "",
                        "review_author" : "",
                        "review_text" : "",
                        "pros" : "",
                        "cons" : "",
                        "review_date" : "",
                        "review_rating" : 2.0,
                        "helpfulness_total_count" : 1,
                        "helpful_count" : 1,
                        "unhelpful_count" : 1,
                        "review_type" : ""
                    }
                ]
            },
            "geographies": [
                {
                    "id": "",
                    "value": "",
                    "type": ""
                }
            ]
        }
    ]
}

If a callback parameter is supplied, the JSON response will be wrapped in a call as follows:

callback_name({"locations": [...]})

Protocol Buffers Response

Google's Protocol Buffers is a format that can easily be processed by applications written in Java, C++, or Python. To use the protocol buffer format, run the protocol buffer compiler for your language on this proto file. The generated classes can then be used to populate, serialize, and read protocol buffer messages.

See Google's Tutorials for information on how to compile .proto files and use the generated classes.

Impression Url

Places Details provides a basic Places that Pay tracking URL in the response called impression_url. This url contains information about the location and can be used in place of the Javascript implementation of Places that Pay. Publishers intend to utilize this field should append the action_target parameter at the end of the url and send it whenever there is a billable action.

Detail Error Reporting

CityGrid Media provides error codes, rather than error messages. This allows you to customize the text and language for display. If a request can not be completed for any reason, an error document will be returned with a set of mnemonic error codes to help you troubleshoot the error.

Error Codes

A complete list of error codes follows:

Code	Reason
query.overspecified	More than one of listing id, infousa id, and phone was given
query.underspecified	Neither listing id, infousa id, nor phone was given for search
id.illegal	The listing id provided was not in the correct format
customer.only.illegal	The value of the customer_only parameter was illegal
publisher.required	The publisher was not given
listing.not.found	No listing with the given id exists
phone.not.found	No listing with the given phone exists
phone.invalid	The phone number was not valid
client.ip.invalid	The client ip parameter was not supplied or not correct
infousa.id.illegal	The value of the infousa_id parameter was illegal
review.count.illegal	The value of the review_count parameter was illegal
all.results.illegal	The value of the all_results parameter was not either true or false
internal.error	An internal problem with the service has occurred
image.count.illegal	The value of the image_count is not a valid number
image.count.out.of.range	The value of the image_count is a negative
image.size.range.invalid	The value of image_size_min is greater than the image_size_max
image.size.illegal	The value of image_size_min and/or image_size_max do not follow the format specified in the Detail Request

XML Error Response

In the XML response, the error codes are contained within errors and error tags.

Element	Parent Element	Description
errors		Root node. A Collection of errors.
error	errors	An error code. See the table of error codes above.

For example, the following request:

https://api.citygridmedia.com/content/places/v2/detail?listing_id=joes+pizza

returns the following response:

<errors>
   <error>id.illegal</error>
   <error>publisher.required</error>
   <error>query.underspecified</error>
   <error>client.ip.invalid</error>
</errors>

JSON Error Response

In the JSON response, the error codes are values paired with error keys, as part of an errors array.

For example, the following request:

https://api.citygridmedia.com/content/places/v2/detail?listing_id=2&publisher=sam&format=json

returns the following response:

{
    "errors": [
        {
            "error": "client.ip.invalid"
        }
    ]
}

Places API

Introduction

Contents

Audience

Version 2 Updates

Places Search

Search Using Where

Where Search HTTPS Endpoint

Where Search Request

Where Search Usage Examples

Specifying the Where Parameter

Search Using Latitude and Longitude

LatLon Search HTTPS Endpoint

LatLon Search Request

LatLon Search Usage Examples

Specifying the Geography

Point-Radius

Box

Search Response

XML Response

JSON Response

Notes

Protocol Buffers Response

Spelling suggestions

Geocoding

Histograms

Search Error Reporting

Error Codes

XML Error Response

JSON Error Response

Places Detail

Detail HTTPS Endpoint

Detail Request

Detail Usage Examples

Detail Response

XML Response

JSON Response

Protocol Buffers Response

Impression Url

Detail Error Reporting

Error Codes

XML Error Response

JSON Error Response