Skip to end of metadata
Go to start of metadata

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.

Contents

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:

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

Icon

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.

Search Using Latitude and Longitude

LatLon HTTPS Endpoint

The following endpoint supports HTTPS GET:

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.

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

Icon

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.

JSON Response

The following is an example of a JSON response:

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

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:

Histograms

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

Histograms Optional

Icon

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.

Icon

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:

returns the following response:

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:

returns the following response:

Recent Reviews (Deprecated)

Recent Reviews HTTPS Endpoint

The following endpoint supports HTTPS GET:

This Endpoint is Deprecated

Icon

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.

Icon

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

Icon

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:

JSON Response

Responses in JSON format are structured as follows:

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

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.

  • No labels