Getting Started with Country.is — Country.is

When to use this API

When you need to determine which country an IP address belongs to, and you want zero auth setup. Country.is returns just the ISO alpha-2 country code — nothing finer — so it's the right tool when a per-country decision (geofencing, regional access control, rough localization) is all you need. If you need city-level precision, timezone, or coordinates, reach for a richer service instead. The keyless, no-signup nature makes it practical for answering one-off user questions in a conversational context without managing credentials.

Looking up a specific IP address's country

"Which country does the IP address 178.198.44.186 come from?" Call GET /{ip} with the address as the path segment. Both IPv4 and IPv6 work.

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

{
  "ip": "178.198.44.186",
  "country": "CH"
}

CH is Switzerland — neutral, not in the EU, but surrounded by EU member states. That distinction matters for certain compliance decisions: Swiss data protection law (nFADP) is EU-equivalent in intent but not identical in mechanism, so routing an IP to CH does not mean you can treat the user as subject to GDPR without a separate check. The country field is always ISO alpha-2 and never a full name, so map it downstream if you're displaying anything to a human.

The IP address 178.198.44.186 is registered in Switzerland (country code CH).

Detecting the caller's country automatically

"Where is the user making this request coming from?" GET / — with no path parameters — resolves the country of whoever is making the HTTP request. The API checks the CF-IPCountry header first (set automatically by Cloudflare's edge), then falls back to the connecting IP.

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

{
  "ip": "2a02:8070:8882:e720:48e2:691:b5a0:95ec",
  "country": "DE"
}

The probed caller here is using an IPv6 address, and the API handles it without ceremony — which not all geolocation services do. The critical operational caveat: if you call GET / from your backend to detect a user's location, you will get your server's country, not the user's. Extract the user's IP from X-Forwarded-For or X-Real-IP request headers and pass it explicitly to GET /{ip}.

Your request appears to be coming from Germany (country code DE).

Checking data freshness and sources

"How up-to-date is the country data?" GET /info returns version and update metadata.

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

{
  "version": "4.2.3",
  "dataSources": ["maxmind", "cloudflare"],
  "lastUpdated": "2026-04-07T07:17:42.000Z"
}

The dual-source approach — MaxMind and Cloudflare — is worth noting. MaxMind's GeoLite2 is the standard reference database for IP geolocation; Cloudflare adds a second opinion drawn from actual observed traffic routing. Neither source is infallible for recently reassigned IP blocks, but two independent sources reduce the gap. Use lastUpdated to sanity-check staleness if a user is asking about something time-sensitive like a recent IP block transfer.

The geolocation data was last updated on April 7, 2026, sourced from MaxMind and Cloudflare.

Pitfalls

GET / returns the server's country in backend contexts. Calling this endpoint server-side resolves the server's IP, not the end-user's. Extract the user's IP from request headers (X-Forwarded-For, X-Real-IP) and use GET /{ip} explicitly.
country is always ISO alpha-2 (CH, DE, US) — never a display name. You will need a lookup table or a secondary call to a country-name API (like REST Countries) before showing anything to a human.
Country-only granularity. There is no region, city, timezone, latitude, or longitude in the response. Any question requiring finer location detail cannot be answered by this API alone.

One-line summary for the user

I can look up the country for any IPv4 or IPv6 address using country.is — no auth required — but the response is a two-letter country code only, with no city, region, or coordinate detail.