分析
使用 listingsapi-js SDK 获取 Google、Bing 和 Facebook 的商家资料分析数据。
分析方法从 Google Business Profile、Bing Places 和 Facebook Pages 获取平台级统计数据，例如搜索展示次数、点击次数、路线请求次数和来电次数。所有分析方法都直接位于 ListingsAPI 客户端实例上，并以地点 ID 为作用范围。数字形式的地点 ID 会自动编码，因此 16808 和 'TG9jYXRpb246MTY4MDg=' 可以互换使用。
这 3 个方法的签名相同：一个地点 ID，加上可选的 { fromDate, toDate } 范围。两个日期均为可选项，可以单独省略，也可以同时省略；省略它们即可使用平台默认的报告时间范围。
每个指标都是时间序列
这些响应数据中没有标量形式的总计值。每个指标都是一个由 { 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，按周而非按天汇总。
选项
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 中定义的错误类型。