分析
使用 listingsapi-js SDK 取得 Google、Bing 和 Facebook 的商家檔案分析資料。
分析方法可從 Google Business Profile、Bing Places 和 Facebook Pages 取得平台層級的數據，例如搜尋曝光次數、點擊次數、路線查詢次數和來電次數。所有分析方法都直接定義在 ListingsAPI 用戶端實例上，且查詢範圍皆限定於指定的地點 ID。數字格式的地點 ID 會自動編碼，因此 16808 和 'TG9jYXRpb246MTY4MDg=' 可以互換使用。
這 3 個方法的簽章皆相同：地點 ID 加上選填的 { fromDate, toDate } 範圍。這 2 個日期都不是必填，可省略其中一個或同時省略；若兩者皆省略，則使用平台預設的報表期間。
每個指標都是時間序列
這些回傳資料不包含純量形式的總計。每個指標都是由 { startTime, value } 資料點組成的陣列，每天一筆（Bing 為每週一筆），而沒有資料的指標會是 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 這 1 個指標，並以每週而非每日為單位彙整。
選項
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，否則未連接的商家檔案會在您的儀表板中顯示為實際的零值。請求失敗時，仍會擲回 SDK 中對應型別的錯誤。