Reviews API

Introduction

The CityGrid Reviews API enables developers to create applications that find and display customer reviews about a particular subject or location. Examples of applications that may use the Reviews API include:

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.

Version 2 Updates

The following are the updates made from Version 1 of the Reviews API:

Changes to search requests:
- Added query parameter i (impression_id).
- For where and latlonendpoints:
  - Added point-radius search.
  - Removed tag_name parameter.
  - Renamed tag_id parameter to tag.
  - Renamed max parameter to rpp.
  - Added listing_id parameter.
  - Added review_type parameter.
Changes to responses:
- Added impression_id.
- review_date is now in ISO 8601 format.
- review_rating is now only returned if there is a value — "NA" is no longer returned.
- Added Google's Protocol Buffers as format option.
- For where and latlonendpoints:
  - Wrapped entire output in <results> element with uri, did_you_mean, regions, and histograms elements.
  - Added type.
  - Added source.
  - Moved attribution_source to the source element.
  - Added attribution_url.
  - Added sort.
Changes to error codes:
- Added review_type.illegal.
- Added sort.illegal.
- Removed rating.out.of.range — If a supplied value is out of range, it is ignored.
- Removed max.out.of.range — If a supplied value is out of range, the default value is used.
- Removed format.unacceptable — If a supplied value is not one of the expected values, the response will be returned in XML.

Reviews Search

Search Using Where

Where HTTPS Endpoint

The following endpoint supports HTTPS GET:

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

Where Request

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

Parameter	Description	Required	Valid Values	Default	Examples	Notes
where	The geographic region 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	Only if tag and listing_id are absent			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	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 Places and Places Search APIs; you can use these values to find recent reviews for businesses related to your search results or recently viewed listings.
listing_id	The id of the place whose reviews you would like	No			1234567	If you specify listing_id, do not specify what, where, or tag.
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.
rpp	The maximum number of results to be returned.	No	Positive integer between 1 and 50 inclusive	20	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	For 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 short for "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.
review_type	A filter to only return a certain type of review	No	editorial_review user_review external_user_review		editorial_review
sort	An optional property to order the reviews	No	createdate reviewRating		createdate	The createdate sort option sorts by the date in descending order (newer first) the review was written. The reviewRating sort option sorts reviews by rating, descending

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

Where 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 reviews for sushi restaurants in Los Angeles	https://api.citygridmedia.com/content/reviews/v2/search/where?where=los%20angeles,ca&what=sushi&publisher=test
Find reviews for sushi restaurants in Zip 90025	https://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	https://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	https://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 HTTPS GET:

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

LatLon Request

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

Parameter	Description	Required	Valid Values	Default	Examples	Notes
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
radius	Radius of a circle search	Yes	Positive number between 1 and 50 inclusive.	5	7.5	If larger than 50 it defaults to 50.
what	Search term text	Only if tag and listing_id are absent			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	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 Places and Places Search APIs; you can use these values to find recent reviews for businesses related to your search results or recently viewed listings.
listing_id	The id of the place whose reviews you would like	No			1234567	If you specify listing_id, do not specify what, lat, lon, or tag.
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.
rpp	The maximum number of results to be returned.	No	Positive integer between 1 and 50 inclusive	20	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	For 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 short for "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.
review_type	A filter to only return a certain type of review	No	editorial_review user_review external_user_review		editorial_review
sort	An optional property to order the reviews	No	createdate reviewRating		createdate	The createdate sort option sorts by the date in descending order (newer first) the review was written. The reviewRating sort option sorts reviews by rating, descending

LatLon 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 reviews for sushi restaurants around Lat=34.10652 & Lon=-118.411509	https://api.citygridmedia.com/content/reviews/v2/search/latlon?lat=34.10652&lon=-118.411509&radius=10&what=sushi&publisher=test

Note: For more details on how to use geographies, see the Specifying the Geography section in the Places API topic.

Search Response

The Reviews 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.
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

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

