Atlas API — IP Geolocation & ASN Lookup

GET /api/v2/ip/:ip_or_hostname

Full geolocation and network lookup for an IPv4 address, IPv6 address, or resolvable hostname. Returns country, continent, ASN, organisation name, and — as of v0.1 — the most-specific announced BGP prefix covering the IP. Cached for 7 days.

Response fields

Field	Type	Description
ip	string	Resolved IP address. May differ from input when a hostname is provided.
country_code	string	ISO 3166-1 alpha-2 code, e.g. `"AU"`.
country	string	Full country name, e.g. `"Australia"`.
country_flag	string	Unicode flag emoji, e.g. `"🇦🇺"`.
continent	string	Full continent name, e.g. `"Oceania"`.
as_number	number	ASN as an integer, e.g. `13335`.
as_description	string	Organisation name from the routing registry, e.g. `"CLOUDFLARENET"`.
cidrnew	string\|null	Most-specific announced BGP prefix containing this IP, e.g. `"1.1.1.0/24"`. `null` when the ASN has no prefix entries in the database.
error	null\|string	Null on success. Error message on failure.

Example requests

curl https://atlas.ipinfo.app/api/v2/ip/1.1.1.1 curl https://atlas.ipinfo.app/api/v2/ip/2606:4700::1111 curl https://atlas.ipinfo.app/api/v2/ip/cloudflare.com

Example response — 200 OK

{ "ip": "1.1.1.1", "country_code": "AU", "country": "Australia", "country_flag": "🇦🇺", "continent": "Oceania", "as_number": 13335, "as_description": "CLOUDFLARENET", "cidr": "1.1.1.0/24", "error": null }

Error response — 404 Not Found

