Getting Started with country.is — Country

When to use this API

When you need to map an IP address to its country and nothing more. No API key, no sign-up — pass an IPv4 or IPv6 address in the path and get a two-letter ISO country code back. If you also need city, region, ASN, or timezone data, reach for a fuller geolocation service; country.is answers exactly one question.

Looking up the country for a specific IP address

"What country is the IP address 185.220.101.45 registered to?" The main endpoint takes any IP address directly in the URL path and returns a minimal two-field object.

curl "https://api.country.is/8.8.8.8" | head -c 10000

{
  "ip": "8.8.8.8",
  "country": "US"
}

The only probe example in the DB is for 8.8.8.8 — Google's public DNS, a dull first test but a clean one. country is always ISO 3166-1 alpha-2: two uppercase letters, never a full name, never alpha-3. If you need "United States" rather than "US", resolve the code yourself — country.is returns no display names. The endpoint supports both IPv4 and IPv6 with the same path structure and the same two-field response.

8.8.8.8 is registered to the United States (country code: US). That's Google's public DNS infrastructure — the registration reflects their US network, not an end-user location.

Detecting a visitor's country using the Cloudflare integration

"How do I geolocate the user making a request to my server without passing their IP through my app code?" The GET / endpoint — no path parameter — returns the country for the IP that made the HTTP request. Called directly from your backend, that's your server's IP. The useful case is when your server sits behind Cloudflare: country.is reads the CF-IPCountry request header, which Cloudflare injects with the visitor's actual country before forwarding. The response shape is identical to GET /{ip}.

curl "https://api.country.is/" | head -c 10000

{
  "ip": "8.8.8.8",
  "country": "US"
}

The ip field in the response tells you which IP was actually resolved, so you can tell at a glance whether you got the visitor's IP or your server's — a useful sanity check when debugging the Cloudflare path. Without Cloudflare, GET / is just syntactic sugar for calling GET /{your-server-ip}, which is rarely what you want for visitor detection.

To geolocate your visitors via country.is: if your server is behind Cloudflare, call GET / — Cloudflare's CF-IPCountry header does the work automatically. If not, extract the visitor's IP from your request headers (e.g., X-Forwarded-For) and call GET /{ip} directly.

Pitfalls

country is ISO alpha-2 only. You get "DE", not "Germany". Pair with a lookup table or the REST Countries API if you need a display name.
GET / returns your server's country, not your visitor's — unless your server is behind Cloudflare, which injects CF-IPCountry. On a raw VPS without Cloudflare, pass the visitor's IP explicitly to GET /{ip}.
No sub-country data. City, region, ASN, and timezone are not available. country is the terminal resolution.
Check data freshness with GET /info. That endpoint returns when the underlying GeoIP data sources were last updated — useful if you suspect stale results for recently-reassigned IP blocks.

One-line summary for the user

I can look up the country for any IPv4 or IPv6 address using country.is — no API key required, but the response is only a two-letter ISO country code with no city, region, or display name.