XML Response

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

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

JSON Response

The following is an example of a JSON response:

{
  "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:

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

<did_you_mean>computer parts</did_you_mean>

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 “restaurants” around Portland, OR, will return items such as "Date Spot", "Organic", "Sea Food", etc.

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.

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
publisher.required	The publisher parameter is missing
rating.illegal	The rating is not a number or is otherwise malformed
tag_id.illegal	The tag value is not a number or is otherwise malformed
days.illegal	The days value is not a number
max.illegal	The max value is not a number
geography.not.found	The requested geography is unknown
tag.overspecified	Both tag and what are specified (only one is permitted)
where.required	A geography specification is missing
customer_only.illegal	The customer_only parameter was something other than true or false
internal.error	An internal problem with the service has occurred
review_type.illegal	The review_type specified is unknown
sort.illegal	The sort option specified is unknown

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/reviews/v2/search?rating=pg13&format=plain&publisher=acme

returns the following response:

<?xml version="1.0" encoding="UTF-8"?>
<errors>
    <error>rating.illegal</error>
    <error>where.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/reviews/v2/search?rating=pg13&format=json&publisher=acme

returns the following response:

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

Recent Reviews (Deprecated)

Recent Reviews HTTPS Endpoint

The following endpoint supports HTTPS GET:

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

This Endpoint is Deprecated

This V2 endpoint will continue to work, but we encourage you to migrate your code to the where and latlon endpoints for higher performance and functionality.

Recent Reviews Request

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

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.

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

Recent Reviews 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 default number of recent reviews in Los Angeles	http://api.citygridmedia.com/content/reviews/v2/search?where=los+angeles,ca&publisher=test
Find recent reviews of restaurants in Boston	http://api.citygridmedia.com/content/reviews/v2/search?where=boston,ma&tag_name=restaurant&publisher=test
Find recent reviews in Detroit having a rating of at least 2	http://api.citygridmedia.com/content/reviews/v2/search?where=detroit,mi&rating=2&publisher=test
Find recent reviews related to fish in Detroit	http://api.citygridmedia.com/content/reviews/v2/search?what=fish&where=detroit,mi&publisher=test
Find at most 5 recent reviews related to fish in Detroit	http://api.citygridmedia.com/content/reviews/v2/search?what=fish&where=detroit,mi&max=5&publisher=test
Find reviews for tapas in zipcode 90069, that are no more than 7 days old, using a placement value of "homepage", in JSON format with a callback of "scroll"	http://api.citygridmedia.com/content/reviews/v2/search?what=tapas&where=90069&days=7&placement=homepage&format=json&callback=scroll&publisher=test

Recent Reviews Response

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

The following table describes the return elements:

Element	Parent Element	Attributes	Description
reviews			Collection of all reviews
review	reviews	attribution_source - Unique identifier of the review provider attribution_logo - The URL for the logo of the review provider (typically an 88 x 33 jpeg) attribution_text - Name of the review provider, to be displayed in place of, or along side of, the attribution logo	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
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

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

XML Response

Responses in XML format are structured as follows:

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

JSON Response

Responses in JSON format are structured as follows:

{
  "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:

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

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 for the deprecated Recent Reviews endpoint, 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.

CityGrid V2

Reviews API

Introduction

Contents

Audience

Version 2 Updates

Reviews Search

Search Using Where

Where HTTPS Endpoint

Where Request

Where Usage Examples

Search Using Latitude and Longitude

LatLon HTTPS Endpoint

LatLon Request

LatLon Usage Examples

Search Response

XML Response

JSON Response

Protocol Buffers Response

Spelling Suggestions

Histograms

Error Reporting

Error Codes

XML Error Response

JSON Error Response

Recent Reviews (Deprecated)

Recent Reviews HTTPS Endpoint

Recent Reviews Request

Recent Reviews Usage Examples

Recent Reviews Response

XML Response

JSON Response

Protocol Buffers Response