리뷰
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
지정한 날짜 범위에 대해 하나 이상의 사업장에서 수집한 리뷰의 구문과 감정을 분석합니다. 단일 옵션 객체를 받으며, 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();