ReviewsAgg Source Reference| Hitchhikers Platform

On the ReviewsAgg Source, there is a record for each Reviews Aggregate Data Object (average star rating and review count); this data exists at the level of the entity-publisher pair. This source is useful if you want to, for example, display average rating and/or review count in a consumer-facing experience like a website or mobile app.

Filter

The only supported filter for ReviewsAgg is Publisher. There are four accepted values for the publisher filter:

• googlemybusiness
• facebook
• firstparty
• externalfirstparty

Fields

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

Example - Fetching Reviews Aggregate Data Using Data Projected from Linked Entities

Similar to the Reviews case above, another common use case is to fetch the Reviews Aggregate Data, which consists of the Average Rating and Review Count, for a given entity on a specific publisher. In the example above, we wanted individual reviews for all of the locations in a specific state.

In this example, we’ll imagine that we want to fetch the Reviews Aggregate Data for locations in a specific state. We might want the Average Rating and Review Count across a few publishers: First Party, Facebook, and Google, to display the complete picture of the reputation of the entity in question. The ReviewsAgg Data Source produces one record per entity-publisher pair, so you can imagine that there would be separate objects returned by the API for the combination of entity1-googlemybusiness and entity1-facebook; this format is somewhat intuitive, since the aggregate data is necessarily going to vary based on the publisher.

Again, we’ll start with defining the relevant Content Endpoint:

{
  "$id": "reviewsAggByState",
  "$schema": "https://schema.yext.com/config/streams/streams-api/v1",
  "name": "Reviews Aggregate Data API by State",
  “stream”: {
        "source": “reviewsAgg”,
        "filter": {
              "publishers": [“firstparty”, “googlemybusiness”, “facebook”]
         },
        "fields": [
          "reviewCount",
          "averageRating",
          "publisher",
          "entity.id",
          "entity.name",
          "entity.address"
        ]
   },
  "fieldIndexes": [
    {"field": "entity.address"},
    {"field": "entity.id"}
  ]
}

As mentioned above, since we are interested in receiving the Reviews Aggregate Data records, we’ll set our source as “reviewsAgg”.

We’ll filter down based on publisher to the three aforementioned publishers, so that any reviewsAgg records which refer to these publishers will come through the Content Endpoint.

We will include the reviewCount, averageRating, and publisher fields from the reviewsAgg source, and we’ll project some entity data, including the Entity ID, Entity Name, and Entity Address.

We will then index the Entity’s Address to ensure we can filter to only entities within a specific region. We will also index the Entity ID, in case we want to use this same API to fetch Reviews Agg data for individual entities.

Say you want to query this Content Endpoint for Reviews Aggregate Data 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/reviewsAggByState?api_key={api_key}&v=20200408&entity.address.region=NY

Example Response:

{
   "response":{
      "docs":[
         {
            "reviewCount": 12,
            "averageRating": 4.32,
            "publisher": googlemybusiness,
            "entity": {
                "id": "entity1",
                "name": "The Froggy Fog",
                "address":{
                   "city":"New york",
                   "countryCode":"US",
                   "line1":"1 Madison ave",
                   "postalCode":"10010",
                   "region":"NY"
                }
            }
         },
         {
            "reviewCount": 22,
            "averageRating": 4.12,
            "publisher": facebook,
            "entity": {
                "id": "entity1",
                "name": "The Froggy Fog",
                "address":{
                   "city":"New york",
                   "countryCode":"US",
                   "line1":"1 Madison ave",
                   "postalCode":"10010",
                   "region":"NY"
                }
            }
         },
         {
            "reviewCount": 32,
            "averageRating": 4.83,
            "publisher": firstparty,
            "entity": {
                "id": "entity1",
                "name": "The Froggy Fog",
                "address":{
                   "city":"New york",
                   "countryCode":"US",
                   "line1":"1 Madison ave",
                   "postalCode":"10010",
                   "region":"NY"
                }
            }
         }
      ]
   }
}

In the example response above, only one entity is returned, which would mean there was only one entity with reviews on the specified publishers where region=NY. However, if there were more entities, there would be additional objects in the response for each entity-publisher pair.