取得地點的 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 分析資料，即可取得跨發布平台的整體檢視。