Page Comparison

...

Applications that display recent reviews for restaurants in a particular neighborhood.
Applications that display a "hot spot" map showing locations for which people are actively creating reviews.

Audience

The Reviews API is intended for developers of web and mobile applications who want to obtain customer reviews by subject and/or location.

...

Reviews Search

Search Using Where

Where

...

HTTPS Endpoint

The following endpoint supports HTTP HTTPS GET:

Code Block
httphttps://api.citygridmedia.com/content/reviews/v2/search/where

...

Usage	URL
Find reviews for sushi restaurants in Los Angeles	httphttps://api.citygridmedia.com/content/reviews/v2/search/where?where=los%20angeles,ca&what=sushi&publisher=test
Find reviews for sushi restaurants in Zip 90025	httphttps://api.citygridmedia.com/content/reviews/v2/search/where?where=90025&what=sushi&publisher=test
Find reviews for sushi restaurants in Zip 90025, ordered by review date, with most recent review first	httphttps://api.citygridmedia.com/content/reviews/v2/search/where?where=90025&what=sushi&sort=createdate&publisher=test
Find reviews for mexican restaurants in West Hollywood posted in the last 90 days	httphttps://api.citygridmedia.com/content/reviews/v2/search/where?where=west+hollywood,ca&what=mexican+restaurant&days=90&publisher=test

Search Using Latitude and Longitude

LatLon

...

HTTPS Endpoint

The following endpoint supports HTTP HTTPS GET:

Code Block
httphttps://api.citygridmedia.com/content/reviews/v2/search/latlon

...

Usage	URL
Find reviews for sushi restaurants around Lat=34.10652 & Lon=-118.411509	httphttps://api.citygridmedia.com/content/reviews/v2/search/latlon?lat=34.10652&lon=-118.411509&radius=10&what=sushi&publisher=test

...

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.
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)
did_you_mean	results		Spelling suggestions if what parameter was provided and not enough results were retrieved.
histograms	results
reviews	results		Collection of all reviews
review	reviews		A single review
business_name	review		The name of the business that the review is for
listing_id	review		The CityGrid Media identifier for the business
reference_id	review		A secondary identifier for the business, used for tracking
review_id	review		The internal CityGrid Media id for the review
impression_id	review		The internal impression id generated for tracking.
review_url	review		The URL of the review (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_author_url	review		The profile link of the author
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) if applicable
source	review		ID of the content provider
attribution_logo	review		Logo of content provider
attribution_text	review		Name of the content provider
attribution_url	review		URL of the content provider
type	review		Type of review (user_review or editorial_review)
helpful_count	review		Count of helpfulness ratings of the review
unhelpful_count	review		Count of unhelpfulness ratings of the review

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

...

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

Code Block

	XML
	XML


<results total_hits="" rpp="" query_id="" page="" last_hit="" first_hit="">
    <uri></uri>
    <did_you_mean></did_you_mean>
    <regions>
        <region type="">
            <name></name>
            <latitude></latitude>
            <longitude></longitude>
            <default_radius></default_radius>
        </region>
    </regions>
    <histograms>
        <histogram name="">
            <items>
                <item count="" name="">
                    <url></url>
                    <tag_ids>
                        <tag_id></tag_id>
                    </tag_ids>
                </item>
            </items>
        </histogram>
    </histograms>
    <reviews>
        <review>
            <review_id></review_id>
            <review_title></review_title>
            <review_text></review_text>
            <pros></pros>
            <cons></cons>
            <review_rating></review_rating>
            <review_author></review_author>
            <helpful_count></helpful_count>
            <unhelpful_count></unhelpful_count>
            <type></type>
            <source></source>
            <attribution_logo></attribution_logo>
            <attribution_text></attribution_text>
            <attribution_url></attribution_url>
            <listing_id></listing_id>
            <business_name></business_name>
            <impression_id></impression_id>
            <review_author_url></review_author_url>
            <review_url></review_url>
        </review>
    </reviews>
</results>

...

The following is an example of a JSON response:

Code Block


