API 文件

所有介面都支援 IPv4 與 IPv6，不需註冊即可呼叫；帶上 API Key 可享有更高的呼叫額度。基礎位址： https://bgp.cx

快速開始

bash

$ curl https://bgp.cx/api/ip/8.8.8.8
{
  "ip": "8.8.8.8",
  "version": 4,
  "country": "美国",
  "country_code": "US",
  "region": "California",
  "timezone": "America/Chicago",
  "isp": "Google LLC",
  "asn": 15169,
  "asn_organization": "Google LLC",
  "network": "8.8.8.0/24"
}

命令列

使用 curl、wget、PowerShell、HTTPie 等工具存取時，會自動回傳純文字。

指令	說明
curl https://bgp.cx	本機 IP
curl -4 https://bgp.cx	指定使用 IPv4
curl -6 https://bgp.cx	指定使用 IPv6
curl https://bgp.cx/info	本機 IP 的詳細資訊
curl https://bgp.cx/ip/1.1.1.1	查詢指定 IP
curl https://bgp.cx/ip/github.com	查詢網域（自動解析）
curl https://bgp.cx/asn/4134	查詢 ASN 及其 IP 段
wget -qO- https://bgp.cx	wget
irm https://bgp.cx/api/ip	PowerShell

JSON 介面

GET/api/ip · /api/ip/{ip|domain}

回傳合併後的 JSON 結果，不帶參數時查詢訪客本身。舊路徑 /geoip、/json 仍可使用。

GET/api/lookup?q={ip|domain}

回傳完整結果：info 為查詢結果，resolved 為網域解析結果。

GET/ip · /jsonip

只回傳訪客 IP，分別為純文字與 {"ip":"…"}。

ASN

GET/asn/{asn} · /api/asn/{asn}

回傳 ASN 的名稱、網域、國家、網路類型和宣告的 IP 段。family 取 4 或 6 只回傳對應協定的前綴，limit（最大 10000）和 offset 用於分頁。{asn} 可以寫成 4134 或 AS4134。

curl "https://bgp.cx/api/asn/4134?family=4&limit=100&offset=0"

回傳欄位

欄位	說明
`ip` / `version`	IP 位址 / 4 或 6
`country` / `country_code`	國家或地區名稱 / ISO 3166 代碼
`region` / `region_code`	省份、州
`city` / `district`	城市 / 區縣
`continent_en` / `country_en` / `region_en` / `city_en` / `district_en`	英文地名（介面語言不是英文、且資料含英文名稱時回傳）
`isp` / `organization`	電信業者 / 組織
`asn` / `asn_organization` / `asn_domain`	自治系統號 / 自治系統名稱 / AS 網域
`usage_type`	使用場景：Broadband、Mobile、DataCenter、Cloud、CDN、VPN、Spider、AICrawler、Business、Education 等
`area_code` / `city_code` / `phone_code`	行政區劃代碼 / 電話區號 / 國際區號
`country_alpha3` / `flag`	國家三碼代號（ISO 3166-1 alpha-3）/ 國旗
`currency` / `currency_name` / `languages`	貨幣代碼 / 貨幣名稱 / 官方語言
`network`	所在網段（CIDR）
`latitude` / `longitude`	近似經緯度，僅在與城市一致時回傳
`timezone` / `continent`	時區 / 洲
`scope`	非公網位址的類型：private、loopback、cgnat、reserved 等

沒有資料的欄位不會出現在結果中。回傳哪些欄位取決於 API 方案（每個方案對應一個資料庫版本的欄位，見價格頁）；不帶 Key 時依網站設定。

單欄位介面

GET/ip/{ip}/{field}

只回傳某個欄位的值（純文字），適合在腳本中使用。除上表欄位外，還支援 location（完整歸屬地）與 loc（"緯度,經度"）。{ip} 寫成 me 表示查詢本機。

curl https://bgp.cx/ip/me/country

通用參數

參數	說明
`lang`	結果語言：zh-CN、en、ja、de、fr、ru、es、pt-BR
`format`	`json` 或 `text`，強制指定回傳格式
`pretty`	格式化輸出 JSON
`callback`	JSONP 回呼函式名稱
`key`	API Key（僅查詢介面），建議使用 `Authorization: Bearer` 請求標頭

所有 JSON 介面都允許跨網域（Access-Control-Allow-Origin: *），前端可以直接呼叫。

API Key 與限額

不帶 Key 時依 IP 限制頻率（IPv6 依 /64 網段計算）；帶上 Key 後依帳戶計算，額度取決於你的方案。超出限額會回傳 429，回應標頭 Retry-After 表示需等待的秒數。

curl -H "Authorization: Bearer ipk_xxx" https://bgp.cx/api/ip/1.1.1.1

頻率與配額

帶 API Key 的請求按帳戶計量：每分鐘請求數和每日查詢量由 API 方案決定（沒有付費方案時使用免費版額度），每日查詢量在 0 點重置。不帶 Key 的請求按 IP（IPv6 按 /64）限制每分鐘請求數，網站也可以設定每日查詢次數。超出時回傳 429，Retry-After 提供可重試的秒數。

回應標頭	說明
`X-RateLimit-Limit`	每分鐘可請求次數
`X-Quota-Limit`	每日查詢量（不限時不回傳）
`X-Quota-Remaining`	今日剩餘查詢次數

資料庫下載

GET/api/databases

版本清單。<code>editions</code> 是所有上架版本及其欄位；帶上 API Key 時還會回傳 <code>downloads</code>：你的帳戶可下載的版本與檔案（檔名、格式、大小、SHA-256、建置時間）。

GET/dl/{file}

下載已購版本的檔案，{file} 是檔名，例如 ipdb-insight.mmdb、ipdb-insight-v4.xdb。API Key 需放在 Authorization: Bearer 請求標頭中。支援 Range 續傳，續傳不重複計次。

curl -LOJ -C - -H "Authorization: Bearer ipk_xxx" https://bgp.cx/dl/ipdb-insight.mmdb

帳號僅限本人使用：每個帳號每天只能在有限個網路（IPv4 位址 / IPv6 /64）下載，網頁產生的下載連結只在取得它的網路中有效。

離線資料庫的欄位、檔案格式和讀取範例見資料庫文件。

路徑與 WAF

所有查詢和下載都使用固定前綴，方便在 WAF / CDN 中依路徑設定白名單或快取規則。為相容舊用法，/{ip} 這樣的根路徑仍可查詢（瀏覽器會跳轉到 /ip/），管理員可在後台關閉。

路徑前綴	說明
`/ip/`	IP / 網域查詢頁面、文字和單一欄位
`/asn/`	ASN 頁面和文字
`/api/`	JSON 介面（會被腳本高頻呼叫，不要開啟人機驗證）
`/dl/`	資料庫檔案下載（檔案較大，不要快取）

錯誤碼

狀態碼	意義
`400`	IP 或網域無效、網域無法解析
`401`	API Key 無效，或下載時未提供憑證
`403`	沒有此資料庫的下載權限、超出次數或網路數限制
`404`	資源不存在
`429`	請求過於頻繁

錯誤回應格式：{"error":"…","code":400}；以命令列存取時回傳 error: … 純文字。