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: … 纯文本。