API Hop

文件目錄

API Hop 文件

SimilarwebAPI

透過經過驗證的 REST 端點，查詢網站流量、搜尋關鍵字、反向連結、引薦、競爭對手及互動資料。

SimilarwebAPI 在 /v1/similarweb 下提供 27 個唯讀資料端點，與其他 RequestBeam API 共用帳號、API 金鑰、餘額與使用紀錄。可用性取決於閘道是否啟用及您的 API 金鑰權限；文件本身不代表正式環境已可用。

驗證

請傳送您的 RequestBeam API 金鑰，而非第三方憑證：

http
Authorization: Bearer YOUR_API_KEY

請求範例

所有公開操作均使用 GET，透過查詢參數傳值，不含請求主體。路徑與參數的大小寫必須完全符合文件。

僅支援全球資料（country=999）。 其他合法的國家參數值在請求上游前統一改為 999，傳回全球資料，而非所指定國家的資料。

對於接受日期的端點，合法、完整的明確 from/to 區間優先。對於接受 latest 的端點，傳入的值仍須通過原有格式和端點允許值驗證，但不再用於選擇區間，也不傳給 Similarweb；不補預設 latest。沒有明確區間時，原有 latest、預設值和視窗行為保持不變。History 的限制仍適用；不接受 latest 的端點仍拒絕該欄位。

bash
curl --get "https://api.apihop.ai/v1/similarweb/websites/incoming-referrals" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "key=example.com" \
  --data-urlencode "country=999" \
  --data-urlencode "page=1"

引薦流量使用單一小寫 key 主機名稱參數，而非 keys。此 key 是目標網站的業務查詢參數，不是 API 憑證，僅允許在明確列入白名單的 Similarweb GET 路由中使用。API 驗證仍使用 Authorization，其他憑證查詢欄位仍被禁止。資料列傳回於 Records，而非 Data。各操作的確切欄位請見完整端點參考。

涵蓋範圍

  • 搜尋：關鍵字建議、排名頁面、網站關鍵字、自然與付費搜尋、品牌關鍵字。
  • 網站流量：互動、造訪、地理分布、裝置組成、管道與社群流量。
  • 關聯：反向連結、流入引薦、流出流量與相似網站。
  • 歷史：分別提供每月造訪、跳出率、造訪時長與每次造訪頁數的時間序列。

回應格式

成功回應會保留原生 JSON 主體，不新增 success/data 包裝。欄位名稱、未知欄位、空陣列及數值精度保持不變。不同端點可能傳回 Data、Records 或其他原生結構，請勿假設所有資料列都有統一欄位。

成功但為空的結果不代表該網域沒有流量。失敗的請求不得視為空資料。請保留 X-Request-Id 與請求時間，以便疑難排解。

計費與分頁

全部 27 個端點的標準價格為每次成功請求 $0.0005，或每 1,000 次請求 $0.50。依請求次數而非資料列計費；成功的空結果仍算一次請求。每個後續頁面都是獨立請求。若已設定帳號專屬價格，則優先適用。參數無效、缺少授權或餘額不足的請求，不會作為成功的計費呼叫執行。上游失敗的請求不收費。

依平台最低餘額政策，呼叫前您的帳號必須至少有 $0.10 可用餘額。標準費用仍為每次成功請求 $0.0005。

僅使用所選端點文件列出的分頁欄位。頁碼一般從 1 開始；反向連結使用 Page 與 PageSize，其他表格可能使用 page、pageSize 或 rowsPerPage。請勿傳送不支援的每頁筆數欄位。

錯誤

平台錯誤使用以下結構；code 是平台業務代碼，不是 HTTP 狀態碼：

json
{"success":false,"error":{"code":10000,"message":"Invalid request parameters"},"requestId":"..."}

常見 HTTP 狀態包含查詢無效 400、API 金鑰無效 401、餘額不足 402、閘道拒絕存取 403、速率限制 429，以及上游或服務暫時失敗 5xx。請勿對格式錯誤的請求不加修改地重試。