{ "ip": "127.0.0.1", // private/reserved addresses are not in the database "country_code": null, "country": null, "country_flag": null, "continent": null, "as_number": null, "as_description": null, "cidr": null, "error": "IP address not found in database." }

GET /api/v2/asn/:as_number

Returns all CIDR prefixes announced by an ASN, annotated with country and continent data. Now also includes pre-computed announcement size stats so consumers don't need to iterate the full prefix list. :as_number accepts a bare integer or an AS-prefixed string (e.g. 13335 or AS13335). Cached for 24 hours.

Response fields

Field	Type	Description
as_number	number	The ASN as an integer.
as_description	string	Organisation name from the registry.
ipv4_countnew	number	Total IPv4 host addresses across all announced prefixes (sum of 2^(32−prefixLen)).
ipv6_prefix_countnew	number	Number of IPv6 prefix entries. IPv6 address space is too large to represent as a single sum.
cidrs	object[]	Array of prefix objects.
cidrs[].cidr	string	CIDR notation, e.g. `"1.1.1.0/24"`.
cidrs[].country_code	string	ISO 3166-1 alpha-2 code for this prefix's allocation.
cidrs[].country	string	Full country name for this prefix.
cidrs[].continent	string	Full continent name for this prefix.
error	null\|string	Null on success.

Example requests

curl https://atlas.ipinfo.app/api/v2/asn/AS13335 curl https://atlas.ipinfo.app/api/v2/asn/13335

Example response — 200 OK

{ "as_number": 13335, "as_description": "CLOUDFLARENET", "ipv4_count": 1572864, // total IPv4 addresses announced "ipv6_prefix_count": 4, // number of IPv6 prefix entries "cidrs": [ { "cidr": "1.1.1.0/24", "country_code": "AU", "country": "Australia", "continent": "Oceania" } // ... more prefixes ], "error": null }

Error response — 404 Not Found

{ "as_number": 999999, "as_description": null, "ipv4_count": 0, "ipv6_prefix_count": 0, "cidrs": [], "error": "AS number not found or has no associated CIDRs in the database." }

GET /api/v2/asn/search?q=:query

Search ASNs by multiple input types — automatically detected from the query string. Returns up to 25 matching { as_number, as_description } results.

Input type detection (evaluated in order)

Input	Strategy
CIDR prefixnew	e.g. `1.1.1.0/24` — exact match against the prefix table. Returns the owning ASN.
IP address	e.g. `1.1.1.1` — resolves to the owning ASN via the IP range table.
AS number / "AS1234"	e.g. `13335` or `AS13335` — direct lookup by number, single result.
Org name	e.g. `cloudflare` — case-insensitive partial match against organisation names, up to 25 results.

Example requests

curl "https://atlas.ipinfo.app/api/v2/asn/search?q=cloudflare" curl "https://atlas.ipinfo.app/api/v2/asn/search?q=AS13335" curl "https://atlas.ipinfo.app/api/v2/asn/search?q=1.1.1.1" curl "https://atlas.ipinfo.app/api/v2/asn/search?q=1.1.1.0%2F24" # CIDR — encode the /

Example response — 200 OK

{ "results": [ { "as_number": 13335, "as_description": "CLOUDFLARENET" }, { "as_number": 209242, "as_description": "Cloudflare London" } ], "error": null }

Error response — 404 Not Found

{ "results": [], "error": "No results found for your query." }

GET /api/v2/hop/:ipnew

Traceroute hop annotation — returns the reverse-DNS record, the ASN details, and a best-effort "PoP" (point of presence) match derived from parsing the PTR against known carrier naming conventions (Hurricane Electric, Cogent, GTT, Zayo, Lumen/Level3, NTT). When no carrier pattern fits, a tier-2 "scatter" pass looks for 3-letter IATA hub codes and known city names anywhere in the hostname. Supports IPv4 and IPv6. Auto-generated IPv6 PTRs (e.g. residential Comcast nibble-hex labels) are detected and stripped before matching. Cached for 24 hours; rate-limited to 300 requests/minute per client IP.

Response fields

Field	Type	Description
ip	string	The IP as supplied in the URL.
ip_version	4 \| 6 \| null	Address family. `null` only on 400 errors.
ptr	string\|null	Reverse-DNS hostname. `null` when no PTR is published or lookup timed out (2s).
asn	object\|null	ASN metadata (same shape as `/api/v2/ip`). `null` when the IP is not in the routing table.
asn.number	number	AS number as integer.
asn.name	string	Organisation name from the registry.
asn.country_code	string	ISO 3166-1 alpha-2 country code.
pop	object\|null	Matched PoP annotation, or `null` when nothing matched.
pop.iata	string	Canonical 3-letter IATA code for the PoP city.
pop.city	string	City name.
pop.country	string	ISO alpha-2 country code.
pop.lat / pop.lon	number	Airport coordinates (proxy for PoP location).
pop.matched	string	Origin of the match: `carrier:<suffix>` or `scatter:<token>`.
pop.confidence	"high"\|"medium"\|"low"	`high` = carrier pattern; `medium` = scatter hit whose country agrees with the ASN country; `low` = scatter hit only.
ptr_style	"normal"\|"auto"\|"auto-prefix"\|null	`auto` = PTR was auto-generated (no hint); `auto-prefix` = we stripped the auto label and still matched the suffix.
error	null\|string	Null on success. Error message on 400 (invalid IP) or 429 (rate-limited).

Example requests

curl https://atlas.ipinfo.app/api/v2/hop/184.105.213.157 curl https://atlas.ipinfo.app/api/v2/hop/2001:470:0:68::2 curl https://atlas.ipinfo.app/api/v2/hop/154.54.30.173

Example response — 200 OK (carrier hit, high confidence)

{ "ip": "184.105.213.157", "ip_version": 4, "ptr": "100ge15-1.core1.lax1.he.net", "asn": { "number": 6939, "name": "HURRICANE", "country_code": "US", "country": "United States", "country_flag": "🇺🇸", "continent": "North America" }, "pop": { "iata": "LAX", "city": "Los Angeles", "country": "US", "lat": 33.9425, "lon": -118.408, "matched": "carrier:he.net", "confidence": "high" }, "ptr_style": "normal", "error": null }

Example response — 200 OK (no match)

{ "ip": "8.8.8.8", // google — generic PTR, no PoP hint "ip_version": 4, "ptr": "dns.google", "asn": { /* ... */ }, "pop": null, "ptr_style": "normal", "error": null }

Error response — 429 Too Many Requests

{ "ip": "...", "error": "Rate limit exceeded. Try again in 60 seconds." }

GET /api/v1/country/:ip_or_hostname

Returns the full country name as a plain text string. Ideal for shell pipelines. Accepts IPv4, IPv6, or any resolvable hostname. Cached for 7 days.

Example

curl https://atlas.ipinfo.app/api/v1/country/1.1.1.1 Australia

GET /api/v1/asn/:ip_or_hostname

Returns the bare ASN number as plain text — no "AS" prefix.

Example

curl https://atlas.ipinfo.app/api/v1/asn/1.1.1.1 13335

GET /api/v1/continent/:ip_or_hostname

Returns the full continent name as plain text.

Example

curl https://atlas.ipinfo.app/api/v1/continent/1.1.1.1 Oceania