Reviews Source | Yext 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 four 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.

reviewLabels object

comments object

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://cdn.yextapis.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"
                }
            }
         }
      ]
   }
}