Listings APIListings API
登入

分析

每個商家檔案分析端點均附有 cURL、Python 和 Node 範例：提供地點的 Google 和 Facebook 每日指標，以及 Bing 每週瀏覽次數。

商家檔案分析顯示地點在各發布平台上被瀏覽及觸發互動的頻率：曝光次數、頁面瀏覽次數、路線查詢次數、通話次數和網站點擊次數。共有三個端點，每個發布平台各一個，且全都是讀取操作，因此使用 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 分析

這三個端點使用相同的參數。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 是該筆計數所歸屬的日期。在範例中，第一天的 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 商家檔案瀏覽次數，每週 1 個資料點。

與 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。請參閱 速率限制。

完整清單請見 錯誤碼。

後續步驟