Places API

Skip to end of metadata
Go to start of metadata

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.

Contents

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:

  • 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 histograms is 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 search requests:
    • i (impression_id)
  • 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.
  • 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.
  • 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:

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 HTTP Endpoint

The following endpoint supports HTTP GET:

http://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 results to listings of the given type See Notes below. movie
movietheater
restaurant
hotel
travel
barclub
spabeauty
shopping 		  movie
hotel
restaurant 		 
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. This parameter should only 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   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 Return 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 An optional property for providing 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.
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.


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 http://api.citygridmedia.com/content/places/v2/search/where?type=movietheater&where=90045&publisher=test
Find Italian restaurants in Chicago using placement “sec-5” http://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 http://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 http://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: http://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 HTTP Endpoint

The following endpoint supports HTTP GET:

http://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 results to listings of the given type See Notes below. movie
movietheater
restaurant
hotel
travel
barclub
spabeauty
shopping 		  movie 
hotel 
restaurant
 
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. This parameter should only 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   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 Whether to return only listings that have offers associated with them
No
true
false
false
true 
false
 
histograms An optional property for providing 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.
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.
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 http://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:

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: http://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: http://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.
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.  
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:

http://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:

http://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 HTTP Endpoint

http://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  
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.


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 http://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 http://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 http://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 http://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 http://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
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.
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 		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 (citysearch review), external_user_review, editorial_review

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="" />
        </urls>
        <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/>
    </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" : ""
                }
            },
            "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" : ""
                    }
                ]
            }
        }
    ]
}

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.

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

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:

http://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:

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

returns the following response:

{
    "errors": [
        {
            "error": "client.ip.invalid"
        }
    ]
}
Enter labels to add to this page:
Please wait 
Looking for a label? Just start typing.