Reviews Source Reference| Hitchhikers Platform

On the Reviews Source, each record is an individual review. This source is useful if you want to, for example, fetch reviews from the Content API to publish in a consumer-facing experience like a website or mobile app.

Filter

The only supported filter for Reviews is Publisher. There are 4 accepted values for the publisher filter:

  • googlemybusiness
  • facebook
  • firstparty
  • externalfirstparty

The Content API includes any reviews which match the publisher criteria, and also the following criteria:

  • Review Status = LIVE (excluding QUARANTINED & REMOVED reviews)

Fields

The Review object has a predefined data model. The following fields are available from the Reviews source.

Field Type Description
reviewId integer The ID of the review. This ID is generated by Yext and is globally unique. It is not editable by users.

This ID is the primary key for the reviews source, meaning you can use this ID for a Get by ID API request on a Content Endpoint with the Reviews Source.
entity Object (reference) This field is used to reference data from the entity which the review is for. Using dot notation, a user can specify fields from the entity to include on the review document, for example, entity.name.
publisher string The publisher which the review is associated with.
authorName string The name of the person who wrote the review.
content string The content of the review.
reviewUrl string The public URL where the review can be found
rating number Normalized rating out of 5.
reviewDate date-time The date the review was posted, according to the publisher.

Note: certain publishers update the reviewDate when a review is updated by the reviewer.
lastYextUpdateDate date-time The most recent of the reviewDate and the date of the last response.
reviewLabels Array of reviewLabels objects An object containing information about the labels on the review
comments Array of comments objects An object containing information about the responses for the review.
apiIdentifier string A unique identifier for this review. This value is determined in the following manner:
  • A UUID generated at the time the Review Creation request is accepted
  • The invitationUid, if the review is associated with an invitation.

reviewLabels object

Field Type Description
uid integer The UID of the specific reviewLabel object.
name string The name of the label.

comments object

Field Type Description
commentId integer The unique ID of the comment.
commentDate date-time The date the comment was posted.
authorName string The name of the author who wrote the comment.
content string The content of the comment.

Example - Fetching Reviews Using Data Projected from Linked Entities

Another important use case solved by the Content API is the ability to fetch reviews data while filtering on data from the relevant entity. The Reviews data source consists of a single record per review; each review has a reference to an entity (using the Entity UID) which can be traversed to project data from that linked entity onto the review output record.

For example, imagine you were building a Landing Page for each state for a given business, and you wanted to display reviews for the locations in that state. You would want to make a client-side call on that page to fetch reviews, and filter on the relevant entity field (“region” in this case) to only the reviews for the relevant entities for my specific page.

First, you would define the relevant Content Endpoint.

{
  "$id": "reviewsByState",
  "$schema": "https://schema.yext.com/config/streams/streams-api/v1",
  "name": "Reviews API by State",
  “stream”: {
        "source": “reviews”,
        "filter": {
              "publishers": [“firstparty”]
         },
        "fields": [
          "rating",
          "content",
          "reviewDate",
          "comments",
          "entity.id",
          "entity.name",
          "entity.address"
        ]
   },
  "fieldIndexes": [
    {"field": "entity.address"},
    {"field": "entity.id"}
  ]
}

As previously noted, we want to pull from the Reviews source, since we are interested in receiving individual reviews. We filter down to First Party reviews, since we want to publish these reviews on the page.

By using dot notation on the entity, we can access the fields from the entity which the review is for. We then index the address field, so that we can query on the address.region field to get all reviews for entities in a specific region. We might also want to index the entity.id field, so that we can use this same endpoint to fetch reviews for a specific entity; this scenario would be relevant if we were also publishing these reviews on individual landing pages per entity.

Say you want to query reviews on entities located in New York. You would use the following query, passing a query parameter for entity.address.region=NY.

Example Request:

GET https://streams.yext.com/v2/accounts/me/api/reviewsByState?api_key={api_key}&v=20200408&entity.address.region=NY

Example Response:

{
   "response":{
      "docs":[
         {
            "reviewId": 1234,
            "reviewDate": "2021-02-01T05:00:00Z",
            "rating": 5,
            "content": “I love this restaurant. Wonderful service!”,
            "entity": {
                "id": "entity1",
                "name": "The Froggy Fog",
                "address":{
                   "city":"New york",
                   "countryCode":"US",
                   "line1":"1 Madison ave",
                   "postalCode":"10010",
                   "region":"NY"
                }
            }
         },
         {
            "reviewId": 12345,
            "reviewDate": "2021-03-01T05:00:00Z",
            "rating": 4,
            "content": “This restaurant is pretty good but the service is not amazing”,
            "entity": {
                "id": "entity2",
                "name": "The Foggy Dog",
                "address":{
                   "city":"New york",
                   "countryCode":"US",
                   "Line1":"61 Ninth ave",
                   "postalCode":"10010",
                   "region":"NY"
                }
            }
         }
      ]
   }
}
Feedback