{
  "results": {
    "query_id": "",
    "uri": "",
    "first_hit": 1234,
    "last_hit": 1234,
    "total_hits": 1234,
    "page": 1234,
    "rpp": 1234,
    "did_you_mean": "",
    "regions": [
      {
        "type": "",
        "name": "",
        "latitude": 1.0,
        "longitude": -1.0,
        "default_radius": 1.0
      }
    ],
    "histograms": [
  ],
  "reviews": [
    {
       "review_id": "",
       "review_title": "",
       "review_text": "",
       "pros": "",
       "cons": "",
       "review_rating": 1,
       "review_author": "",
       "helpful_count": 1234,
       "unhelpful_count": 1234,
       "type": "editorial_review",
       "source": "",
       "reference_id": "",
       "attribution_logo": "",
       "attribution_text": "",
       "attribution_url": "",
       "listing_id": 1234,
       "business_name": "",
       "impression_id": "",
       "review_author_url": "",
       "review_url": ""
      },
    ]
  },
  "transportableType": null
}

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

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

...

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 did_you_mean element. For example, a query containing what=computr+parts yields:

Code Block

	XML
	XML


<did_you_mean>computer parts</did_you_mean>

...

For example, the following request:

Code Block
httphttps://api.citygridmedia.com/content/reviews/v2/search?rating=pg13&format=plain&publisher=acme

returns the following response:

Code Block

	XML
	XML


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

...

For example, the following request:

Code Block
httphttps://api.citygridmedia.com/content/reviews/v2/search?rating=pg13&format=json&publisher=acme

returns the following response:

Code Block
{ "errors": [ { "error": "where.required" }, { "error": "rating.illegal" } ] }

Recent Reviews (Deprecated)

Recent Reviews

...

HTTPS Endpoint

The following endpoint supports HTTP HTTPS GET:

Code Block
http://api.citygridmedia.com/content/reviews/v2/search

...

Parameter	Description	Required	Valid Values	Default	Examples	Notes
where	The geographic location for the businesses for which you wish to obtain reviews.	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.
what	Search term text.	Yes, unless type, tag, _chain or listing_id _already appear.			pizza sporting%20goods plumbers	The term will be used to search both for businesses related to the term and for reviews containing the term.
tag_id	Category of the businesses for whom you wish to obtain reviews	No	A number.		1722 (for restaurants)	Tag identifiers are obtained from responses from the Search and Profile APIs; you can use these values to find recent reviews for businesses related to your search results or recently viewed listings.
tag_name	Category name of the businesses for which you wish to obtain reviews.	No			restaurants	The list of acceptable tag names is provided separately. Tag names are obtained from responses from the Search and Profile APIs; you can use these values to find recent reviews for businesses related to your search results or recently viewed listings.
publisher	The publisher code that identifies you.	Yes			acme
customer_only	Whether you wish to restrict the results to reviews of CityGrid Media customers.	No	true false	false	true
rating	The minimal rating for the reviews.	No	Positive integer between 1 and 10 inclusive.		4	For example, supplying 4 will restrict the response to reviews with a rating of 4 or better. If this parameter is omitted, the result set will not be filtered by rating.
days	The maximum age in days for the reviews.	No	Positive integer		25	For example, supplying 14 will restrict the results to reviews which have been posted within the last 14 days.
max	The maximum number of results to be returned.	No	Positive integer between 1 and 20 inclusive.	10	6
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			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.
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.

...

Responses in XML format are structured as follows:

Code Block

	XML
	XML


<reviews>
	<review>
		<review_id></review_id>
		<review_title></review_title>
		<review_text></review_text>
		<pros></pros>
		<cons></cons>
		<review_rating></review_rating>
		<review_date></review_date>
		<review_author></review_author>
		<listing_id></listing_id>
		<business_name></business_name>
		<impression_id></impression_id>
		<review_author_url></review_author_url>
		<review_url></review_url>
	</review>
</reviews>
</results>

...

Responses in JSON format are structured as follows:

Code Block


{
  "reviews" : [
    {
      "review_id": ...,
      "review_title": ...,
      "review_text": ...,
      "pros": ...,
      "cons": ...,
      "review_rating" : ...,
      "review_date": ...,
      "review_author": ...,
      "listing_id" : ...,
      "business_name": ...,
      "impression_id": ...,
      "review_author_url": ...,
      "review_url": ...
    }
  ]
}

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

Code Block
callback_name({"reviews": {...}})

...

Versions Compared

Old Version 5

New Version 6

Key

Contents

Audience

Reviews Search

Search Using Where

Where

HTTPS Endpoint

Search Using Latitude and Longitude

LatLon

HTTPS Endpoint

Recent Reviews (Deprecated)

Recent Reviews

HTTPS Endpoint