https://github.com/hakanensari/country

IP-to-country geolocation API
https://github.com/hakanensari/country

geoip geolocation ip-to-country

Last synced: about 3 hours ago
JSON representation

IP-to-country geolocation API

• Host: GitHub
• URL: https://github.com/hakanensari/country
• Owner: hakanensari
• Created: 2015-01-14T12:56:12.000Z (almost 10 years ago)
• Default Branch: main
• Last Pushed: 2024-10-21T05:08:17.000Z (23 days ago)
• Last Synced: 2024-10-30T06:58:37.964Z (14 days ago)
• Topics: geoip, geolocation, ip-to-country
• Language: JavaScript
• Homepage: http://country.is/
• Size: 525 KB
• Stars: 167
• Watchers: 5
• Forks: 19
• Open Issues: 7
• Metadata Files:
  • Readme: README.md

Awesome Lists containing this project

README

        
# Country

[![Build](https://github.com/hakanensari/country/workflows/Build/badge.svg)][action]

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

[We run a free instance][free-instance]—no API key

needed. You can also self-host if preferred.

## Usage

The API has a minimal interface.

### GET /

Returns the country of the IP making the request, typically the user’s browser or app.

```json

/* https://api.country.is/ */

{

  "ip": "77.249.1.1",

  "country": "NL"

}

```

### GET /{ip}

Returns the country of any given IP. The API supports both with IPv4 and IPv6.

```json

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

{

  "ip": "77.1.2.3",

  "country": "DE"

}

```

### GET /info

Provides metadata about the API, including when the data sources were last updated.

```json

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

{

  "dataSources": ["maxmind", "cloudflare"],

  "lastUpdated": "2024-08-20T18:34:36.000Z"

}

```

The API automatically updates MaxMind data every 24 hours in the background.

## Deployment

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

```

docker run -d -p 3000:3000 -e ACCOUNT_ID=YOUR_MAXMIND_ACCOUNT_ID -e LICENSE_KEY=YOUR_MAXMIND_LICENSE_KEY hakanensari/country

```

Replace `YOUR_MAXMIND_ACCOUNT_ID` and `YOUR_LICENSE_KEY` with your MaxMind account ID and the license key associated with it.

[free-instance]: https://api.country.is

[action]: https://github.com/hakanensari/country/actions