レビュー

すべてのレビューエンドポイントにcURL、Python、Nodeのサンプルを掲載しています。ソースと設定、一覧、集約、詳細、返信、編集、アーカイブ、フレーズ、分析を扱います。

レビューは、顧客がGoogle、Facebook、Yelpに投稿する星評価とコメントです。APIは各レビューのコピーを1件ずつ保存し、返信機能を提供し、レビュー分析を行います。RESTのパスではreviewsを使用しますが、レスポンスのキーとリファレンスページのタイトルでは、同じオブジェクトの旧内部名であるinteractionsを使用します。このガイドでは、一貫してレビューと呼びます。読み取りにはRead（読み取り）キーが必要です。返信、編集、アーカイブ、設定変更にはWrite（書き込み）キーが必要です。Readキーで書き込みを行うと、SY90016を伴う400が返されます。

エンドポイント一覧

プランで利用できるレビューソースの一覧を取得する

GET /reviews/site-configは、アカウントで利用が認められているレビュープラットフォームのカタログを返します。パラメーターは不要で、アカウント単位の情報を返すため、拠点ごとに呼び出すのではなくキャッシュしてください。siteUrlの値は、このリソースのほかのすべてのフィルターで使用できるホスト名です。

curl https://listingsapi.com/api/v4/reviews/site-config \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionSiteConfig": [      { "site": "Google", "siteUrl": "maps.google.com" },      { "site": "Facebook", "siteUrl": "facebook.com" },      { "site": "Yelp", "siteUrl": "yelp.com" }    ]  }}

data.interactionSiteConfig[]を確認してください。この例はLaunchプランのアカウントのもので、具体的な内容はプランと業種によって異なります。一覧エンドポイントのsiteUrlsフィルターと、設定を編集する際のsiteUrls[].nameには、siteUrlを使用してください。

拠点に設定されているソースの一覧を取得する

GET /locations/{locationId}/reviews/settingsは、プランでサポートされているプラットフォームごとに1件のエントリを、レビューの取得元URLとともに返します。これは、後述の編集エンドポイントに対応する読み取り用エンドポイントです。パスにはbase64 idまたは通常の数値を指定できます。

curl https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews/settings \-H "Authorization: API $LISTINGSAPI_KEY"

{  "data": {    "interactionsSetting": {      "siteSettings": [        { "name": "maps.google.com", "url": null },        { "name": "facebook.com", "url": null },        { "name": "yelp.com", "url": null }      ]    }  }}

data.interactionsSetting.siteSettings[]を確認してください。urlがnullでなければ、そのプラットフォームが接続されており、そのページからレビューが取得されていることを意味します。urlがnullであれば、そのプラットフォームは利用可能ですが、未設定であることを意味します。GoogleとFacebookは、OAuthでそれぞれのアカウントを接続すると自動的に設定され、編集エンドポイントでは上書きできません。Yelpは明示的に指定する必要があります。

拠点のレビュー設定を編集する

POST /locations/reviews/settings/editは、拠点について監視するソースと、肯定的と判定する星評価を設定します。フィールドはinputでラップせず、リクエストボディに直接指定します。ソースを追加するとスクレイピングがキューに登録されるため、新しいサイトのレビューはこのレスポンスには含まれず、後から取り込まれます。

curl -X POST https://listingsapi.com/api/v4/locations/reviews/settings/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "locationId": "TG9jYXRpb246MTgwMDI4OQ==",  "positiveInteractionThreshold": 4,  "siteUrls": [    { "name": "maps.google.com", "url": null },    { "name": "yelp.com", "url": "https://www.yelp.com/biz/blue-bottle-coffee-oakland" }  ]}'

{  "data": {    "editInteractionsSetting": {      "errors": null,      "interactionSetting": {        "locationId": "1800289",        "positiveInteractionThreshold": 4,        "siteSettings": [          { "name": "maps.google.com", "url": null, "monitored": true, "canRespond": true },          { "name": "yelp.com", "url": "https://www.yelp.com/biz/blue-bottle-coffee-oakland", "monitored": true, "canRespond": false }        ]      }    }  }}

保存されている選択内容はdata.editInteractionsSetting.interactionSetting.siteSettings[]で確認してください。monitoredはソースが有効であることを示し、canRespondはAPIを通じてそのソースにオーナーの返信を投稿できるかどうかを示します。到達できないURLやプランの対象外のサイトなど、検証で拒否されたソースは、設定が変更されないままerrorsに含まれて返されるため、200の場合はerrorsを確認してください。その場合、SDKはValidationErrorを送出します。

拠点のレビューを一覧表示する

GET /locations/{locationId}/reviewsは、data.interactionsにカーソル方式のコネクションを返し、結果は新しい順に並びます。firstのデフォルトは20のため、1回の呼び出しで履歴全体を取得することはできません。配列フィルターはクエリ文字列内のJSON文字列であり、URLエンコードが必要です。cURLのサンプルでは、そのために-Gと--data-urlencodeを使用しています。

