XML Schema

This section desribes the XML schema used for the merchant review data feed.

Top-level element: <feed>

Description

The top-most container element that holds all other elements in the feed.

Attributes

Name Format Occurrences Description
xmlns xs:string Required (1) Please hardcode the following value:
http://schemas.google.com/merchant_reviews/5.0
xmlns:xsi xs:string Required (1) Please hardcode the following value:
http://www.w3.org/2001/XMLSchema-instance
xsi:schemaLocation xs:string Required (1) Please hardcode the following value, leaving a single blank space between URLs:
http://schemas.google.com/merchant_reviews/5.0 http://www.gstatic.com/productsearch/static/reviews/5.0/merchant_reviews.xsd

Example

<feed xmlns="http://schemas.google.com/merchant_reviews/5.0"
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
      xsi:schemaLocation="http://schemas.google.com/merchant_reviews/5.0 https://www.gstatic.com/productsearch/static/reviews/5.0/merchant_reviews.xsd">

Contains

Name Format Occurrences Description
merchants       -- Optional (0‑1) Container element for <merchant> elements.
deleted_merchants       -- Optional (0‑1) Container element for <deleted_merchant> elements.
reviews       -- Optional (0‑1) Container element for <review> elements.
deleted_reviews       -- Optional (0‑1) Container element for <deleted_review> elements.

<merchants>

Description

Container for <merchant> elements.

Contains

Name Format Occurrences Description
merchant       -- Required (1‑n) Element repeated for each merchant.

<merchant>

Description

Each <merchant> element contains information and reviews for one merchant.

Attributes

Name Format Occurrences Description
id Id Required (1) Must be unique and stable across all feeds. In other words, if a feed today and a feed 90 days ago refer to the same merchant, they must have the same id.

Example

<merchant id="2739">

Contains

Please include the following elements within the merchant element.

Name Format Occurrences Description
name NonEmptyString Required (1) Human-readable display name for the merchant.
merchant_url xs:anyURI Required (1) URL to the merchant's main website.
Do not use a redirect URL for this value. In other words, the value should point directly to the merchant's site.

Example: 

<merchant_url>
  http://store.google.com
</merchant_url>
rating_url xs:anyURI Required (1) URL to the landing page that hosts the reviews for this merchant.
Do not use a redirect URL.

Example: 

<rating_url>
  http://merchant_url.com/reviews/
</rating_url>
create_timestamp DateTimeWithTimeZone Required (1) Time/date the merchant was created. This should never change.
last_update_timestamp DateTimeWithTimeZone Required (1) Time/date the merchant was last updated. If any of the fields in the <merchant> element are updated for a given merchant ID, this value must also change.

<deleted_merchants>

Description

Container for merchants which were deleted.

Contains

Name Format Occurrences Description
deleted_merchant       -- Required (1‑n) Contains element(s) related to a single deleted merchant.

<deleted_merchant>

Description

Merchant which was deleted.

Attributes

Name Format Occurrences Description
id Id Required (1) Specifies the ID of a merchant that should be deleted from the feed. The ID must match the id attribute of a <merchant> element in any previous feed file.

Contains

Name Format Occurrences Description
last_update_timestamp DateTimeWithTimeZone Required (1) Time/date when a merchant was removed from the system.

Example: 

<last_update_timestamp>
  2016-04-03T18:37:32Z
</last_update_timestamp>

Example

<deleted_merchant id="10">
  <last_update_timestamp>2014-07-12T07:55:06Z</last_update_timestamp>
</deleted_merchant>

<reviews>

Description

Container for <review> elements.

Contains

Name Format Occurrences Description
review       -- Required (1‑n) Element repeated for each review.

<review>

Description

Container for details related to a review.

Attributes

Name Format Occurrences Description
id Id Required (1) The identifier for a review in your system. Must be unique and stable across all feeds.

Example: 

<review id=132739 mid=1234>
mid Id Required (1) The identifier of the merchant this review is for.

Contains

Please include the following elements within the review element.

Name Format Occurrences Description
reviewer_name NonEmptyString Optional (0‑1) Display name of the author of the review, provided the review should have a named author. Anonymous reviews should not include this field.

Example: 

<reviewer_name>
  Joel
</reviewer_name>
create_timestamp DateTimeWithTimeZone Required (1) Time/date the review was submitted by the user. This should never change.

Example: 

<create_timestamp>
  2016-04-03T18:37:32Z
</create_timestamp>
last_update_timestamp DateTimeWithTimeZone Required (1) Time/date the information in the <review> element last changed. If any of the fields in the <review> element are updated for a given review ID, this value must also change.

Example: 

<last_update_timestamp>
  2016-04-03T18:37:32Z
</last_update_timestamp>
country_code CountryCode Required (1) Country of the reviewer. If available, this is the country the product was shipped to or where the service was rendered. Otherwise, use country the reviewer is in at the point of creating the review. The country code must be in ISO 3166-1 alpha-2 format.

Example: 

  <country_code>
    US
  </country_code>
title xs:string Optional (0‑1) The title of the review. The title should be plain text without any HTML tags in it.

Example: 

  <title>
    Great prices
  </title>
content xs:string Required (1) The content of the review. This should be any freeform text provided by the user and should not be truncated. The content should be plain text without any HTML tags in it. For example a line break should be represented by a line feed character, not a <br> tag. If multiple responses to different questions are provided, all responses should be included, with the minimal context for the responses to make sense. Context should not be provided if questions were left unanswered.

Example: 

  <content>
    I like this store!
    My order arrived on time and I got
    a great price.
  </content>

Example: 

  <content>
    Positives: Great prices.
    Suggestions: Selection could be better.
  </content>
ratings           -- Required (1) Container element for the reviewer's ratings of the merchant. If no rating is available for the <overall> element, then the entire associated review should be excluded from the feed because the <overall> element is required and the review will not be accepted without it.
collection_method CollectionMethodType Required (1) The method that was used to collect the review. The value must be one of the following:
  • unsolicited: The user was not responding to a specific solicitation when they submitted the review.
  • point_of_sale: The user submitted the review in response to a solicitation when the user placed an order.
  • after_fulfillment: The user submitted the review in response to a solicitation after fulfillment of the user's order.

Example: 

  <collection_method>
    after_fulfillment
  </collection_method>

<ratings>

Description

Contains the reviewer's ratings of the merchant. If no rating is available for the <overall> element, then the entire associated review should be excluded from the feed because the <overall> element is required and the review will not be accepted without it.

Contains

Please include the following elements within the ratings element.

Name Format Occurrences Description
overall RatingRange Required (1) Reviewer’s overall rating for a merchant.

Example: 

  <overall min="1" max="10">9</overall>
customer_service RatingRange Optional (0‑1) Reviewer’s rating of the customer service quality for this merchant.

Example: 

  <customer_service min="1" max="5">3</customer_service>

<deleted_reviews>

Description

Container for reviews which were deleted.

Contains

Name Format Occurrences Description
deleted_review       -- Required (1‑n) Contains element(s) related to a single deleted review.

<deleted_review>

Description

Review which was deleted.

Attributes

Name Format Occurrences Description
id Id Required (1) Specifies the ID of a review that should be deleted from the feed. The ID must match the id attribute of a <review> element in any feed file.

Contains

Name Format Occurrences Description
last_update_timestamp DateTimeWithTimeZone Required (1) Time at which a review was removed from the system.

Example: 

  <last_update_timestamp>
    2016-04-03T18:37:32Z
  </last_update_timestamp>

Example

<deleted_review id="10">
  <last_update_timestamp>2014-07-12T07:55:06Z<last_update_timestamp>
</deleted_review>