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, maps在 Google Search 和 Google Maps中的展示次数。
directionsAction, phoneAction, websiteAction路线请求次数、通话点击次数、网站点击次数。
businessBookings, businessFoodOrders, businessFoodMenuClicks预订次数、餐饮订单数和菜单点击次数，适用于提供这些功能的商家资料。

如果地点 id 格式不正确，则会返回 200，其中包含 googleInsights: null 和一个 errors 数组，看起来与未连接的商家资料相似。请先检查 errors。

2. 读取 Facebook 指标

GET .../facebook-analytics 在 data.facebookInsights 下采用相同的结构，包含 5 个每日序列：views、ctaAction、directionsAction、phoneAction 和 websiteAction。

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 在没有数据时返回空的 views 数组，而不是 null。请将这两种情况都视为“无内容可显示”。

4. 将序列求和，得到月度总计

获取该月的数据，然后将每个数据点的 value 相加。请区分 null 和零：未连接的商家资料必须显示为“不可用”，不能显示为该月没有流量。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'

请处理 3 种情况：任一时段为 null（未连接）、较早时段为 0（除以零），以及日期范围尚未结束，因为将不完整月份与完整月份比较时，看起来总是有所下降。每次调用都会计入您的速率限制，因此请缓存较早时段的数据，避免在每次渲染时重新获取。

后续步骤