これらに加えて、リファレンスページに記載されている任意のcategory、categories、および単一値のratingFilterも使用できます。

curl -G "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'ratingFilters=[1,2]' \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=25'

{  "data": {    "interactions": {      "pageInfo": { "hasNextPage": true, "endCursor": "SW50ZXJhY3Rpb246MV8xNTU0..." },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "nice place for family together",            "authorName": "vaibhav nakate",            "rating": 5,            "date": "2019-04-02T22:11:13.036997+00:00",            "type": "Review",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..."        }      ],      "totalCount": 425    }  }}

edges[].nodeを読み取ります。idは返信時に渡す値で、canRespondはそのソースがオーナーからの返信を受け付けるかどうかを示します。totalCountは、このページ内ではなく、結果セット全体で一致した件数です。hasNextPageがfalseになった場合、またはページが空のedgesを返した場合はページングを終了します。境界が最も古いレビューと一致する場合、その次に空のページが1つ返されます。

集約エンドポイントで全拠点のレビューを取得する

GET /rollup_interactionsは、キーで参照できるすべての拠点を対象とする同じカーソル方式のコネクションで、data.rollupInteractionsにあり、各ノードに数値のlocationIdが含まれます。拠点ごとの一覧と同じフィルターを受け付けます。拠点フィルターはなく、locationIds引数は拒否されずに無視されます。どちらのSDKもまだこのエンドポイントのラッパーを提供していないため、サンプルではrequestsとfetchを使用しています。

curl -G "https://listingsapi.com/api/v4/rollup_interactions" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'responseStatus=["PENDING"]' \--data-urlencode 'sortOrder=["NEWEST_FIRST"]' \--data-urlencode 'first=50'

{  "data": {    "rollupInteractions": {      "pageInfo": { "hasNextPage": true, "hasPreviousPage": false },      "edges": [        {          "node": {            "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",            "source": "maps.google.com",            "content": "Excellent service, highly recommend.",            "rating": 5,            "responded": false,            "canRespond": true,            "locationId": 1800289          },          "cursor": "SW50ZXJhY3Rpb246OWUyNmQyYTg="        }      ],      "totalCount": 1284    }  }}

店舗のdatabaseIdであるlocationIdでノードをグループ化します。集約結果のpageInfoにはendCursorが含まれない場合があるため、最後のedgeのcursorをafterとして使用します。これら2つの値は同等です。スケジュール実行では、履歴を再取得する代わりにstartDateとendDateで範囲を制限し、429の場合はRetry-Afterに従います。

idでレビューを取得する

GET /reviewDetailsは、保存されているレビューの最新のコピーをページングなしで返します。レスポンスはdata.interactionDetails.interactionsにある通常の配列で、edgesやpageInfoはなく、各レビューにはそのresponsesが含まれます。ウォッチリストのデータを再取得したり、編集やアーカイブに必要なresponseIdを見つけたりする際に使用します。

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["b2fa765e-c62b-4e0b-b1d6-1c67c855f5e0"]'

{  "data": {    "interactionDetails": {      "interactions": [        {          "id": "b2fa765e-c62b-4e0b-b1d6-1c67c855f5e0",          "source": "maps.google.com",          "content": "Great place for dessert!",          "rating": 5,          "responded": true,          "responseCount": 1,          "canRespond": true,          "responses": [            {              "id": "2090753a-ece6-4837-8336-8494ad308523",              "content": "Thank you so much for the kind words!",              "interactionStatus": "CONFIRMED",              "editedResponse": false            }          ]        }      ]    }  }}

responses[].idは、編集およびアーカイブのエンドポイントで使用するresponseIdです。別のアカウントのidを指定すると、interactionDetails: nullとSY90001エラーを含む200が返されるため、インデックスでアクセスする前にnullを確認します。

レビューと返信のフィールド

属性リファレンスは、レビューオブジェクトと返信オブジェクトのすべてのフィールドを一覧にした、ドキュメント専用のページです。特によく使用するフィールドは次のとおりです：

responses[]内の各返信には、id、content、authorName、date、interactionStatus、editedResponse、respondedWith（テンプレートid）、およびremarks（失敗の詳細）が含まれます。interactionStatusは次の状態を遷移します：

オーナーからの返信を投稿する

POST /locations/reviews/respondは元のプラットフォームに公開返信を投稿します。各フィールドはbodyに直接指定します。返信は即座に受け付けられ、非同期で配信されるため、interactionStatusはCREATEDから始まります。まず、レビューのcanRespondを確認してください。

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseContent": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!"}'

{  "data": {    "respondToInteraction": {      "interaction": {        "id": "2090753a-ece6-4837-8336-8494ad308523",        "interactionId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",        "content": "Thank you for visiting Jenny Home: we are glad you enjoyed your experience!",        "interactionStatus": "CREATED",        "editedResponse": false      },      "errors": null    }  }}

interaction.idは編集とアーカイブに使用するresponseIdなので、保存しておいてください。拒否された返信は200として返され、data.respondToInteraction内のerrorsに値が設定されるため、bodyを確認してください。SDKはValidationErrorを送出します。少し待ってからidでレビューを再取得し、返信がCOMPLETEDまたはCONFIRMEDになったことを確認してください。

返信を編集する

POST /locations/reviews/respond/editは既存の返信の本文を変更します。編集内容はプラットフォームに再送信されるため、interactionStatusはCREATEDに戻り、反映されるとeditedResponseがtrueになります。返信が1件のみ許可されるプラットフォームでは、アーカイブして再投稿するよりも、この方法を優先してください。

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/edit \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{  "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",  "responseId": "2090753a-ece6-4837-8336-8494ad308523",  "responseContent": "Thank you again: we have updated our reply to include our new store hours."}'

{  "data": {    "editResponse": {      "status": "true",      "reviewId": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",      "responseId": "2090753a-ece6-4837-8336-8494ad308523"    }  }}

編集が受け付けられると、statusは文字列"true"になります。詳細取得の呼び出しで新しい文面を確認し、返信のinteractionStatusを確認してください。

返信をアーカイブする

POST /locations/reviews/respond/archiveは、当サービス側で追跡しているレビューのresponsesから返信を削除します。これは論理削除であり、Google、Yelp、Facebookですでに公開されている返信は、そのまま残ります。失敗した下書きや別の下書きに置き換えられた下書きを削除する場合に使用し、公開済みの返信には編集を使用してください。

curl -X POST https://listingsapi.com/api/v4/locations/reviews/respond/archive \-H "Authorization: API $LISTINGSAPI_KEY" \-H "Content-Type: application/json" \-d '{ "responseId": "2090753a-ece6-4837-8336-8494ad308523" }'

{  "data": {    "archiveResponse": {      "status": "true"    }  }}

アーカイブすると、レビューのresponseCountが減少し、respondedに残りの返信が反映されます。

顧客が繰り返し使うフレーズを一覧表示する

GET /review-phrasesはdata.newReviewPhrasesに通常の配列を返し、繰り返し使われるフレーズごとに1つのエントリが含まれ、各エントリにはそのフレーズを含むレビューのみを対象に算出された統計が含まれます。ページネーションはないため、phraseCountで上限を設定してください。すべてのフィルターは任意で、組み合わせて使用できるため、ratingFilters=[1,2]とstartDateを指定すると、前四半期の苦情を取得できます。

このほか、リファレンスページに記載されている任意のcategoriesと、非推奨の単一値パラメーターcategoryおよびratingFilterも使用できます。

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": "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 }          ]        }      }    ]  }}

