# Country: free IP-to-Country geolocation API

Source: https://country.is

## Summary

Country is a free, keyless IP-to-country geolocation API at api.country.is, and its source code is open source and can be self-hosted. It returns the country for an IPv4 or IPv6 address, and optional fields such as city, continent, subdivision, postal code, coordinates, and ASN can be added to a lookup. Batch lookups accept up to 100 addresses per POST request. The FAQ says the data comes from MaxMind GeoLite2 and is updated daily, the API is free for commercial use, and infrastructure rate-limits to 10 requests per second per IP. It also states that requests are not logged and that the service has run since 2015.

## Article

Free IP-to-country geolocation API

GitHub

Country maps IP addresses to countries. It can also return city, continent, subdivision, postal code, coordinates, and ASN.

api.country.is is free and requires no key. The app is open source and can be self-hosted.

Usage

GET /

Returns the country of the caller's IP.

curl https://api.country.is/

GET /{ip}

Returns the country of a given IPv4 or IPv6 address.

curl https://api.country.is/77.1.2.3

POST /

Look up multiple IPs in one request. Send a JSON array of up to 100 addresses.

curl https://api.country.is/ -d ‘["77.1.2.3","93.184.216.34"]’

?fields=

Add extra fields to any lookup: city, continent, subdivision, postal, location, asn.

curl https://api.country.is/77.1.2.3?fields=city,continent,subdivision,postal,location,asn

GET /info

Returns metadata, including when the data was last updated. Data refreshes every 24 hours.

curl https://api.country.is/info

A machine-readable OpenAPI spec is available.

Errors

The API returns standard HTTP status codes.

400

Invalid IP address or malformed request.

404

No data found for the given IP.

429

Rate limit exceeded. Try again shortly.

Self-hosting

Run your own instance with Docker.

# Runs country on port 3000 docker run -d -p 3000:3000 \ -e ACCOUNT_ID=YOUR_MAXMIND_ACCOUNT_ID \ -e LICENSE_KEY=YOUR_MAXMIND_LICENSE_KEY \ -v country-data:/app/data \ --pull always \ lineofflight/country

Get your credentials from MaxMind. For high-volume server-side use, consider self-hosting or querying MaxMind data directly.

Quick answers

Is the API free for commercial use?

Yes.

Are there rate limits?

No quotas. Infrastructure rate-limits to 10 requests per second per IP to prevent abuse.

Where does the data come from?

MaxMind GeoLite2, updated daily. Cloudflare geolocation is used when available.

Do you log requests?

No.

Will the API keep running?

Country has been running since 2015. For critical applications, self-host for full control.

## Comments

**@macbudkowski**: apparently you need this if you run an app that has some gambling features (lottery, betting, etc.)