분석
listingsapi-js SDK로 Google, Bing, Facebook 프로필 분석 데이터를 가져옵니다.
분석 메서드는 Google Business Profile, Bing Places, Facebook Pages에서 검색 노출 수, 클릭 수, 길찾기 요청 수, 전화 통화 수 등의 플랫폼별 통계를 조회합니다. 모든 분석 메서드는 ListingsAPI 클라이언트 인스턴스에서 직접 제공되며, 조회 범위는 사업장 ID로 지정합니다. 숫자형 사업장 ID는 자동으로 인코딩되므로 16808과 'TG9jYXRpb246MTY4MDg='를 서로 바꾸어 사용할 수 있습니다.
3개 메서드는 모두 사업장 ID와 선택 사항인 { fromDate, toDate } 범위를 받는 동일한 시그니처를 사용합니다. 두 날짜는 각각 또는 모두 생략할 수 있으며, 모두 생략하면 플랫폼의 기본 보고 기간을 사용합니다.
모든 지표는 시계열입니다
이 페이로드에는 스칼라 합계가 없습니다. 각 지표는 일별(Bing의 경우 주별) { startTime, value } 데이터 포인트의 배열이며, 데이터가 없는 지표는 0나 []이 아닌 null입니다. 따라서 시계열의 합계는 직접 계산하고, "데이터 없음"과 "0"을 구분해야 합니다:
type Point = { startTime: string; value: number | null }; // null when the metric is absent, so an empty profile never reads as 0.function sumSeries(series: Point[] | null | undefined): number | null {if (!Array.isArray(series)) return null;return series.reduce((acc, p) => acc + (p.value ?? 0), 0);} function show(label: string, series: Point[] | null | undefined) {const total = sumSeries(series);console.log(label, total === null ? 'unavailable' : total);}fetchGoogleAnalytics
사업장의 Google Business Profile 통계를 조회합니다.
const google = await client.fetchGoogleAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Impressions (total)', google.total);show('Search impressions', google.search);show('Maps impressions', google.maps);show('Website clicks', google.websiteAction);옵션
페이로드는 googleInsights 객체이며, 객체의 모든 키는 { startTime, value }[] 시계열입니다: total, search, maps, websiteAction, directionsAction, phoneAction, businessBookings, businessFoodOrders, businessFoodMenuClicks. total은 프로필 노출 수로, search와 maps의 합계이며 행동 지표는 포함하지 않습니다. Google에 데이터가 없는 시계열은 모두 null로 반환됩니다. 전체 필드 설명은 사업장의 Google 분석 데이터 조회를 참조하세요.
fetchBingAnalytics
사업장의 Bing Places 통계를 조회합니다.
const bing = await client.fetchBingAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Bing views', bing.views);Bing은 단일 지표인 views을 일별이 아닌 주별로 집계하여 보고합니다.
옵션
fetchFacebookAnalytics
사업장의 Facebook 페이지 통계를 조회합니다.
const facebook = await client.fetchFacebookAnalytics(16808, {fromDate: '2024-01-01',toDate: '2024-12-31',}); show('Page views', facebook.views);show('CTA clicks', facebook.ctaAction);Facebook 페이로드에는 views, ctaAction, websiteAction, directionsAction, phoneAction가 포함됩니다. pageLikes는 없습니다.
옵션
여러 플랫폼의 보고서
Promise.all를 사용하여 3개 플랫폼의 데이터를 모두 병렬로 조회합니다:
import { ListingsAPI } from 'listingsapi-js'; const client = new ListingsAPI(); // reads LISTINGSAPI_KEY from envconst LOCATION_ID = 16808;const range = { fromDate: '2024-01-01', toDate: '2024-12-31' }; const [google, bing, facebook] = await Promise.all([client.fetchGoogleAnalytics(LOCATION_ID, range),client.fetchBingAnalytics(LOCATION_ID, range),client.fetchFacebookAnalytics(LOCATION_ID, range),]); show('Google impressions:', google.total);show('Bing views:', bing.views);show('Facebook views:', facebook.views);특정 플랫폼에 프로필이 연결되어 있지 않으면 메서드는 Promise를 거부하지 않고 빈 객체로 이행하며, 개별 시계열은 null로 반환됩니다. 이 경우 ??를 사용하여 0으로 변환하지 말고 "사용 불가"로 표시해야 하며, 그렇지 않으면 연결되지 않은 프로필이 대시보드에서 실제 값이 0인 것처럼 표시됩니다. 요청 실패 시에는 여전히 SDK에 정의된 타입별 오류가 발생합니다.