total-reviewsはフレーズの出現頻度、overall-ratingはそのフレーズを含むレビューの平均評価、deltaは前期間からの変化率、absは実数での変化量です。SY90003を伴う403は、リクエストした拠点のいずれかをキーで読み取れないことを意味します。

拠点のレビューKPIを取得する

GET /locations/{locationId}/review-analytics-overviewはdata.interactionsAnalyticsStats.statsに4つの統計値を返します。日付範囲は任意で、指定すると値とその変化量の算出対象期間を絞り込めます。各deltaは、同じ長さの前期間からの変化率です。

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として報告されるため、最初の月の変化量を成長と解釈しないでください。

日別のレビュータイムラインを取得する

GET /locations/{locationId}/review-analytics-timeline は、data.interactionsChartData.data に日ごとに1件のエントリを返します。グラフの対象期間を指定する必要がある場合は、必ず startDate と endDate を渡してください。省略すると、サービスが独自に期間を選択します。1つのソースだけを描画するには、site を追加してください。

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-timeline?startDate=2026-08-01&endDate=2026-08-31&site=maps.google.com" \-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 を折れ線グラフとして描画してください。平均値はその日のみの値で、累積平均ではありません。また、レビューがない日は null になるため、0を描画するのではなく空白にしてください。

レビュー分析をソース別に分類する

GET /locations/{locationId}/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",          "baseRating": 4.5,          "baseInteractions": 388,          "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 が含まれます。baseRating と baseInteractions は、差分の測定基準となる期間の開始時点の値です。recency は最新のレビューのタイムスタンプで、そのソースがレビューを一度も返していない場合は null です。newInteractions が 0 で、recency が数か月前の場合、通常はソース接続が更新されなくなっていることを意味するため、拠点のソースを確認してください。

発生するエラー

書き込みでは、data.<op> 内の errors に値が設定された状態で 200 が返される場合もあるため、すべての書き込みでレスポンスボディを確認してください。完全な一覧は エラーコード にあります。

次の手順

• レビューを取得する: 対応待ちのキューを作成し、Webhook で通知を受け取ります。
• レビューに返信する: 返信、確認、編集、アーカイブを行います。
• レビュー分析: スコアカード、グラフ、苦情パネル、日次スナップショットを利用します。
• 分析: 同じ拠点の Google、Facebook、Bing のプロフィール指標を確認します。
• リファレンスのトップページ: レビュー。SDK: Python のレビュー、Node のレビュー。