Listings APIListings API
로그인

Google·Facebook·Bing 프로필 분석 조회

사업장의 Google 및 Facebook 일별 프로필 지표와 Bing 주별 조회수를 가져오고, 월간 시계열 합계를 계산하고, 두 기간을 비교합니다.

프로필 분석 데이터는 각 게시 플랫폼에서 사업장이 얼마나 자주 노출되었고 얼마나 많은 행동으로 이어졌는지를 노출수, 길찾기 요청, 전화 및 웹사이트 클릭으로 보여 줍니다. 모든 지표는 { startTime, value } 데이터 포인트로 구성된 시계열이므로, 표시할 합계는 직접 계산해야 합니다.

1. 날짜 범위의 Google 지표 조회하기

GET /locations/{locationId}/google-analytics?fromDate=&toDate=는 지표마다 하나의 일별 시계열이 포함된 data.googleInsights를 반환합니다. total은 프로필 노출수로, search와 maps를 합한 값이며 행동 지표는 포함하지 않습니다.

Google
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "googleInsights": {      "total": [        { "startTime": "2026-08-01T00:00:00+00:00", "value": 412 },        { "startTime": "2026-08-02T00:00:00+00:00", "value": 388 }      ],      "search": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 300 }],      "maps": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 112 }],      "directionsAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 24 }],      "phoneAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 8 }],      "websiteAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 41 }],      "businessBookings": null,      "businessFoodOrders": null,      "businessFoodMenuClicks": null    }  }}
시계열의미
total노출수로, search와 maps를 합한 값입니다.
search, mapsGoogle Search 및 Google Maps에서의 노출수입니다.
directionsAction, phoneAction, websiteAction길찾기 요청, 전화 클릭, 웹사이트 클릭입니다.
businessBookings, businessFoodOrders, businessFoodMenuClicks해당 기능을 제공하는 프로필의 예약, 음식 주문 및 메뉴 클릭입니다.

형식이 잘못된 사업장 id로 요청하면 googleInsights: null과 errors 배열이 포함된 200이 반환되므로, 연결되지 않은 프로필처럼 보입니다. 먼저 errors를 확인하세요.

2. Facebook 지표 조회하기

GET .../facebook-analytics는 data.facebookInsights 아래에 동일한 구조로 views, ctaAction, directionsAction, phoneAction, websiteAction의 5개 일별 시계열을 포함합니다.

Facebook
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/facebook-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "facebookInsights": {      "views": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 120 }],      "ctaAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 5 }],      "directionsAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 3 }],      "phoneAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 2 }],      "websiteAction": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 9 }]    }  }}

ctaAction은 페이지의 행동 유도 버튼 클릭수를 집계하며, 이를 통해 "지금 예약" 또는 "지금 전화" 캠페인의 성과를 측정합니다. 페이지 좋아요 지표는 없습니다.

3. Bing 조회수 조회하기

GET .../bing-analytics는 일별이 아닌 주별로 묶인 단일 시계열 data.bingInsights.views를 반환합니다. 매주 월요일에 이전 주의 데이터가 갱신되므로, 추세선을 표시하려면 여러 달에 걸친 범위의 데이터를 가져오세요.

Bing
curl "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/bing-analytics?fromDate=2026-06-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY"
JSON
{  "data": {    "bingInsights": {      "views": [        { "startTime": "2026-06-01T00:00:00+00:00", "value": 73 },        { "startTime": "2026-06-08T00:00:00+00:00", "value": 58 }      ]    }  }}

Google 및 Facebook과 달리 Bing은 데이터가 없으면 null 대신 빈 views 배열을 반환합니다. 두 경우 모두 "표시할 내용 없음"으로 처리하세요.

4. 시계열의 월간 합계 계산하기

해당 월의 데이터를 가져온 다음 모든 데이터 포인트의 value를 더합니다. null은 0과 구분해야 합니다. 연결되지 않은 프로필은 트래픽이 없는 달이 아니라 "이용 불가"로 표시해야 합니다. Node SDK의 분석 페이지에도 동일한 sumSeries 헬퍼가 있습니다.

Monthly total
# jq: null when the metric is null, otherwise the sum of valuescurl -s "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY" \| jq '.data.googleInsights | { search: (if .search == null then null else ([.search[].value] | add) end),                               maps: (if .maps == null then null else ([.maps[].value] | add) end) }'

Bing에서는 한 가지를 추가로 확인해야 합니다. 빈 views 배열의 합계는 0이므로, 이 경우에도 "데이터 없음"을 표시하려면 length == 0인지 확인하세요.

5. 두 기간 비교하기

길이가 같은 두 기간의 동일한 지표를 가져오고 두 합계를 사용해 변화를 계산합니다. API에는 프로필 분석을 위한 비교 기능이 내장되어 있지 않으며, delta 필드는 리뷰 분석에만 있습니다.

Two periods
curl -s "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-07-01&toDate=2026-07-31" \-H "Authorization: API $LISTINGSAPI_KEY" | jq '[.data.googleInsights.total[].value] | add' curl -s "https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2026-08-01&toDate=2026-08-31" \-H "Authorization: API $LISTINGSAPI_KEY" | jq '[.data.googleInsights.total[].value] | add'

어느 한 기간이 null인 경우(연결되지 않음), 이전 기간이 0인 경우(0으로 나누기), 아직 진행 중인 기간인 경우의 3가지를 처리해야 합니다. 진행 중인 달의 일부 데이터를 온전한 한 달의 데이터와 비교하면 항상 감소한 것처럼 보이기 때문입니다. 각 호출은 요청 빈도 제한에 포함되므로, 렌더링할 때마다 이전 기간의 데이터를 다시 가져오는 대신 캐시하세요.

다음 단계