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 latlon endpoints:
    • 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 latlon endpoints:
    • 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 HTTP Endpoint

The following endpoint supports HTTP GET:

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

Where Request

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

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

The following endpoint supports HTTP GET:

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

LatLon Request

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

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:

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:

XML Error Response

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

For example, the following request:

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

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

The following endpoint supports HTTP 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:

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.

Recent Reviews Response

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

The following table describes the return elements:

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.