리뷰 성과 측정

사업장의 리뷰 KPI를 조회하고, 일별 추이를 차트로 표시하고, 소스를 비교하고, 자주 등장하는 문구를 추출하고, 웹훅으로 일간 및 주간 스냅샷을 받습니다.

서로 관련된 3개의 엔드포인트는 KPI 개요, 일별 추이, 소스별 분석을 통해 사업장의 리뷰를 수치로 보여 줍니다. 4번째 엔드포인트는 고객이 반복해서 사용하는 문구를 나열합니다. 이 엔드포인트들을 함께 사용하면 성과 요약 타일, 추이 차트, 불만 패널을 구성할 수 있습니다.

1. 사업장의 KPI 조회

GET /locations/{locationId}/review-analytics-overview는 data.interactionsAnalyticsStats.stats에 4개의 통계를 반환합니다. 여기서 날짜 범위는 선택 사항이며, 값과 변화량을 계산하는 기간을 좁힙니다.

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으로 보고되므로 첫 달의 변화량을 성장으로 해석하지 않아야 합니다.

2. 차트용 일별 추이 가져오기

GET .../review-analytics-timeline은 data.interactionsChartData.data에 하루당 1개의 항목을 반환합니다. startDate와 endDate를 항상 전달해야 하며, 그렇지 않으면 서비스가 자체적으로 기간을 선택합니다. 하나의 소스만 따로 표시하려면 site(maps.google.com 같은 호스트 이름)를 추가합니다.

curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/review-analytics-timeline?startDate=2026-08-01&endDate=2026-08-31" \-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은 선으로 표시합니다. averageRating은 누적 평균이 아니라 해당 일의 평균이며, 리뷰가 없는 날에는 null이므로 0으로 표시하지 않고 빈 구간으로 남겨 둡니다.

3. 소스별 분석

GET .../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",          "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가 포함됩니다. 다른 소스에는 변화가 없는데 하나의 averageRating.delta만 음수이면 특정 플랫폼에 원인이 있음을 시사하며, 모두 음수이면 매장에 원인이 있음을 시사합니다. newInteractions가 0이고 recency가 몇 달 전이면 일반적으로 소스 연결이 더 이상 정상적으로 작동하지 않는다는 뜻이므로, 사업장의 리뷰 소스 목록 조회를 확인하고 소스가 사라졌다면 리뷰 설정 수정으로 다시 추가합니다.

4. 고객이 사용하는 문구 찾기

GET /review-phrases는 data.newReviewPhrases에 일반 배열을 반환하며, 반복해서 등장하는 문구마다 개요와 동일한 통계 구조의 항목 1개가 포함되고 해당 문구가 들어 있는 리뷰만을 대상으로 계산됩니다. 불만 패널을 구성하려면 ratingFilters=[1,2]를 추가합니다. locationIds와 ratingFilters는 쿼리 문자열에 포함된 JSON 배열이므로 URL 인코딩해야 하며, SDK가 이를 자동으로 처리합니다.

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": "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는 변화율과 함께 제공되는 절대 변화량입니다. SDK의 문구 메서드는 ratingFilters나 phraseCount를 노출하지 않으므로, 이 항목들이 필요하면 REST 호출을 사용합니다.

5. 웹훅으로 일간 및 주간 스냅샷 받기

웹훅 URL이 설정되어 있으면 review_analytics.daily_snapshot과 review_analytics.weekly_snapshot은 사업장별로 기간당 1번 발생합니다. 각각을 고정된 기간에 대해 계산한 개요 엔드포인트의 결과로 해석합니다. 해당 기간의 total_reviews는 total-reviews이고, new_reviews_in_period는 new-reviews이며, average_rating은 overall-rating이고, 직전 기간에 대한 previous_average_rating이 함께 제공됩니다. 답글 작성률, 일별 추이, 소스별 분석은 페이로드에 포함되지 않으므로, 필요하면 이벤트가 도착했을 때 위의 엔드포인트를 호출합니다.

{  "event": "review_analytics.weekly_snapshot",  "timestamp": "2026-08-24T02:00:00Z",  "account_id": 11073,  "location_id": "279381",  "data": {    "period": "2026-08-17",    "granularity": "weekly",    "total_reviews": 1237,    "new_reviews_in_period": 18,    "average_rating": 4.6123,    "previous_average_rating": 4.5901  }}

이 이벤트 그룹의 규모는 사업장 수에 비례합니다. 사업장이 400개이면 일간 이벤트 400개가 한꺼번에 발생하며, 요금제의 분당 한도를 초과하는 이벤트는 대기열에 들어가지 않고 삭제됩니다. 따라서 스냅샷이 누락되면 그 원인을 판단할 수 없습니다. 누락된 스냅샷을 절대로 0으로 기록하지 말고, 대신 해당 기간의 개요를 다시 조회합니다. 설정 방법은 웹훅으로 이벤트에 대응하기에 나와 있습니다.

다음 단계

• 리뷰에 답글 작성하기: 대기 중인 리뷰에 답글을 작성하여 review-response-rate를 높입니다.
• 프로필 분석 데이터 가져오기: 동일한 사업장의 Google, Facebook, Bing 조회수, 검색 수 및 액션 수를 가져옵니다.
• 참조: 상호작용 분석 조회, 타임라인, 사이트별, 리뷰 문구 목록 조회.
• SDK: Python 리뷰, Node 리뷰.