API Docs Database docs

API Docs

Every endpoint supports IPv4 and IPv6 and works without signing up; an API key raises your limits. Base URL: https://bgp.cx

Quick start

bash

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

Command line

Requests from curl, wget, PowerShell, HTTPie and similar tools get plain text automatically.

Command	Description
curl https://bgp.cx	Your IP
curl -4 https://bgp.cx	Force IPv4
curl -6 https://bgp.cx	Force IPv6
curl https://bgp.cx/info	Details of your IP
curl https://bgp.cx/ip/1.1.1.1	Look up an IP
curl https://bgp.cx/ip/github.com	Look up a domain (resolved automatically)
curl https://bgp.cx/asn/4134	Look up an ASN and its prefixes
wget -qO- https://bgp.cx	wget
irm https://bgp.cx/api/ip	PowerShell

JSON endpoints

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

Returns the merged result as JSON; without a parameter it describes the caller. The legacy paths /geoip and /json still work.

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

Full result: info holds the lookup result and resolved the domain's addresses.

GET/ip · /jsonip

Just the caller's IP, as plain text or {"ip":"…"}.

ASN

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

Returns the name, domain, country, network type and announced prefixes of an ASN. family=4 or 6 limits the prefixes to one protocol; limit (max 10000) and offset paginate. {asn} may be 4134 or AS4134.

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

Response fields

Field	Description
`ip` / `version`	IP address / 4 or 6
`country` / `country_code`	Country name / ISO 3166 code
`region` / `region_code`	Province / state
`city` / `district`	City / district
`continent_en` / `country_en` / `region_en` / `city_en` / `district_en`	English place names (returned when the request language is not English and the data has them)
`isp` / `organization`	ISP / organization
`asn` / `asn_organization` / `asn_domain`	AS number / AS name / AS domain
`usage_type`	Usage type: Broadband, Mobile, DataCenter, Cloud, CDN, VPN, Spider, AICrawler, Business, Education …
`area_code` / `city_code` / `phone_code`	Division code / area dialing code / calling code
`country_alpha3` / `flag`	ISO 3166-1 alpha-3 code / flag emoji
`currency` / `currency_name` / `languages`	Currency code / currency name / languages
`network`	Network (CIDR)
`latitude` / `longitude`	Approximate coordinates, only when consistent with the city
`timezone` / `continent`	Time zone / continent
`scope`	Type of non-public addresses: private, loopback, cgnat, reserved…

Fields without data are omitted. Which fields are returned depends on your API plan (each plan matches the field set of a database edition, see Pricing); without a key the site setting applies.

Single-field endpoint

GET/ip/{ip}/{field}

Returns a single value as plain text, handy in scripts. Besides the fields above, location (full location) and loc ("lat,lon") are supported. Use me as {ip} for your own address.

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

Common parameters

Parameter	Description
`lang`	Result language: zh-CN, en, ja, de, fr, ru, es, pt-BR
`format`	`json` or `text` to force the format
`pretty`	Pretty-print JSON
`callback`	JSONP callback name
`key`	API key (lookups only); prefer the `Authorization: Bearer` header

All JSON endpoints allow cross-origin requests (Access-Control-Allow-Origin: *).

API keys and limits

Without a key, limits apply per IP (per /64 for IPv6); with a key, per account according to your plan. Exceeding the limit returns 429 with a Retry-After header.

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

Rate limits & quota

Requests with an API key are metered per account: requests per minute and queries per day come from your API plan (the free tier without a paid plan) and reset at midnight. Requests without a key are limited per IP (IPv6 per /64) per minute, and the site may also set a daily limit. Over the limit you get 429; Retry-After gives the seconds to wait.

Header	Description
`X-RateLimit-Limit`	Requests allowed per minute
`X-Quota-Limit`	Queries per day (absent when unlimited)
`X-Quota-Remaining`	Queries left today

Downloads

GET/api/databases

Edition list. <code>editions</code> lists every published edition and its fields; with an API key the response also has <code>downloads</code>: the editions your account may download and their files (name, format, size, SHA-256, build time).

GET/dl/{file}

Downloads a file of an edition you own; {file} is the file name, e.g. ipdb-insight.mmdb or ipdb-insight-v4.xdb. Send the API key in an Authorization: Bearer header. Range resumes are supported and not counted again.

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

Accounts are personal: each can download from a limited number of networks (IPv4 address / IPv6 /64) per day, and web download links only work on the network they were issued to.

Fields, file formats and code samples of the offline databases are in the database docs.

Paths & WAF

All lookups and downloads use fixed prefixes, so WAF / CDN rules can allow-list or cache by path. For compatibility, root paths like /{ip} still work (browsers are redirected to /ip/); administrators can turn this off.

Path prefix	Description
`/ip/`	IP / domain lookup pages, text and single fields
`/asn/`	ASN pages and text
`/api/`	JSON APIs (called by scripts; do not put a challenge on them)
`/dl/`	Database file downloads (large, do not cache)

Errors

Status	Meaning
`400`	Invalid IP or domain, or the domain doesn't resolve
`401`	Invalid API key, or no credentials for a download
`403`	No access to this database, or a daily/network limit was reached
`404`	Not found
`429`	Too many requests

Errors look like {"error":"…","code":400}; terminals get plain error: … text.