レビューのパフォーマンスを測定する

拠点のレビューのKPIを取得し、日別の推移をグラフにし、ソースを比較し、よく使われるフレーズを抽出し、日次および週次のスナップショットをWebhookで受信します。

3つの関連エンドポイントが、拠点のレビューを数値で示します。内容は、KPIの概要、日別の推移、ソース別の内訳です。4つ目のエンドポイントは、顧客が繰り返し使うフレーズを一覧で返します。これらを組み合わせることで、スコアカードのタイル、トレンドグラフ、苦情パネルに必要な情報がそろいます。

1. 拠点のKPIを取得する

GET /locations/{locationId}/review-analytics-overviewは、data.interactionsAnalyticsStats.statsに4つの統計値を返します。このエンドポイントでは日付範囲の指定は任意で、指定すると値と差分の計算対象期間を絞り込めます。

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-overview?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsAnalyticsStats": {      "stats": [        { "name": "total-reviews", "value": 128, "delta": 6.67 },        { "name": "new-reviews", "value": 9, "delta": -25 },        { "name": "overall-rating", "value": 4.43, "delta": 2.31 },        { "name": "review-response-rate", "value": 62.5, "delta": 12.5 }      ]    }  }}

比較対象となる前の期間がない新規アカウントでは、deltaが100と報告されるため、最初の月の差分を成長と解釈しないでください。

2. グラフ用に日別の推移を取得する

GET .../review-analytics-timelineは、data.interactionsChartData.dataに1日につき1件のエントリを返します。startDateとendDateを必ず渡してください。指定しない場合、サービスが独自に期間を選択します。1つのソースだけをグラフにするには、site（maps.google.comなどのホスト名）を追加してください。

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-timeline?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsChartData": {      "data": [        { "date": "2026-08-01", "interactionCount": 4, "averageRating": 4.5 },        { "date": "2026-08-02", "interactionCount": 0, "averageRating": null },        { "date": "2026-08-03", "interactionCount": 7, "averageRating": 4.285714285714286 }      ]    }  }}

interactionCountを棒グラフ、averageRatingを折れ線グラフとして描画してください。averageRatingは累積平均ではなくその日の平均で、レビューがない日はnullになるため、ゼロを描画せずに空白を残してください。

3. ソース別の内訳を取得する

GET .../review-analytics-sites-statsは、data.interactionsSitesStats.statsにレビューソースごとに1件のエントリを返します。どのプラットフォームが平均値を変動させたかを確認するために使用してください。

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-sites-stats?startDate=2026-08-01&endDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsSitesStats": {      "stats": [        {          "key": "google",          "siteUrl": "maps.google.com",          "averageRating": { "value": 4.6, "delta": 2.2 },          "totalInteractions": { "value": 412, "delta": 6.1 },          "newInteractions": { "value": 24, "delta": 33.3 },          "recency": "2026-09-06T14:12:00Z",          "humanizedRecency": "3 days ago"        },        {          "key": "facebook",          "siteUrl": "facebook.com",          "averageRating": { "value": 4.1, "delta": -1.4 },          "newInteractions": { "value": 0, "delta": -100 },          "recency": null,          "humanizedRecency": null        }      ]    }  }}

averageRating、totalInteractions、newInteractionsには、それぞれvalueとdeltaが含まれます。他が横ばいで1つのaverageRating.deltaだけがマイナスの場合はそのプラットフォームに、すべてがマイナスの場合は店舗に原因があることを示唆します。newInteractionsが0で、recencyが数か月前の場合、通常はソースへの接続が有効でなくなっていることを意味するため、拠点のレビューソースを一覧表示するで確認し、ソースがなくなっていればレビュー設定を編集するで再追加してください。

4. 顧客が使うフレーズを見つける

GET /review-phrasesは、data.newReviewPhrasesに通常の配列を返します。繰り返し使われるフレーズごとに1件のエントリがあり、各エントリの統計は概要と同じ構造で、そのフレーズを含むレビューのみを対象に計算されます。苦情パネルにはratingFilters=[1,2]を追加してください。locationIdsとratingFiltersはクエリ文字列内のJSON配列なので、URLエンコードが必要です。SDKではこれが自動的に行われます。

curl -G "https://listingsapi.com/api/v4/review-phrases" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'locationIds=[1800289]' \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'startDate=2026-06-01' \--data-urlencode 'endDate=2026-08-31' \--data-urlencode 'phraseCount=10'

{  "data": {    "newReviewPhrases": [      {        "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 }          ]        }      }    ]  }}

total-reviewsはフレーズの出現頻度を、overall-ratingはそれらのレビューが好意的かどうかを、deltaは状況が悪化しているかどうかを示します。absは、変化率とともに示される絶対量での変化です。SDKのフレーズ用メソッドではratingFiltersやphraseCountを指定できないため、これらが必要な場合はREST呼び出しを使用してください。

5. 日次および週次のスナップショットをWebhookで受信する

WebhookのURLを設定すると、review_analytics.daily_snapshotとreview_analytics.weekly_snapshotが、拠点ごとに各期間に1回発生します。それぞれを、固定期間について計算された概要エンドポイントの結果として読み取ってください。その期間について、total_reviewsはtotal-reviews、new_reviews_in_periodはnew-reviews、average_ratingはoverall-ratingに相当し、直前の期間に対するprevious_average_ratingが含まれます。返信率、日別の推移、ソース別の内訳はペイロードに含まれないため、必要な場合はイベントの到着時に上記のエンドポイントを呼び出してください。

{  "event": "review_analytics.weekly_snapshot",  "timestamp": "2026-08-24T02:00:00Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "period": "2026-08-17",    "granularity": "weekly",    "total_reviews": 1237,    "new_reviews_in_period": 18,    "average_rating": 4.6123,    "previous_average_rating": 4.5901  }}

この一連のイベントの件数は拠点数に比例し、400拠点では日次イベントが400件まとめて発生します。プランの1分あたりの上限を超えたイベントはキューに入らず、破棄されます。そのため、スナップショットが欠落していても、その原因は判別できません。欠落をゼロとして記録せず、必ずその期間の概要を再取得してください。設定方法はWebhookでイベントに対応するを参照してください。

次の手順

• レビューに返信する: 保留中のキューにあるレビューに返信して、review-response-rateを高めます。
• プロフィール分析データを取得する: 同じ拠点について、Google、Facebook、Bingでの閲覧数、検索数、アクション数を取得します。
• リファレンス: インタラクション分析データを取得する、タイムライン、サイト別、レビューのフレーズを一覧表示する。
• SDK: Pythonのレビュー、Nodeのレビュー。