리뷰
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가 생략될 수 있으므로 마지막 에지의 cursor를 after로 사용합니다. 두 값은 동일합니다. 예약 실행 시 이력을 다시 읽는 대신 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는 원본 플랫폼에 공개 답글을 게시합니다. 필드는 본문에 직접 넣습니다. 답글은 즉시 접수되고 비동기적으로 전달되므로 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에 값이 채워지므로 본문을 확인해야 하며, 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는 절대 변화량입니다. 403이 SY90003과 함께 반환되면 키로 요청한 사업장 중 하나를 읽을 수 없다는 의미입니다.
사업장의 리뷰 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를 전달합니다. 이를 생략하면 서비스가 자체적으로 기간을 선택합니다. 하나의 소스만 따로 표시하려면 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을 반환할 수도 있으므로 모든 쓰기 작업의 응답 본문을 확인합니다. 전체 목록은 오류 코드에 있습니다.