获取地点的 Google 分析数据

参数

路径

名称	类型	必填	描述
locationId	string	必填	Location ID, either the Base64 Relay id (e.g. TG9jYXRpb246MTgwMDI4OQ==) or the raw numeric database id (e.g. 1800289). Both forms resolve to the same location.

查询

名称	类型	必填	描述	默认值
fromDate	string	可选	Start of the range (YYYY-MM-DD). Defaults to a recent window when omitted.	—
toDate	string	可选	End of the range (YYYY-MM-DD).	—

响应

200Daily Google interaction metrics. Each metric is a time-series array; a metric is `null` when no data exists for the range or the profile is not connected.

Response

{  "data": {    "googleInsights": {      "total": [        { "startTime": "2025-06-01T00:00:00+00:00", "value": 412 },        { "startTime": "2025-06-02T00:00:00+00:00", "value": 388 }      ],      "search": [        { "startTime": "2025-06-01T00:00:00+00:00", "value": 300 }      ],      "maps": [        { "startTime": "2025-06-01T00:00:00+00:00", "value": 112 }      ],      "directionsAction": [        { "startTime": "2025-06-01T00:00:00+00:00", "value": 24 }      ],      "phoneAction": [        { "startTime": "2025-06-01T00:00:00+00:00", "value": 8 }      ],      "websiteAction": [        { "startTime": "2025-06-01T00:00:00+00:00", "value": 41 }      ],      "businessBookings": [        { "startTime": "2025-06-01T00:00:00+00:00", "value": 0 }      ],      "businessFoodOrders": [        { "startTime": "2025-06-01T00:00:00+00:00", "value": 0 }      ],      "businessFoodMenuClicks": [        { "startTime": "2025-06-01T00:00:00+00:00", "value": 0 }      ]    }  }}

401Unauthenticated, missing or invalid API key.

返回某个地点的每日 Google Business Profile 互动数据。每项指标都是一个时间序列数据点数组，其中每个数据点都包含 startTime（计数归属的日期）和 value。

可用指标：

total：商家资料的总展示次数，即 search 与 maps 之和。它不包含下方的操作指标，因此在上面的示例中，412 = 300 次搜索展示 + 112 次地图展示。
search：在 Google Search结果中的展示次数（桌面端和移动端合计）
maps：在 Google Maps结果中的展示次数（桌面端和移动端合计）
directionsAction：前往该地点的路线请求次数
phoneAction：通话按钮的点击次数
websiteAction：点击进入网站的次数
businessBookings：通过商家资料发起的预订次数
businessFoodOrders：通过商家资料提交的餐饮订单数
businessFoodMenuClicks：菜单链接的点击次数

路径中可使用任一种 id 形式

1800289 和 TG9jYXRpb246MTgwMDI4OQ== 都会解析为同一个地点。建议优先使用 Base64 Relay id：每个读取端点都会返回此形式，其余 API 也采用此形式。如果传入的值既不是数字，也不是可解码的 Relay id，则会返回 200，其响应体为 {"data":{"googleInsights":null},"errors":[...]}，这很容易被误认为是服务器故障。

Shell

curl -s 'https://listingsapi.com/api/v4/locations/TG9jYXRpb246MTgwMDI4OQ==/google-analytics?fromDate=2025-06-01&toDate=2025-06-30' \  -H "Authorization: API $LISTINGSAPI_KEY"

报告数据更新的影响

一种常见用途是生成变更前后的可见度对比报告：将营业时间或类别变更推送到某个地点后，轮询 google-analytics 以获取变更前后数周的数据，并将 search + maps 绘制成图表，以展示提升效果。当该地点在请求的时间范围内没有 Google 数据，或其 Google 商家资料尚未连接时，各项指标会返回 null（而非空数组）；在汇总时，请以相同方式处理 null 和 []。结合 Facebook 和 Bing 分析数据，可获得跨发布平台的视图。