1つの拠点またはアカウント全体のレビューを取得する

拠点の最新レビューを一覧表示し、未返信の低評価レビューに絞り込み、カーソルでページを順に取得し、アカウント全体を巡回して、Webhookで通知を受け取ります。

APIでは、レビューを「インタラクション」と呼びます。Google、Facebook、Yelpのすべてのレビューは、拠点ごとに1つのリストとして、またアカウント全体では1つの集約結果として返されるため、1つの連携ですべての接続済みソースをカバーできます。

1. 1つの拠点の最新レビューを一覧表示する

GET /locations/{locationId}/reviewsは、data.interactionsにあるカーソルベースのコネクションです。結果は新しい順に返され、firstのデフォルト値は20なので、1回の呼び出しで履歴全体が返されることはありません。パスにはbase64のIDまたは通常の数値を指定できます。

Latest reviews

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

JSON

{  "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",            "responded": false,            "responseCount": 0,            "canRespond": true,            "permalink": "https://maps.google.com/maps?cid=..."          },          "cursor": "SW50ZXJhY3Rpb246MV8xNTU0..."        }      ],      "totalCount": 425    }  }}

data.interactions.edges[].nodeを読み取ります。idはbase64のRelay IDではなく通常のUUIDで、返信時に渡す値です。totalCountは、このページではなく結果セット全体で条件に一致する件数です。canRespondは、そのソースがAPI経由のオーナー返信を受け付けるかどうかを示します。

配列フィルターはクエリ文字列内のJSON文字列です。ratingFilters=[1,2]は星1つと星2つのレビューに絞り込み、responseStatus=["PENDING"]はオーナーの返信がないレビューに絞り込みます。角括弧と引用符はURLエンコードする必要があるため、cURLのサンプルでは-Gと--data-urlencodeを組み合わせて使用し、各値を自動的にエンコードしてURLに追加します。同等のクエリ文字列を直接記述すると、ratingFilters=%5B1%2C2%5D&responseStatus=%5B%22PENDING%22%5Dになります。

Unanswered 1-2 stars

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=50'

組み合わせて使用できるフィルターは次のとおりです。

パラメーター	値	注記
`siteUrls`	`["maps.google.com"]`, `["facebook.com"]`, `["yelp.com"]`	アカウントのレビューソースを一覧表示するで取得したホスト名です。
`ratingFilters`	`[1,2]`など	取得対象の星評価です。
`responseStatus`	`["PENDING"]`または`["RESPONDED"]`	オーナーの返信が存在するかどうかです。
`sortOrder`	`["NEWEST_FIRST"]`, `["OLDEST_FIRST"]`, `["LAST_RESPONDED"]`	デフォルトは新しい順です。
`startDate`, `endDate`	`YYYY-MM-DD`	JSONではなく通常の文字列です。
`searchString`	自由形式のテキスト	レビュー本文を全文検索します。

3. カーソルでページを順に取得する

pageInfo.endCursorをafterとして次のリクエストに渡します。hasNextPageがfalseになった場合、またはページが空のedges配列を返した場合は、取得を終了します。ページの境界が最も古いレビューと一致すると、その次に空のページが1つ返されます。どちらのSDKでも、ページを自動的に読み取れます。

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/reviews?first=50&after=SW50ZXJhY3Rpb246MV8xNTU0..." \-H "Authorization: API $LISTINGSAPI_KEY"

各リクエストはレート制限の対象としてカウントされ、レビューが425件ある拠点をfirst=50で取得するには9回の呼び出しが必要です。429が返された場合は、Retry-Afterを待ってから次のページを取得します。定期的な同期では、履歴を再度読み取る代わりに、startDateとendDateで取得範囲を制限します。レート制限をご覧ください。

4. 集約結果でアカウント全体を巡回する

GET /rollup_interactionsは、キーで参照できるすべての拠点にわたる同じ形式のノードをdata.rollupInteractionsに返し、各ノードにはlocationIdが含まれます。同じフィルターに加えてtagを指定でき、そのデフォルト値はallです。拠点フィルターはないため、locationIdによるグループ化はクライアント側で行ってください。どちらのSDKもまだこのエンドポイントをラップしていないため、SDKのサンプルではrequestsとfetchを使用して呼び出します。

Account-wide pending

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'

各ノードは手順1と同じ構造で、店舗のdatabaseIdである数値のlocationIdが追加されています。集約結果のpageInfoにはendCursorが含まれない場合があるため、最後のエッジのcursorをafterとして使用してください。この2つの値は同等です。

5. IDで詳細情報をすべて取得する

保存済みのIDがある場合、GET /reviewDetailsはページを順に取得せずに最新のデータを返します。interactionIdsはJSON配列で、他のフィルターと同様にURLエンコードします。レスポンスはdata.interactionDetails.interactionsにある通常の配列で、各interactionにはそのresponsesが含まれます。

Details by id

curl -G "https://listingsapi.com/api/v4/reviewDetails" \-H "Authorization: API $LISTINGSAPI_KEY" \--data-urlencode 'interactionIds=["9e26d2a8-a6ed-42ea-8454-47d1c92ea841"]'

JSON

{  "data": {    "interactionDetails": {      "interactions": [        {          "id": "9e26d2a8-a6ed-42ea-8454-47d1c92ea841",          "responded": true,          "responseCount": 1,          "responses": [            {              "id": "2090753a-ece6-4837-8336-8494ad308523",              "content": "Thank you so much for the kind words!",              "interactionStatus": "CONFIRMED"            }          ]        }      ]    }  }}

別のアカウントのIDを指定すると、interactionDetails: nullとSY90001エラーを伴う200が返されるため、インデックスでアクセスする前にnullを確認してください。

6. ポーリングの代わりにWebhookイベントを受信する

Webhook URLを設定すると、レビューが取り込まれるか変更されたときにinteraction.reviewイベントが発生します。レビューのフィールドはdataの直下ではなくdata.interactionの下にあり、data.interaction.idは一覧で返されるものと同じUUIDです。

注意点は2つあります。このイベントのlocation_idは正規化されずに渡されるため、数値文字列またはnullの場合があります。そのため、型をそのまま信頼せず、受信側で変換してください。また、レビューが変更されるたびに同じidが再び届くため、このイベントは1回限りの挿入としてではなく、レビューを再取得するきっかけとして扱ってください。配信は1回のみで再試行されないため、取りこぼしに備えて手順4の定期的な確認を継続してください。設定方法はWebhookでイベントに対応するに記載されています。

次の手順

レビューに返信する：先ほど見つけた未対応のレビューに返信し、その後で返信を編集またはアーカイブします。
レビュー分析：同じ拠点の評価、レビュー数、返信率を確認します。
リファレンス：インタラクションの一覧を取得する、集計インタラクションを取得する、IDでインタラクションを取得する、インタラクションの属性。
SDK：Pythonのレビュー、Nodeのレビュー。