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
- 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. |
title | string | Title of the review. This value is omitted if review on the publisher's site does not have title. |
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 date the review was last updated. |
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. WARNING: Including the apiIdentifier field in your stream creates a security risk as an unauthorized user can access the value and use it to modify a first party review that is not their own. |
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://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"
}
}
}
]
}
}