Country

aece6e1

Star

Country is a free IP-to-country geolocation API that returns a user’s country based on their IP address.

We run an open instance—no API key needed. If preferred, you can self-host with Docker.

Usage

The API has a minimal interface.

GET /
Returns the country of the IP making the request, typically the user’s browser or app. 
/* curl -s https://api.country.is/ */
GET /{ip}
Returns the country of any given IP. The API supports both with IPv4 and IPv6.
Here, we query .
/* curl -s https://api.country.is/77.1.2.3 */
GET /info
Provides metadata about the API, including when the data sources were last updated. 
/* curl -s https://api.country.is/info */
The API automatically updates MaxMind data every 24 hours in the background.

Our hosted service is ideal for client-side apps. If you require to run high-volume queries server-side, consider self-hosting or querying the MaxMind GeoIP data directly.

Deployment

If you prefer not to use our server, you can self-host with Docker.

# Runs country on port 3000
docker run -d \
  -p 3000:3000 \
  -e ACCOUNT_ID=$MAXMIND_ACCOUNT_ID \
  -e LICENSE_KEY=$MAXMIND_LICENSE_KEY \
  -- pull always \
  hakanensari/country

Set the two environment variables to your MaxMind account ID and the license key associated with it.

Quick answers

Is the API free for commercial use?
Yes, absolutely.
Does the API have any limit of calls?
We rate-limit queries from the same IP to 10 per second; you should use Maxmind's data directly if you run a high volume of queries server-side. The API has no limits in other use cases: web, mobile apps, etc.
Will the API work in the future?
We've been running for a decade and have no plans to shut down. For critical applications, we still recommend self-hosting for control.

Notes

  1. The API uses geolocation data provided by MaxMind and optionally Cloudfare.
  2. Since 30 December 2019, you need to register for a license key to download the MaxMind data if you're self-hosting.
  3. We don't log requests on our server. However, Cloudflare, which we use for caching, aggregates metadata for analytics and performance monitoring.