WorldIP API — Developer Documentation
A fast, JSON REST API over the same global IP intelligence that powers worldip.io — IP profiles, ASN & organization ownership, reverse/forward DNS, VPN/proxy classification, trust scoring and live BGP routing events. Built on a worldwide adaptive-scanning fleet processing over a billion record updates a day, with sub-second responses for cached profiles.
MCP server (for AI agents)
WorldIP speaks the Model Context Protocol, so an MCP-aware client can call it as a tool instead of scraping pages. No API key is required — the server exposes the same free keyless profile as the public endpoints.
| Endpoint | https://worldip.io/mcp |
|---|---|
| Transport | HTTP, JSON-RPC 2.0 over POST. A GET returns 405 by design — it is an API endpoint, not a page. |
| Protocol | 2025-06-18 |
| Auth | None. Rate-limited per source IP. |
| Server card | /.well-known/mcp/server-card.json |
Add it to Claude Code
claude mcp add --transport http worldip https://worldip.io/mcpOr by hand in .mcp.json
The type field selects the transport — the config will not work without it.
{ "mcpServers": { "worldip": { "type": "http", "url": "https://worldip.io/mcp" } } }Tools
lookup_ip | Look up a public IPv4 or IPv6 address: owner/organisation, ASN, country, region, city, CIDR, reverse DNS (PTR) and forward-confirmed DNS, plus a daily count of the domains hosted on an IPv4 address (domains_hosted, from issued.live). Takes ip. |
|---|---|
whats_my_ip | Return the caller’s own public IP and its profile. Takes no arguments. |
Both tools are read-only, idempotent and open-world (they consult live data), and are annotated as such in tools/list.
The tools and the free keyless endpoint (https://worldip.io/{ip}) carry domains_hosted:
how many registrable domains have a name resolving to the address, updated daily from issued.live's DNS
data — a number, never the names. count is 0 when none were seen and
null when the count is unavailable; the whole object is null for reserved addresses
and, for now, for IPv6. The keyed lookup below is unchanged.
"domains_hosted": {"count":57807,"as_of":"2026-11-16","source":"issued.live","attribution":"Domain data provided by issued.live — for full details visit https://issued.live/pricing","details_url":"https://issued.live/pricing"}Getting started
Every endpoint lives under a single HTTPS base URL and returns application/json.
A successful response is 200 OK with the record at the top level; errors use
standard HTTP status codes with a JSON error body (see Errors).
| Base URL | https://worldip.io |
|---|---|
| Version | v1 (path-versioned) |
| Format | JSON, UTF-8. Slashes are unescaped. |
| Methods | GET (all data endpoints). OPTIONS is accepted for CORS preflight. |
| Auth | Authorization: Bearer YOUR_KEY, over HTTPS only. Never put a key in a URL (?key=). |
Quickstart — one full IP profile
curl -s https://worldip.io/api/v1/ext/lookup/8.8.8.8 \
-H "Authorization: Bearer YOUR_KEY"
https://worldip.io/{ip},
1,000 lookups a day) and the public Pulse feeds
(below) work today.
Beta keys for issued.live Plus and Pro customers
While the WorldIP API is in beta, our team issues API keys free of charge to customers with an active issued.live Plus or Pro subscription. issued.live and WorldIP are separate services run by the same company, Tuxxin LLC: your issued.live plan and billing do not change, and WorldIP charges nothing for a beta key.
| issued.live plan | WorldIP key | Enriched lookups / mo | Per minute | Concurrent | Data |
|---|---|---|---|---|---|
| Plus | Pro | 200,000 | 600 | 10 | The IP profile lookup with VPN / proxy / Tor / datacenter classification, residential & mobile proxy detection, access type, trust score, BGP prefix and origin ASN, /24 neighbours, region and city; plus the ASN, organization and range lookups and search. |
| Pro | Business | 1,000,000 | 1,200 | 20 | Everything in Pro, plus MOAS and routing anomalies on the lookup, Web3 node roles and the Pulse API. |
Basic lookups on https://worldip.io/{ip} with
a paid key have no daily cap (a free account key: 10,000 a day). Responses carry X-RateLimit-* (per minute) and
X-Concurrency-Limit (requests in flight); enriched lookups also carry X-Quota-*
(monthly enriched lookups). Limits may change during the beta.
How to get your key
- Subscribe to issued.live Plus or Pro. We issue keys by hand and email yours to the address on your issued.live account within one business day.
- No key after one business day? Contact us from that address.
- We store only a hash of your key and cannot show it again, so keep it safe. If you lose it or it leaks, contact us and we will replace it.
Using your key
- Send it only in the
Authorization: Bearer YOUR_KEYheader, and only tohttps://URLs. - Never put it in a URL (
?key=): URLs are written to server, proxy and browser logs. Never ship it in browser or app code that others can read; call the API from your server. - Keep the
attributiontext (andgrip_attributionwhere present) with any API data you display or pass on: some fields come from licensed datasets (see Data sources).
Beta conditions
- Free during the beta, one key per issued.live subscription, for you or your organisation only. Do not share, publish, sell or sublicense it.
- Limits may change during the beta, and so may fields and endpoints. We announce breaking changes on this page and email key holders.
- No SLA. Beta keys come with no uptime commitment.
- Revocation. We may suspend or revoke a key that is abused or used against our Terms, and we revoke it when the issued.live subscription it came with ends.
- End of the beta: 30 days after WorldIP’s paid plans launch. We will email you before then. Nothing is charged automatically.
- Support is best effort, through our contact form.
The full terms are in our Terms of Use (API keys and the beta).
Authentication
Present your key on every keyed request as a Bearer token, over HTTPS only. Do not use the
?key= query parameter: it is accepted only for older integrations, and a key in a URL is
written to server logs and can leak through referrers and browser history.
Authorization: Bearer YOUR_KEY
Scopes
Each key carries one or more scopes. A request is rejected with 403 forbidden_scope
if its key lacks the scope the endpoint requires.
| Scope | Grants |
|---|---|
ext:read | The IP profile lookup (/api/v1/ext/lookup), the ASN, organization and range lookups and search (/api/v1/ext/asn, /org, /range, /search), and keyed basic lookups on https://worldip.io/{ip}. |
pulse:read | The keyed Pulse event stream + summary (Business keys). |
* | All scopes (issued only to trusted / enterprise integrations). |
Key locking (optional)
A key can be pinned so a leaked value is useless elsewhere:
- Origin lock — restricts browser calls to one site
(enforced whenever the request carries an
Origin/Referer). Mismatch →403 origin_not_allowed. - IP allow-list — restricts calls to specific caller IPs,
the strongest server-to-server lock. Off-list →
403 ip_not_allowed.
IP profile lookup
One consolidated intelligence profile for an IPv4 address: PTR, ASN, organization, country,
CIDR, trust score, VPN/proxy/Tor/datacenter classification (including a residential &
mobile proxy verdict), BGP route + recent routing anomalies, the hosted-domain count, and Web3 roles. The same route takes an IPv6 address; see
IPv6 lookups for what an IPv6 profile contains.
The assembly is cached per IP for five minutes at the origin, so repeat lookups return in
milliseconds (X-Ext-Cache: HIT / MISS). Responses are never cached by
shared caches (Cache-Control: private, no-store), so every call is counted.
| Path parameter | Description |
|---|---|
ipv4 | Dotted-quad IPv4 address, e.g. 8.8.8.8. Invalid input → 400 bad_ip. |
ipv6 | Any valid IPv6 notation, e.g. 2001:4860:4860::8888 (echoed back in canonical compressed form). Invalid input → 400 bad_ip. |
curl -s https://worldip.io/api/v1/ext/lookup/8.8.8.8 \
-H "Authorization: Bearer YOUR_KEY"
{
"ip": "8.8.8.8",
"reserved": false,
"reserved_note": null,
"ptr": "dns.google",
"asn": { "number": 15169, "name": "Google LLC" },
"org": { "name": "Google LLC", "slug": "google-llc", "category": "hosting" },
"country": { "code": "US", "name": "United States" },
"cidr": "8.8.8.0/24",
"trust": { "score": 92, "band": "Trusted", "color": "#3fb950" },
"web3": [],
"bgp": {
"prefix": "8.8.8.0/24",
"origin_asn": 15169,
"moas": false,
"anomalies": []
},
"forward_dns": null,
"flags": [
{ "key": "hosting", "label": "Hosting/DC", "level": "warn", "emoji": "🖥️",
"title": "Datacenter / hosting network - server addresses, not home connections." }
],
"classification": {
"is_vpn": false,
"is_proxy": false,
"is_relay": false,
"relay_source": null,
"is_anonymous": false,
"access_type": "hosting",
"proxy_density_30d": null,
"vpn_density_30d": null,
"is_tor": false,
"is_datacenter": true,
"is_vpn_likely": false,
"verdict": "hosting",
"confidence": "high",
"score": 0,
"source": "worldip-classification"
},
"grip": null,
"grip_attribution": null,
"attribution": "Includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com, used under the MaxMind GeoLite End User License Agreement; GeoLite2 incorporates GeoNames data (https://www.geonames.org) under CC BY 4.0. Includes the IPinfo Lite dataset (https://ipinfo.io) under CC BY-SA 4.0. License details: https://worldip.io/data-sources",
"links": {
"ip": "https://worldip.io/8.8.8.8",
"asn": "https://worldip.io/asn/15169",
"org": "https://worldip.io/org/google-llc"
},
"generated_at": "2026-07-17T00:45:12+00:00"
}
Response fields
| Field | Type | Notes | Tier |
|---|---|---|---|
ip | string | Canonical IPv4 echoed back. | Free |
ptr | string | null | Reverse-DNS hostname. | Free |
asn | object | null | number, name. | Free |
org | object | null | name, slug, category. | Free |
country | object | null | ISO-2 code + name. | Free |
cidr | string | null | Allocated block this IP sits in. | Free |
links | object | Canonical worldip.io URLs for the IP/ASN/org. | Free |
forward_dns | object | null | How many domains are hosted on the IP: hosted_domain_count. On plan keys (Basic and up, beta keys included) this object carries the count only: hosted_domains is always an empty list, hostname and registerable_domain are always null, and hosted_domains_truncated is true whenever the count is above 0. Keys without a plan (such as keys issued before the beta) keep the original object, which also lists a sample of up to 25 names (usually about 10) and fills hostname and registerable_domain. For now the count comes from GRIP, covers IPv4 only and is present only while WorldIP holds a GRIP result for the address from the last few hours; otherwise forward_dns is null. | Basic |
classification | object | VPN / proxy / Tor / datacenter, access_type, residential/mobile-proxy verdict, confidence, score, and is_relay + relay_source (Apple iCloud Private Relay egress). | Pro |
trust | object | null | score 0-100, band, color. | Pro |
flags | array | Human-readable risk chips (Tor exit, Proxy/VPN, Hosting/DC, Malware). | Pro |
bgp | object | null | prefix and origin_asn (Basic and up); moas and the last 7 days’ routing anomalies[] ({type, severity, count}; Business and up). | Basic Business |
web3 | array | Blockchain node roles hosted on the IP (chain + role). | Business |
generated_at | string | ISO-8601 UTC timestamp of assembly. | Free |
attribution | string | Data-licence attribution for the geolocation, ASN and organization fields (MaxMind GeoLite2 with GeoNames, IPinfo Lite). Present on every plan; the keyless endpoint carries it as _meta.attribution. | Free |
version | integer | 6. IPv6 profiles only; an IPv4 profile has no version key. | Free |
address_type, prefixes, embedded_ipv4 | string, object, string | null | IPv6 only: address class, the containing /32 /48 /56 /64, and the IPv4 inside a NAT64 or 6to4 address. | Free |
rdns | object | IPv6 only: scan status, kind of PTR (isp_generated, wildcard or specific), checked_at, forward_check, note. | Free |
unavailable | object | IPv6 only: every field that is null because WorldIP has no IPv6 source for it, with the reason. | Free |
classification.verdict becomes
residential_proxy with is_proxy: true. Observations expire: an address
that is no longer seen as a proxy exit drops out of the verdict. Unlocked on the Pro tier.
classification.is_relay is true
when the address is an Apple iCloud Private Relay egress. We match it against our own copy of
Apple's published egress list, refreshed daily, and relay_source is then
"icloud_private_relay". When only GRIP flags the relay it is "grip",
and otherwise null. A relay egress carries traffic for many ordinary Apple users whose own
addresses are hidden, so it does not change verdict, is_vpn,
is_proxy or the trust score. IPv6 lookups use the same list; GRIP has no IPv6
data, so for IPv6 relay_source is "icloud_private_relay" or null.
IPv6 lookups
Both IP endpoints take IPv6 addresses: the free keyless https://worldip.io/{ipv6} and the keyed
/api/v1/ext/lookup/{ipv6}. An IPv6 profile has the same keys as an IPv4 one, so one parser
handles both, plus "version": 6, the containing prefixes and an rdns block.
Authentication, scopes, per-key rate and concurrency limits, the monthly allowance, plan data tiers,
CORS and the 5-minute origin cache work exactly as for IPv4.
| IPv6 field | Source | Endpoint |
|---|---|---|
country, region, city | The same geolocation release as our IPv4 data, rebuilt daily. City-level IPv6 geolocation is approximate and often absent. | Keyless + keyed |
asn, org.name, cidr | The same ASN and organization data as IPv4. cidr is the most specific network we hold for the address. | Keyless + keyed |
ptr, rdns (and the keyless forward_dns forward check) | WorldIP's own IPv6 reverse-DNS scans. | Keyless + keyed |
org.slug, org.category | The organization's slug and category (isp, hosting, cdn, …), as for IPv4. | Keyed (every plan) |
classification.is_datacenter, access_type, flags | Hosting/datacenter classification by the network's organization, as for IPv4. | Keyed (Pro+) |
classification.blocklists, is_bogon | IPv6 blocklists (Spamhaus DROPv6) and Team Cymru IPv6 fullbogons. | Keyed (Pro+) |
classification.is_relay | Apple iCloud Private Relay egress list, refreshed daily. | Keyed (Pro+) |
null, never false, and the unavailable object names each one
with the reason. is_vpn, is_proxy and is_tor are true only when
an IPv6 blocklist lists the address; otherwise they are null.
rdns.kind is isp_generated
when the name encodes the address (for example p200300c8....dip0.t-ipconnect.de, in hex, hextets,
nibbles or base 36) or comes from a network that gives every address its own generated name, and
wildcard for a name shared by many addresses. Such a name shows which network the address is in.
It is not evidence that a host is live there.
specific means we found no template or wildcard, not that the name was assigned by hand.
When our latest scan could not resolve the address, rdns.status is lookup_failed and
ptr is the last name we saw.
rdns.forward_check is confirmed, mismatch or not_checked;
forward_dns.confirmed is true only when it is confirmed.
curl -s https://worldip.io/2003:c8:734:9700::1
{
"ip": "2003:c8:734:9700::1",
"version": 6,
"ptr": "p200300c8073497000000000000000001.dip0.t-ipconnect.de",
"forward_dns": { "hostname": "p200300c8073497000000000000000001.dip0.t-ipconnect.de", "confirmed": true },
"asn": { "number": 3320, "name": "Deutsche Telekom AG" },
"org": { "name": "Deutsche Telekom AG" },
"country": { "code": "DE", "name": "Germany" },
"region": "Baden-Wurttemberg",
"city": "Leutkirch",
"cidr": "2003:c8:400::/38",
"address_type": "Global Unicast",
"prefixes": { "/32": "2003:c8::/32", "/48": "2003:c8:734::/48", "/56": "2003:c8:734:9700::/56", "/64": "2003:c8:734:9700::/64" },
"rdns": {
"status": "found",
"kind": "isp_generated",
"checked_at": "2026-09-30T10:34:08Z",
"forward_check": "confirmed",
"note": "ISP-generated name: the network names every address from a template, usually by encoding the address itself. It shows which network the address belongs to, not that a host is live there."
},
"_meta": { "keyless": true, "docs": "https://worldip.io/developers", "note": "...",
"attribution": "Includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com, used under the MaxMind GeoLite End User License Agreement; GeoLite2 incorporates GeoNames data (https://www.geonames.org) under CC BY 4.0. Includes the IPinfo Lite dataset (https://ipinfo.io) under CC BY-SA 4.0. License details: https://worldip.io/data-sources",
"generated_at": "...", "rate": { "limit": 1000, "remaining": 999, "reset": "...", "window_seconds": 86400 } }
}
curl -s https://worldip.io/api/v1/ext/lookup/2606:54c0:5898::1 -H "Authorization: Bearer YOUR_KEY"
"org": { "name": "Cloudflare, Inc.", "slug": "cloudflare-inc", "category": "cdn" },
"classification": {
"is_vpn": null, "is_proxy": null, "is_relay": true, "relay_source": "icloud_private_relay",
"is_anonymous": null, "access_type": "hosting", "is_tor": null, "is_datacenter": true,
"verdict": null, "confidence": null, "score": null, "is_bogon": false, "blocklists": [], ...
},
"trust": null, "bgp": null, "forward_dns": null,
"unavailable": { "trust": "Trust score is IPv4-only: ...", ... }
Reserved, private and link-local addresses return
reserved: true with no network data. An IPv4-mapped address (::ffff:8.8.8.8) is the
IPv4 address it carries, and every endpoint answers it as that address: the keyless endpoint and the MCP
tools return the IPv4 profile, and /api/v1/ext/lookup/::ffff:8.8.8.8 is the IPv4 lookup, counted
and cached once, as 8.8.8.8. NAT64 (64:ff9b::/96) and 6to4 (2002::/16)
addresses are IPv6 addresses; their profile adds embedded_ipv4 as a hint.
ASN, organization & range lookups
Look up the networks behind the addresses: an autonomous system, an organization that holds address space,
or any IPv4 range, plus the registered blocks and announced prefixes each one holds. These endpoints take the
same key, scope (ext:read), per-minute and concurrency limits as the
IP profile lookup, and return the same
asn / org / country objects, so one parser handles both.
404 for an unknown ASN or slug is counted too.
Malformed input (a bad AS number, CIDR, slug or parameter) is answered with a 400 before
authentication and is never counted. Responses are never cached by shared caches
(Cache-Control: private, no-store).
| Endpoint | Returns |
|---|---|
GET /api/v1/ext/asn/{asn} | ASN profile: name, domain, category, country, the operating organization, address and range counts, and how many prefixes it announces in BGP. {asn} is 15169 or AS15169. |
GET /api/v1/ext/asn/{asn}/ranges | The IPv4 blocks registered to the ASN. A list. |
GET /api/v1/ext/asn/{asn}/prefixes | The IPv4 and IPv6 prefixes the ASN announces in BGP, as seen by the RIPE RIS route collectors. A list. |
GET /api/v1/ext/org/{slug} | Organization profile: category, country, website, its ASNs (up to 500), the countries it holds space in, totals, and the prefixes announced across its ASNs. |
GET /api/v1/ext/org/{slug}/ranges | The IPv4 blocks registered to the organization. A list. |
GET /api/v1/ext/org/{slug}/prefixes | The prefixes the organization's ASNs announce in BGP, one row per prefix and origin ASN. A list. |
GET /api/v1/ext/range/{ipv4}/{prefix} | CIDR profile: the smallest registered block that contains it, with owner, ASN, location, RIR and allocation date; the BGP route covering it; and up to 50 registered blocks inside it. |
Path parameters
| Parameter | Description |
|---|---|
asn | 1 to 4294967295, with or without the AS prefix. Anything else → 400 bad_asn. |
slug | The organization's slug: the last part of its worldip.io URL (google-llc in /org/google-llc), also returned as org.slug by the IP lookup and by search. Lowercase letters, digits and hyphens → otherwise 400 bad_slug. |
ipv4/prefix | An IPv4 CIDR from /8 to /32. Host bits are dropped (8.8.8.8/24 is answered as 8.8.8.0/24). Send the slash as a plain /, not %2F. IPv6 ranges are not supported yet. Invalid → 400 bad_cidr. |
curl -s https://worldip.io/api/v1/ext/asn/AS15169 \
-H "Authorization: Bearer YOUR_KEY"
{
"asn": 15169,
"name": "Google LLC",
"domain": "google.com",
"category": "hosting",
"country": { "code": "US", "name": "United States" },
"allocated_at": "2000-03-30",
"org": { "name": "Google, LLC", "slug": "google-llc", "category": "hosting" },
"ip_count": 2559744,
"range_count": 152,
"bgp": { "announced_prefixes": 1259 },
"links": {
"asn": "https://worldip.io/asn/15169",
"org": "https://worldip.io/org/google-llc",
"ranges": "https://worldip.io/api/v1/ext/asn/15169/ranges",
"prefixes": "https://worldip.io/api/v1/ext/asn/15169/prefixes"
},
"attribution": "Includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com, used under the MaxMind GeoLite End User License Agreement; GeoLite2 incorporates GeoNames data (https://www.geonames.org) under CC BY 4.0. Includes the IPinfo Lite dataset (https://ipinfo.io) under CC BY-SA 4.0. License details: https://worldip.io/data-sources",
"generated_at": "2026-10-19T12:00:00+00:00"
}
What the profile
counts cover. ip_count and range_count on the ASN and organization profiles
(and on the asns rows of an organization) are refreshed weekly and count the MaxMind GeoLite2
ASN blocks only, IPinfo Lite blocks when MaxMind has none. The /ranges lists hold the blocks of
every source, including the smaller sub-allocations nested inside those blocks, so their total
is larger: AS15169 lists 43,535 blocks, 152 of them top-level. Ask for ?nested=0 to get the
top-level blocks only, which matches range_count closely. An organization with more than 500 ASNs
lists the largest 500 and sets asns_truncated: true.
Lists: paging, order and filters
The four list endpoints return their rows in address order (lowest address first; at the
same address the larger block or the shorter prefix comes first; IPv4 before IPv6). The order does not change
between requests, so paging is exact. Page with the cursor: pass the next_after of a page as
?after= to get the next one, until next_after is null.
?offset= pages the same order, but every page costs more the deeper it goes; use one or the
other, not both.
| Query parameter | Description |
|---|---|
limit | Rows per page, 1–1,000 (default 100). A value outside that range is refused with 400 bad_param, not capped. |
after | The next_after of the previous page, passed back unchanged. On /ranges it is a CIDR; on /asn/{asn}/prefixes a prefix; on /org/{slug}/prefixes a prefix and its origin, prefix@asn (one prefix can be announced by several of the organization's ASNs). |
offset | Rows to skip, 0–1,000,000 (default 0). Not together with after. |
nested | /ranges only: 1 (default) every block; 0 top-level blocks only, the ones no other block in the list contains. With nested=0 the cursor skips everything inside the last block returned. |
family | /prefixes only: 4, 6 or all (default). |
Every list response carries total (rows in
the whole list, with the filters applied), limit, offset (null on a cursor
page), after (the cursor you sent, or null), next_after, and
next_offset (offset paging only). Invalid after, nested or
family values → 400 bad_param.
curl -s "https://worldip.io/api/v1/ext/asn/15169/ranges?nested=0&limit=2" \
-H "Authorization: Bearer YOUR_KEY"
{
"asn": 15169,
"nested": false,
"total": 152,
"limit": 2,
"offset": 0,
"after": null,
"next_after": "8.8.8.0/24",
"next_offset": 2,
"ranges": [
{ "cidr": "8.8.4.0/24", "prefix_length": 24, "ip_count": 256,
"org": { "name": "Google, LLC", "slug": "google-llc" },
"country": "US", "region": null, "city": null,
"source": "registered", "sources": ["maxmind_asn", "ipinfo_lite"] },
{ "cidr": "8.8.8.0/24", ... }
],
"attribution": "...",
"generated_at": "2026-10-19T12:00:00+00:00"
}
curl -s "https://worldip.io/api/v1/ext/asn/15169/ranges?nested=0&limit=2&after=8.8.8.0/24" \
-H "Authorization: Bearer YOUR_KEY"
List rows
| List | Row |
|---|---|
/ranges | cidr, prefix_length, ip_count, org (ASN lists) or asn (organization lists), country, region, city, source: "registered", and sources: the datasets that hold the block (maxmind_asn, ipinfo_lite). These are registration datasets (MaxMind GeoLite2 ASN, IPinfo Lite), not RIR delegation files. Location comes from the block's own records only, so region and city are often null; the range profile adds the location of the blocks around and inside it. |
/prefixes | prefix, family (4 | 6), origin_asn, source: "bgp", samples (the announcements the collectors recorded, a visibility measure), first_seen and last_seen (ISO-8601 UTC). An organization's list also carries asns, the ASNs it covers. |
Registered space and announced space are different
things: a block can be registered to an organization and announced by another network (its upstream or its
LIR), or announced without a registration record here. Compare /ranges with /prefixes
to see both. When routing data is briefly unavailable, the profiles return bgp: null and the
/prefixes lists return 503 bgp_unavailable with a Retry-After.
curl -s https://worldip.io/api/v1/ext/range/8.8.8.0/24 \
-H "Authorization: Bearer YOUR_KEY"
{
"cidr": "8.8.8.0/24",
"network": "8.8.8.0",
"last": "8.8.8.255",
"prefix_length": 24,
"ip_count": 256,
"reserved": false,
"reserved_note": null,
"registered_cidr": "8.8.8.0/24",
"asn": { "number": 15169, "name": "Google LLC" },
"org": { "name": "Google, LLC", "slug": "google-llc", "category": "hosting" },
"country": { "code": "US", "name": "United States" },
"region": null,
"city": null,
"rir": "arin",
"allocated_at": "2014-03-14",
"bgp": { "prefix": "8.8.8.0/24", "origin_asn": 15169, "exact": true, "moas": false },
"subranges": [],
"subranges_truncated": false,
"links": {
"range": "https://worldip.io/range/8.8.8.0/24",
"asn": "https://worldip.io/asn/15169",
"org": "https://worldip.io/org/google-llc"
},
"attribution": "...",
"generated_at": "2026-10-19T12:00:00+00:00"
}
Range profile fields
| Field | Type | Notes | Tier |
|---|---|---|---|
cidr, network, last, prefix_length, ip_count | string, integer | The requested range, canonicalized. | Basic |
registered_cidr | string | null | The smallest registered block that contains the whole range (it may be the range itself, or larger). | Basic |
asn, org, country, region, city, rir, allocated_at | object / string | null | Of that block. All null when no single block covers the whole range (for example a /16 split between several holders): see subranges. | Basic |
bgp | object | null | The most specific announced prefix covering the range: prefix, origin_asn, and exact (the range itself is announced). moas (more than one origin ASN) is Business and up. null when no announced route covers it. | Basic Business |
subranges | array | null | Up to 50 registered blocks inside it, largest first, in the list-row shape (with both asn and org, and location inherited from the containing block). null when the block is too dense to list within the time budget: query a smaller CIDR. subranges_truncated is true when there are more than 50. | Basic |
Search ASNs and organizations
Find ASNs and organizations by name, or an ASN by number, ranked by the address space they hold (largest first). An IP address or a CIDR is resolved instead of name-searched. Each hit links to its profile endpoint. One call counts as one enriched lookup.
| Parameter | Description |
|---|---|
q | Required, 2–100 characters, case-insensitive. Three or more characters match anywhere in the name, with names that start with q ranked first; two characters match the start of the name only. An AS number (AS15169 or 15169) returns that ASN first. % and _ are literal characters. An IP address fills ip and an IPv4 CIDR (/8–/32) fills cidr; neither is name-searched. Otherwise → 400 bad_query. |
type | all (default), asn or org. A response only carries the lists it was asked for; ip and cidr come with all only. |
limit | Results per list, 1–50 (default 10). |
curl -s "https://worldip.io/api/v1/ext/search?q=cloudflare&limit=1" \
-H "Authorization: Bearer YOUR_KEY"
{
"query": "cloudflare",
"type": "all",
"ip": null,
"cidr": null,
"asns": [
{ "asn": 13335, "name": "Cloudflare, Inc.", "country": "US", "category": "cdn",
"ip_count": 1441792, "range_count": 1068,
"org": { "name": "Cloudflare, Inc.", "slug": "cloudflare-inc" },
"links": { "asn": "https://worldip.io/asn/13335", "api": "https://worldip.io/api/v1/ext/asn/13335" } }
],
"orgs": [
{ "name": "Cloudflare, Inc.", "slug": "cloudflare-inc", "category": "cdn", "country": "US",
"ip_count": 1560576, "range_count": 1293, "asn_count": 7,
"links": { "org": "https://worldip.io/org/cloudflare-inc", "api": "https://worldip.io/api/v1/ext/org/cloudflare-inc" } }
],
"attribution": "...",
"generated_at": "2026-10-19T12:00:00+00:00"
}
asn_count is the organization's ASNs
that hold address space. For an IPv4 address, ip is
{ "ip", "version": 4, "reserved", "cidr", "asn", "org", "country", "links" }; for IPv6 it carries
the address and its links only: call links.api (the IP
profile lookup) for the full record. For a CIDR, cidr is
{ "prefix", "registered_cidr", "asn", "org", "bgp": { "prefix", "origin_asn", "exact" }, "asns", "links" },
where asns lists the registered ASN and the BGP origin.
Pulse events
A geo-tagged stream of live "internet events" — BGP routing anomalies (MOAS, route leaks,
withdrawals, bogons, newly announced prefixes) and RIR allocation changes — each tagged with a country
and country-centroid lat/lon so it can be plotted directly on a map. Designed to be polled:
pass the returned next_since back as ?since= on the next call.
Business keys; the response carries the data-licence attribution for the location fields.
| Query param | Default | Description |
|---|---|---|
since | now − 300s | Unix seconds or ISO-8601; lower time bound. |
until | now | Upper time bound. |
limit | 500 | Max events, 1–2000. |
min_severity | 0 | Drop BGP events below this severity. |
country | all | ISO-2 country filter, e.g. US. |
types | all | CSV of moas,first_seen,withdrawal,aspath,bogon. |
category | all | all · bgp · rir. |
moas_sample | 50 | Return 1 of every N MOAS events (MOAS is a legitimate-anycast firehose). 1 = full stream. |
curl -s "https://worldip.io/api/v1/pulse/events?types=aspath,bogon&min_severity=5&limit=100" \
-H "Authorization: Bearer YOUR_KEY"
{
"events": [
{
"id": "bgp:14238894120583017472",
"category": "bgp",
"type": "aspath",
"label": "AS-path anomaly (possible leak/hijack)",
"severity": 7,
"detected_at": "2026-07-17T00:44:57+00:00",
"ts": 1768610697,
"prefix": "103.163.158.0/24",
"asn": 141804,
"counter_asn": 140171,
"country": "IN",
"lat": 22.35,
"lon": 78.67,
"detail": { "collector": "rrc05", "as_path": "13237 3320 6453 4755 141804" }
}
],
"count": 1,
"next_since": 1768610697,
"server_time": 1768610760,
"attribution": "Includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com, used under the MaxMind GeoLite End User License Agreement; GeoLite2 incorporates GeoNames data (https://www.geonames.org) under CC BY 4.0. Includes the IPinfo Lite dataset (https://ipinfo.io) under CC BY-SA 4.0. License details: https://worldip.io/data-sources"}
Pulse summary
Current event-type counts for the last hour and last 24 hours — a cheap poll for dashboards and alerting that don't need the full event bodies.
curl -s https://worldip.io/api/v1/pulse/summary \
-H "Authorization: Bearer YOUR_KEY"
{
"bgp_anomalies": [
{ "type": "moas", "category": "bgp", "label": "Multiple-origin route (MOAS)", "last_1h": 7111, "last_24h": 11250 },
{ "type": "aspath", "category": "bgp", "label": "AS-path anomaly (possible leak/hijack)", "last_1h": 9, "last_24h": 120 }
],
"rir_changes": [
{ "type": "allocation", "category": "rir", "label": "RIR allocation", "last_1h": 6, "last_24h": 214 }
],
"server_time": 1768610760,
"attribution": "Includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com, used under the MaxMind GeoLite End User License Agreement; GeoLite2 incorporates GeoNames data (https://www.geonames.org) under CC BY 4.0. Includes the IPinfo Lite dataset (https://ipinfo.io) under CC BY-SA 4.0. License details: https://worldip.io/data-sources"}
Public feeds (no key)
The same Pulse data also powers the auto-refresh on our Pulse pages, exposed as lightweight no-key poll endpoints. They share the site-wide per-IP request floor (see Rate limits); for higher volume or geo-tagged output, use the keyed Pulse events endpoint.
The most recent BGP routing anomalies (last hour, across RIS collectors).
{
"anomalies": [
{
"prefix": "200.7.251.0/24",
"unexpected_asn": 273140,
"expected_asn": 19114,
"pings": 314,
"last_seen": "2026-07-17 00:44:57",
"collector": "rrc25",
"as_path": "198150 174 12956 19114 273140"
}
]
}
Recent RIR ownership changes — allocations, transfers, and country/RIR re-assignments.
Accepts ?since_id= to fetch only newer rows.
{
"events": [
{
"id": 293167,
"changed_at": "2026-07-11 12:03:24",
"ip_start": 3627346432,
"ip_end": 3627346943,
"ip_start_str": "216.52.234.0",
"change_type": "allocation",
"old_value": null,
"new_value": "US",
"rir": "arin",
"cidr_guess": "216.52.234.0/23",
"org_name": "Unitas Global",
"org_slug": "unitas-global",
"asn": 10912,
"country_code": "US"
}
]
}
Anomalies of a single type with 24h totals. type ∈
moas, first_seen, withdrawal, bogon,
aspath.
{
"type": "aspath",
"totals": { "anomalies_24h": 120 },
"anomalies": [ /* ... */ ]
}
Rate limits
Limits are enforced with a sliding 60-second window: a key may make up to its per-minute
limit in any 60 seconds (e.g. a 1,200/min key can send 300 requests in 10 seconds;
the 1,201st request inside one 60-second window is rejected). Exceeding a limit returns
429 with a Retry-After header and a JSON body.
| Endpoint | Limit |
|---|---|
/api/v1/ext/lookup |
Per-key sliding window (your key's rate). Profiles are additionally cached 5 min per IP at the origin (IPv4 and IPv6 alike). |
/api/v1/ext/asn, /org, /range, /search |
The same per-key window and concurrency limit as /api/v1/ext/lookup; each call is one enriched lookup (a list page of up to 1,000 rows included). |
/api/v1/pulse/events, /api/v1/pulse/summary |
Per-key sliding window (your key's rate). |
/api/pulse/* (no key) |
120/min per source IP. |
A high per-source-IP flood guard (3,000/min) also applies before authentication; it sits above every key's own limit, so your key's rate is the limit you will actually meet.
Concurrency
Each paid plan also limits concurrent (simultaneous, in-flight) requests per key:
Basic 5, Pro 10, Business
20, Scale 30, Enterprise
100+ (custom). A request beyond the limit returns
429 concurrency_exceeded with Retry-After: 1 — retry as soon as an earlier
request completes. Keyed responses carry X-Concurrency-Limit. A free account key allows
3 at a time and 120 requests/min. Keyless
lookups have no concurrency limit: they are capped at 60 requests/min.
Limits may change during the beta.
Rate-limit headers
Every keyed response — successes and 429s — tells you where you stand, so you
can pace yourself and confirm a limit change from a single response:
| Header | Meaning |
|---|---|
X-RateLimit-Limit | Your key's limit, requests per window. |
X-RateLimit-Remaining | Requests left in the current 60-second window. |
X-RateLimit-Reset | Unix time (seconds) when the oldest counted request leaves the window, freeing capacity. |
X-RateLimit-Window | Window length in seconds (60). |
X-Concurrency-Limit | Your key's limit on simultaneous in-flight requests (paid plans). |
Retry-After | On 429 only: seconds to wait before retrying. |
Plans with a monthly allowance also return X-Quota-Limit, X-Quota-Remaining and
X-Quota-Reset. The keyless worldip.io/{ip} endpoint reports its daily
allowance in the same X-RateLimit-* headers (Reset = next 00:00 UTC) and has a
separate 60/min burst guard.
{ "error": "rate_limited", "retry_after_sec": 42, "limit_per_min": 1200, "remaining": 0, "reset": 1790812842 }
Using your API key on the free endpoint
Send your key as Authorization: Bearer <key> to https://worldip.io/{ip}
(HTTPS only — a key sent over plain HTTP is refused with 403 https_required). With a paid
key, basic lookups become unlimited: no 1,000/day cap and nothing deducted from your plan.
A free account key (create one on your account page) gets
10,000 lookups per UTC day per account at
120/min, 3 at a time
(see below).
- Your key's own limits apply instead of the keyless 60/min burst guard: its concurrency limit
(
X-Concurrency-Limit) and per-minute limit (X-RateLimit-*). - Responses carry
X-Free-Daily-Limit,X-Free-Daily-Remaining,X-Free-Daily-ResetandX-Billing(free-dailywithin the first 1,000/day per requester IP,unlimitedbeyond it — both are free). In the body,_meta.keylessisfalseand_meta.billingmatches. - A free account key instead carries
X-Daily-Limit,X-Daily-RemainingandX-Daily-Reset(its allowance for the UTC day, shared by every key the account has held;_meta.dailyin the body), and returns429 daily_limit_exceededwithRetry-Afteronce it is spent. All free keys used from one network (IP address or IPv6 /64) share a ceiling of 30,000 lookups a day (429 network_daily_limit_exceeded). A free key does not work on/api/v1/ext/*or the Pulse API (403). - The key needs the
ext:readscope. An invalid, disabled or malformed key returns401/403— it is never silently served as keyless. Use the header rather than?key=, which ends up in logs. - Browsers: the endpoint answers the CORS preflight for
Authorizationand exposes all of the headers above.
Errors
Errors use standard HTTP status codes with a JSON body of
{ "error": "...", "message": "..." } (the 429 body is shown above).
| Status | error | Meaning |
|---|---|---|
| 400 | bad_ip | Malformed IPv4 or IPv6 address in the path. Answered before authentication, so it is never counted. |
| 400 | bad_asn, bad_cidr, bad_slug, bad_query, bad_param | Malformed AS number, CIDR, organization slug, search query, or limit/offset/after/nested/family/type (ASN, organization, range and search endpoints; an out-of-range limit is refused, not capped). Answered before authentication, so never counted. |
| 401 | missing_key | No key supplied. Response also sends WWW-Authenticate: Bearer. |
| 401 | malformed_authorization | An Authorization header was sent but not in Bearer <key> form. |
| 401 | invalid_key | Key not recognized or disabled. |
| 403 | forbidden_scope | Key lacks the required scope. |
| 403 | origin_not_allowed | Key is origin-locked; the request Origin/Referer did not match. |
| 403 | ip_not_allowed | Key is IP-locked; caller IP is off the allow-list. |
| 403 | https_required | A key was sent over plain HTTP; use https://. |
| 403 | no_enriched_access | The key’s plan does not include the enriched endpoint. |
| 404 | not_found | The ASN or organization slug is not in the WorldIP database (counted, like any authenticated call). |
| 404 | unknown_endpoint | No such path under /api/v1/ext/asn, /org, /range or /search. |
| 405 | method_not_allowed | Only GET (and OPTIONS) is accepted on the ASN, organization, range and search endpoints. |
| 429 | rate_limited | Rate limit exceeded; retry after retry_after_sec. |
| 429 | concurrency_exceeded | Too many simultaneous requests for your key; retry when one completes. |
| 429 | quota_exceeded | Monthly enriched allowance spent (metered plans); resets at the start of next month. |
| 503 | db_unavailable | Backend temporarily unavailable; retry shortly. |
| 503 | temporarily_unavailable | A brief maintenance window; retry after the Retry-After seconds. |
| 503 | bgp_unavailable, search_unavailable | Routing data (the prefixes endpoint) or search is briefly unavailable; retry after the Retry-After seconds. |
Plans & data tiers
Web lookups on worldip.io are always free and need no signup. The API adds a monthly allowance of enriched lookups and unlocks progressively richer data — proxy/threat classification, trust scoring, live BGP and Web3 node roles — while keeping a free, no-signup tier. Paid plans are not on sale yet; during the beta, keys come with issued.live Plus and Pro (see Beta keys).
| Plan | Price | Enriched / mo | Concurrent | Adds |
|---|---|---|---|---|
| Keyless | $0 | — | 60/min | Basic endpoint only, 1,000/day per IP, no signup. Owner/org, ASN, country, PTR, CIDR, for IPv4 and IPv6. |
| Free | $0 | — | 3 | Basic endpoint with a free account key: 10,000/day per account, 120/min (send it as Authorization: Bearer <key>, HTTPS only). Enriched endpoint requires a paid plan. Create it on your account page. |
| Basic | $9 | 25,000 | 5 | + the enriched endpoint, /24 neighbors, BGP prefix and origin ASN, and the ASN, organization and range lookups and search. |
| Pro | $39 | 200,000 | 10 | + VPN/proxy/Tor/datacenter classification, residential & mobile proxy detection, botnet & compromised-host reputation, access type, trust score. |
| Business | $129 | 1,000,000 | 20 | + MOAS & routing anomalies, the Pulse API, Web3 node roles. |
| Scale | $499 | 5,000,000 | 30 | Everything in Business, at the highest volume, with priority support. |
| Enterprise | Contact us | Custom | 100+ | Custom limits and volume under a written agreement, SLA, dedicated support. |
Annual billing is two months free (~17% off). See full pricing for details. Free account keys are self-serve on your account page; paid plans are not open yet, and during the beta enriched keys come with issued.live Plus and Pro — Beta keys. Limits may change during the beta.
Get launch updates
Paid plans are not open yet (free keys are: create a free account). Drop your email and we'll message you the day they open — and again for major new endpoints. No spam, unsubscribe anytime. Already on issued.live Plus or Pro? Get your free beta key instead.
Frequently Asked Questions
How do I get an API key?
During the beta, keys are issued free to customers of issued.live Plus and Pro, the sister service of WorldIP: we email the key to the address on your issued.live account within one business day (details: worldip.io/developers#beta-keys). Free account keys are self-serve on your account page; paid plans are not open yet. Without a key, the keyless endpoint (curl https://worldip.io/8.8.8.8 — 1,000 lookups/day, no signup) and the public Pulse feeds work today.
Do the web pages and the API share the same data?
Yes. Every field the API returns is the same intelligence rendered on worldip.io — the API just gives you one cached JSON call instead of scraping a page.
What does the /ext/ path mean?
It is the stable path of the keyed IP-intelligence lookup (/api/v1/ext/lookup). Call it server-side with your API key in the Authorization header, over HTTPS; never put a key in browser code or a URL.
Is IPv6 supported?
Yes. worldip.io/{ipv6} (free, no key) returns geolocation (country, plus region and city where available), reverse DNS from our own IPv6 scans, ASN, org name and CIDR. /api/v1/ext/lookup/{ipv6} adds org category, hosting/datacenter classification, IPv6 blocklists and iCloud Private Relay detection, on the same keys, quotas and limits as IPv4. VPN and proxy exit detection, trust score, live BGP and the hosted-domain count are IPv4-only; in an IPv6 profile those fields are null and the unavailable object says why. Most IPv6 reverse-DNS names are generated by the ISP from the address, and rdns.kind flags them.
What format are responses?
JSON, UTF-8. A success is 200 OK with the record at the top level; errors use standard HTTP status codes (400, 401, 403, 429, 503) with a JSON error body.
Does the API return the domains hosted on an IP?
The free keyless endpoint and the MCP tools carry domains_hosted for IPv4 addresses: how many domains are hosted on the address, updated daily from the DNS data of issued.live, WorldIP's sister service. It is a count, not a list. The keyed lookup is unchanged. issued.live's Reverse IP (paid plans) lists the hostnames seen on an address, current and past: https://issued.live/pricing.