Country

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 \
  hakanensari/country

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

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.