列出評論詞句 | Listings API

參數

查詢

名稱	類型	必填	說明	預設值
locationIds	string	選填	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	選填	JSON array of review sources to include, e.g. `["maps.google.com"]`.	—
startDate	string	選填	Only count reviews on or after this date (`YYYY-MM-DD`).	—
endDate	string	選填	Only count reviews on or before this date (`YYYY-MM-DD`).	—
searchString	string	選填	Only return phrases containing this substring.	—
phraseCount	integer	選填	Maximum number of phrases to return.	—
categories	string	選填	JSON array of interaction categories to include (see the interaction attributes reference).	—
ratingFilters	string	選填	JSON array of star ratings to include, e.g. `[1,2]` to mine only unhappy reviews.	—
responseStatus	string	選填	JSON array of `RESPONDED` / `PENDING` to restrict by whether the review has an owner reply.	—
sortOrder	string	選填	One of `NEWEST_FIRST`, `OLDEST_FIRST`, `LAST_RESPONDED`, `LOWEST_RATING`, `HIGHEST_RATING`.	—
category	string	選填	Deprecated single-value form of `categories`. Kept for v4 compatibility; prefer `categories`.	—
ratingFilter	integer	選填	Deprecated single-value form of `ratingFilters`. Kept for v4 compatibility; prefer `ratingFilters`.	—

回應

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`).

傳回某個地點的評論文字中反覆出現的詞句，每個詞句都附有僅針對包含該詞句的評論所計算的統計資料。這可回答「顧客不斷提到哪些內容，而這些提及是正面還是負面的？」。

data.newReviewPhrases 是頂層陣列，不是分頁回應。可用 phraseCount 限制其長度。

每個項目都包含：

reviewPhrase：詞句本身。
phraseStats.stats：與取得互動分析相同的 { name, value, delta } 結構，僅針對包含該詞句的評論計算，並額外包含一個 abs 欄位，用來記錄絕對變化量（而非百分比變化）。

所有篩選條件都是選用的，而且可以組合使用，因此此路由也可用於搜尋評論文字：ratingFilters=[1,2] 搭配 startDate 可取得最近一個月的抱怨內容，並依重複出現的頻率排序。

使用案例：「最常見的抱怨」面板

若要為某個地點建立抱怨面板，請使用 ratingFilters=[1,2]、設為 90 天前的 startDate，以及 phraseCount=10 呼叫此路由。結果會列出低評分評論中最常出現的 10 個詞句。查看每個詞句中 overall-rating 所對應的 phraseStats，可讓您判斷該詞句是否確實異常突出，或只是常用詞彙，而 delta 則表示情況是否正在惡化。

由於查詢值會以 JSON 解析，陣列必須以 JSON 格式放入查詢字串：?ratingFilters=[1,2]&siteUrls=["maps.google.com"]。

上述回應為範例。