List review phrases — Listings API

Parameters

Query

Name	Type	Required	Description	Default
locationIds	string	optional	JSON array of location IDs to aggregate over, e.g. `[1800289,1800290]`. Query values are JSON-parsed, so a bare single ID also works. Omit to cover every location the key can read.	—
siteUrls	string	optional	JSON array of review sources to include, e.g. `["maps.google.com"]`.	—
startDate	string	optional	Only count reviews on or after this date (`YYYY-MM-DD`).	—
endDate	string	optional	Only count reviews on or before this date (`YYYY-MM-DD`).	—
searchString	string	optional	Only return phrases containing this substring.	—
phraseCount	integer	optional	Maximum number of phrases to return.	—
categories	string	optional	JSON array of interaction categories to include (see the interaction attributes reference).	—
ratingFilters	string	optional	JSON array of star ratings to include, e.g. `[1,2]` to mine only unhappy reviews.	—
responseStatus	string	optional	JSON array of `RESPONDED` / `PENDING` to restrict by whether the review has an owner reply.	—
sortOrder	string	optional	One of `NEWEST_FIRST`, `OLDEST_FIRST`, `LAST_RESPONDED`, `LOWEST_RATING`, `HIGHEST_RATING`.	—
category	string	optional	Deprecated single-value form of `categories`. Kept for v4 compatibility; prefer `categories`.	—
ratingFilter	integer	optional	Deprecated single-value form of `ratingFilters`. Kept for v4 compatibility; prefer `ratingFilters`.	—

Responses

200Phrases with their per-phrase review stats. Response key `newReviewPhrases`, a top-level array.

Response

{  "data": {    "newReviewPhrases": [      {        "reviewPhrase": "friendly staff",        "phraseStats": {          "stats": [            { "name": "total-reviews", "value": 46, "delta": 12.5, "abs": 5 },            { "name": "overall-rating", "value": 4.7, "delta": 1.1, "abs": 0.05 }          ]        }      },      {        "reviewPhrase": "long wait",        "phraseStats": {          "stats": [            { "name": "total-reviews", "value": 11, "delta": 37.5, "abs": 3 },            { "name": "overall-rating", "value": 2.9, "delta": -8.4, "abs": -0.27 }          ]        }      }    ]  }}

401Unauthenticated, missing or invalid API key.

403The key is valid but not permitted to read one of the requested locations (`SY90003`).

Returns the recurring phrases in a location's review text, each with the review stats for the subset of reviews that contain it. It answers "what do customers keep mentioning, and are those mentions good or bad?".

data.newReviewPhrases is a top-level array, not a paginated envelope. Use phraseCount to cap its length.

Each entry has:

reviewPhrase: the phrase itself.
phraseStats.stats: the same { name, value, delta } shape as Get interaction analytics, computed over only the reviews containing that phrase, plus an abs field carrying the absolute (rather than percentage) change.

Every filter is optional and they compose, so the route doubles as a text search over reviews: ratingFilters=[1,2] with startDate gives the complaints of the last month, ranked by how often they recur.

Use case: a "top complaints" panel

To build a complaints panel for a location, call this route with ratingFilters=[1,2], a startDate 90 days back, and phraseCount=10. The result is the ten phrases that show up most in low-rated reviews. Reading phraseStats for overall-rating on each one tells you whether a phrase is a genuine outlier or simply common vocabulary, and delta says whether it is getting worse.

Because query values are JSON-parsed, arrays go on the query string in JSON form: ?ratingFilters=[1,2]&siteUrls=["maps.google.com"].

The response example above is constructed from the upstream NewReviewPhraseInfo / InteractionsStats / InteractionStat GraphQL types, not captured from a live call.