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'

請處理三種情況：任一期間為 null（未連結）、較早期間為 0（除以零），以及日期範圍尚未結束的情況，因為將部分月份與完整月份比較時，結果總是看起來有所下降。每次呼叫都會計入您的速率限制，因此請快取較早期間的資料，避免每次顯示頁面時都重新擷取。

後續步驟