country.is API
Free IP to country API with no key: returns just the ISO country code for any IP address, in a two-field response. Tested curl example and live response included.
Endpoint tested and returned HTTP 200 on 2026-08-21
What is the country.is API?
country.is is a free, key-free API that maps an IP address to its ISO 3166-1 alpha-2 country code. The response contains only the IP and the country code, which makes it the smallest and fastest option when country is all you need.
Most IP geolocation services answer with thirty fields when the caller wanted one. country.is takes the opposite position: two keys, no configuration, and a payload measured in bytes. For the common cases — choosing a currency, picking a default language, deciding which cookie banner to show — that is genuinely all the information there is to have.
It is also the honest amount of information. Country is the one attribute IP geolocation gets right the overwhelming majority of the time, because it is anchored in the regional registry allocation. City and coordinates come from far softer inference, and every field beyond the country is a guess about where a network is used rather than a record of where it is registered. An API that declines to guess is easier to reason about than one that fills the gap with a country centroid.
Quick facts
- Base URL
https://api.country.is- Authentication
- No key, account or attribution requirement. Free for commercial use.
- Rate limit
- No published quota. The operator asks for reasonable use; the response is tiny, so caching per IP is cheap.
- Pricing
- Free.
- CORS
- Enabled — callable directly from browser JavaScript
- Official docs
- Read the docs
How to use the country.is API
Every request below was executed against the live API on 2026-08-21, and the response shown is the real body it returned — not an illustration.
1. Look up the country for a specific IP address
GET https://api.country.is/8.8.8.8
curl 'https://api.country.is/8.8.8.8'const res = await fetch("https://api.country.is/8.8.8.8");
if (!res.ok) throw new Error(`Request failed: ${res.status}`);
const data = await res.json();
console.log(data);import requests
res = requests.get("https://api.country.is/8.8.8.8", timeout=20)
res.raise_for_status()
print(res.json()){
"ip": "8.8.8.8",
"country": "US"
}Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
ip | path | Optional | The IP to look up, IPv4 or IPv6. Omit it entirely to look up the caller's own address. 8.8.8.8 |
Response fields
ipstring- The address that was looked up — the one you supplied, or your own when the path was empty.
countrystring- ISO 3166-1 alpha-2 country code, uppercase. Nothing else is returned.
What you can build with the country.is API
- Pick a default currency or language for a first-time visitor
- Show the right cookie or privacy notice by jurisdiction
- Route traffic to a regional endpoint
- Apply country-level content licensing rules
- Add a coarse country dimension to analytics without a heavy provider
Common errors and how to fix them
404 for an unallocated IP
The address is in a reserved, private or unassigned range.
Fix: Private ranges such as 10.0.0.0/8 and 192.168.0.0/16 have no country. Detect them before calling rather than treating the 404 as a service failure.
Wrong country for a VPN or proxy user
The lookup reports where the exit node is, which is the point of a VPN.
Fix: No IP database can see past this. If the answer matters legally, ask the user rather than inferring it.
Behind a proxy, every request looks the same
Calling without an IP returns the country of whatever address reached the service.
Fix: Pass the client IP explicitly, taken from `X-Forwarded-For` after validating it, rather than relying on the empty-path form.
Corporate IPs report a headquarters country
Large organisations route staff traffic through central egress points.
Fix: Country from IP is a default, not a fact. Always let the user override it.
country.is API — frequently asked questions
Is country.is free?
Yes, free with no key, account or attribution requirement, and usable commercially. There is no paid tier to upsell you to, which is partly why the response stays minimal.
How accurate is IP to country lookup?
Country is the reliable part of IP geolocation, correct the large majority of the time, because it derives from regional registry allocations. VPNs, proxies and corporate egress routing are the systematic exceptions, and no database can see through them.
Can I look up my own IP?
Yes. Call the base URL with no path segment and it returns the address the request arrived from, along with its country. Behind a proxy or load balancer that will be the proxy's address, not your visitor's.
Why does it not return a city?
Because the design treats city as a guess it would rather not make. City-level IP data is often wrong and, when the registry holds nothing better, falls back to a country centroid presented as a precise point. Country is the field that is actually dependable.
Tools that pair with this API
IP Address Validator
Validate lists of IPv4, IPv6 and CIDR entries with the exact failure reason per line — compressed ::, IPv4-mapped forms and prefixes included. Free.
JSON Formatter
Format, beautify and minify JSON online with 2-space, 4-space or tab indentation. Sort keys alphabetically and catch syntax errors instantly — free and private.
Flag Emoji Generator
Turn ISO 3166-1 country codes into flag emoji, decode flags back into codes, or browse and copy every country flag with its Unicode code points.
country.is is an independent third-party service and is not affiliated with ByteTools or ByteVancer. Details on this page were verified on 2026-08-21; always check the official documentation before relying on this API in production, as terms and limits can change.