レビュー
listingsapi-js SDKでレビューの取得、返信、分析を行います。
レビュー（APIでは「interactions」と呼びます）は、Google、Facebook、Yelpから収集した星評価と自由記述のフィードバックです。レビューに関するすべてのメソッドは、ListingsAPIクライアントインスタンスにあります。書き込みがサーバー側で失敗するとValidationErrorがスローされるため、戻り値のsuccessフラグを確認する必要はありません。
fetchInteractions
任意のフィルターとカーソルベースのページネーションを使用して、拠点のレビューを取得します。数値の拠点IDは自動的にエンコードされます。
// Single pageconst result = await client.fetchInteractions(16808, {first: 25,startDate: '2026-01-01',endDate: '2026-06-30',ratingFilters: [1, 2],}); if (!Array.isArray(result)) {console.log(result.interactions); // Interaction[]console.log(result.totalCount); // number | undefinedconsole.log(result.pageInfo); // { hasNextPage, hasPreviousPage, startCursor, endCursor }} // All reviews at once, returns a flat Interaction[]const all = await client.fetchInteractions(16808, {fetchAll: true,startDate: '2026-01-01',});オプション
戻り値
fetchAllを指定しない場合は、success、interactions（Interaction[]）、pageInfo（hasNextPage、hasPreviousPage、startCursor、endCursor）、APIが報告する場合のtotalCount、およびraw（未解析のペイロード）を含むInteractionResponseオブジェクトを返します。fetchAll: trueを指定した場合は、フラットなInteraction[]を返します。各Interactionには、id、content、rating、siteName、siteUrl、reviewerName、publishedAt、category、responsesが含まれます。
fetchReviewDetails
インタラクションIDを指定して、特定のレビューの詳細情報を取得します。入力配列が空の場合は処理を打ち切り、ネットワーク呼び出しを行わずに空のオブジェクトを返します。
const details = await client.fetchReviewDetails(['interaction-uuid-1','interaction-uuid-2',]);respondToReview
レビューへの返信を投稿します。取得元のディレクトリへの配信は非同期で行われます。
await client.respondToReview('interaction-uuid','Thank you for the feedback! We hope to see you again soon.',);editReviewResponse
既存の返信を編集します。
await client.editReviewResponse('review-uuid','response-uuid','Updated response text.',);archiveReviewResponse
返信をアーカイブ（非表示に）します。
await client.archiveReviewResponse('response-uuid');レビュー分析
3つの分析メソッドはいずれも、拠点IDと任意の{ startDate, endDate }の範囲（YYYY-MM-DD）を受け取り、エンドポイントによって構造が異なるReviewAnalyticsオブジェクトを返します。
fetchReviewAnalyticsOverview
指定した期間の全体的な統計として、拠点の評価とレビュー件数の集計を返します。
const overview = await client.fetchReviewAnalyticsOverview(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});console.log(overview);fetchReviewAnalyticsTimeline
グラフ作成に適した、レビュー件数と評価の時系列データです。
const timeline = await client.fetchReviewAnalyticsTimeline(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});fetchReviewAnalyticsSitesStats
取得元サイト（Google、Facebook、Yelp）別のレビューの内訳です。
const siteStats = await client.fetchReviewAnalyticsSitesStats(16808, {startDate: '2026-01-01',endDate: '2026-06-30',});fetchReviewPhrases
指定した期間について、1つ以上の拠点を対象にフレーズ分析と感情分析を行います。単一のオプションオブジェクトを受け取ります。locationIdsは必須で、空のリストを指定すると、ネットワーク呼び出しを行わずに[]を返します。
const phrases = await client.fetchReviewPhrases({locationIds: ['TG9jYXRpb246MTY4MDg=', 'TG9jYXRpb246MTY4MDk='],startDate: '2026-01-01',endDate: '2026-06-30',siteUrls: ['maps.google.com'],}); for (const p of phrases) {console.log(p.phrase, p.count, p.sentiment);}オプション
レビュー設定
fetchReviewSettings
拠点のレビュー取得元の設定を取得します。
const settings = await client.fetchReviewSettings(16808);console.log(settings);editReviewSettings
拠点について追跡するレビュー取得元のURLを設定または更新します。各エントリは、nameとurlを含むReviewSiteUrlです。
await client.editReviewSettings(16808, [{ name: 'Google', url: 'https://www.google.com/maps/place/acme-dental' },{ name: 'Yelp', url: 'https://www.yelp.com/biz/acme-dental-new-york' },]);fetchReviewSiteConfig
アカウント全体で利用可能なレビュー取得元の一覧を取得します。引数は不要で、ReviewSiteConfig[]を返します。
const config = await client.fetchReviewSiteConfig();