Listings APIListings API
登录

分析

每个资料数据分析端点均附有 cURL、Python 和 Node 示例：提供地点的 Google 和 Facebook 每日指标，以及 Bing 每周浏览量。

资料数据分析显示地点在各发布平台上的曝光和用户操作频次：展示次数、页面浏览量、路线请求次数、通话次数和网站点击次数。共有 3 个端点，每个发布平台各有 1 个，且全部为读取操作，因此使用 Read（读取）密钥即可。每项指标都是由 { startTime, value } 数据点组成的时间序列；API 不返回标量总计，因此您展示的总和需要自行计算。

端点概览

方法路径功能参考
GET/locations/{locationId}/google-analytics9 个 Google Business Profile 每日时间序列。Google 数据分析
GET/locations/{locationId}/facebook-analytics5 个 Facebook 公共主页每日时间序列。Facebook 数据分析
GET/locations/{locationId}/bing-analytics1 个 Bing Places 每周时间序列。Bing 数据分析

这 3 个端点使用相同的参数。fromDate 和 toDate 均为 YYYY-MM-DD，且均为可选参数；省略时将使用发布平台默认的近期时间范围。路径接受 base64 Relay id 或纯数字。如果值不属于这两种格式中的任何一种，端点会返回 200，其中 insights 对象被设为 null，并附带一个 errors 数组，这与资料未连接时的结果相似，因此请先检查 errors。

读取指定日期范围内的 Google 指标

GET /locations/{locationId}/google-analytics 返回 data.googleInsights，其中每项指标都有一个每日时间序列。total 表示资料展示次数，即 search 与 maps 之和；它不包含用户操作指标。您可以用它生成数据变更前后的曝光情况对比报告。

名称位置是否必填说明
locationIdpath是Base64 Relay id 或数字形式的 databaseId。
fromDatequery否范围的起始日期，格式为 YYYY-MM-DD。默认使用近期时间范围。
toDatequery否范围的结束日期，格式为 YYYY-MM-DD。
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": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }],      "businessFoodOrders": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }],      "businessFoodMenuClicks": [{ "startTime": "2026-08-01T00:00:00+00:00", "value": 0 }]    }  }}

每个数据点的 startTime 表示该计数归属的日期。在示例中，第 1 天的 total 为 412，即 300 次 search 加上 112 次 maps。

时间序列含义
total资料展示次数，即 search 与 maps 之和。
searchGoogle Search结果中的展示次数，合计桌面端和移动端数据。
mapsGoogle Maps结果中的展示次数，合计桌面端和移动端数据。
directionsAction前往该地点的路线请求次数。
phoneAction通话按钮的点击次数。
websiteAction点击跳转至网站的次数。
businessBookings从资料发起的预订次数。
businessFoodOrders通过资料提交的餐饮订单数。
businessFoodMenuClicks餐饮菜单链接的点击次数。

如果地点在该时间范围内没有 Google 数据，或其 Google 资料未连接，指标将为 null，而不是空数组。汇总时，请以相同方式处理 null 和 []。

读取指定日期范围内的 Facebook 指标

GET /locations/{locationId}/facebook-analytics 在 data.facebookInsights 下采用相同的数据结构，包含 5 个每日时间序列。它要求地点的 Facebook 公共主页已连接。您可以使用 ctaAction 衡量营销活动期间“立即预订”或“立即致电”按钮的表现。

名称位置是否必填说明
locationIdpath是Base64 Relay id 或数字形式的 databaseId。
fromDatequery否范围的起始日期，格式为 YYYY-MM-DD。默认使用近期时间范围。
toDatequery否范围的结束日期，格式为 YYYY-MM-DD。
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 }]    }  }}
时间序列含义
views公共主页总浏览量。
ctaAction公共主页行动号召按钮的点击次数。
directionsAction通过公共主页发起的路线请求次数。
phoneAction从公共主页发起的通话次数。
websiteAction从公共主页点击跳转至网站的次数。

没有公共主页点赞数指标。如果公共主页在该范围内没有数据或未连接，每个时间序列都会返回 null，因此请在遍历前检查是否为 null。

读取指定日期范围内的 Bing 浏览量

GET /locations/{locationId}/bing-analytics 返回单个序列 data.bingInsights.views，按周而非按天分组。每个数据点表示从 startTime 开始的一周的浏览量。数据每周一刷新，提供前一周的数据，因此您能看到的最新数据是最近一个完整周的数据。若要绘制趋势线，请获取跨越多个月的日期范围；此数据不适合用于按天归因。

名称位置是否必填说明
locationIdpath是Base64 Relay id 或数字形式的 databaseId。
fromDatequery否范围的起始日期，格式为 YYYY-MM-DD。默认使用近期时间范围。
toDatequery否范围的结束日期，格式为 YYYY-MM-DD。
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 }      ]    }  }}
序列含义
viewsBing Places 资料浏览量，每周一个数据点。

与 Google 和 Facebook 不同，Bing 在没有数据时返回空的 views 数组和 200，而非 null。请将这两种情况都视为“没有可显示的内容”；如果您希望显示“无数据”标签，请检查 length == 0，因为空数组求和的结果为 0。

您会遇到的错误

参考页面未列出任何分析资源专用的错误代码。您会遇到以下情况：

代码含义解决方法
401，同时包含 SY90001API 密钥缺失或无效。发送 Authorization: API $LISTINGSAPI_KEY。
200，其中 googleInsights、facebookInsights 或 bingInsights 设为 null，并包含 errors 数组locationId 既不是数字，也不是可解码的 Relay id。传入读取端点返回的 base64 id。请勿对其做 URL 编码。
200，同时包含值为 null 的指标（Google、Facebook）或空的 views 数组（Bing），且不包含 errors该时间窗口内没有数据，或者尚未连接发布平台。显示“不可用”，而非零。请连接相应账号。
429速率限制。等待 Retry-After。请参阅速率限制。

完整列表见错误代码。

后续步骤