Skip to content

Commit

Permalink
BIKESHED
Browse files Browse the repository at this point in the history
  • Loading branch information
@hakanensari
hakanensari committed Aug 23, 2024
1 parent 51b4d83 commit 7c8aa57
Show file tree
Hide file tree
Showing 5 changed files with 132 additions and 145 deletions.
58 changes: 37 additions & 21 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,46 +2,62 @@

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

**Country** is a geolocation API that gets your users' country (and nothing else) from their IP.
Country is an IP-to-country geolocation API that returns a user’s country based on their IP address.

We run a <a href="https://api.country.is">free instance</a>—no API key
needed. You can also self-host if preferred.

## Usage

**Country** has a minimal :fire: interface.
The API has a minimal interface.

Have your browser or app query its own IP address.
### GET /

```
https://api.country.is/
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"
}
```

Query an abitrary IP.
### GET /{ip}

```
https://api.country.is/9.9.9.9
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"
}
```

See the data sources.
### GET /info

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

```
https://api.country.is/info
/* https://api.country.is/info */
{
"dataSources": [
"maxmind",
"cloudflare"
],
"lastUpdated": "2024-08-20T18:34:36.000Z"
}
```

**Country** automatically checks for a newer version every 24 hours.
The API automatically updates MaxMind data every 24 hours in the background.

## Deployment

We run a public instance at [country.is](https://country.is). Alternatively, you can run privately with
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 the `YOUR_MAXMIND_ACCOUNT_ID` and `YOUR_LICENSE_KEY` placeholders with your MaxMind account ID and the license key associated with it.

## Notes

**Country** uses geolocation data provided by [Cloudfare](https://support.cloudflare.com/hc/en-us/articles/200168236-Configuring-IP-geolocation) and [MaxMind](http://dev.maxmind.com/geoip/geoip2/geolite2/).

Since 30 December 2019, you need to [register for a license key](https://www.maxmind.com/en/geolite2/signup) to download the MaxMind data.

Our public instance does not log requests.
Replace `YOUR_MAXMIND_ACCOUNT_ID` and `YOUR_LICENSE_KEY` with your MaxMind account ID and the license key associated with it.
6 changes: 0 additions & 6 deletions docs/_includes/docker.sh
View file

This file was deleted.

13 changes: 7 additions & 6 deletions docs/_layouts/default.html
View file
Original file line number Diff line number Diff line change
@@ -1,16 +1,17 @@
---
layout: compress
---

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="{{ page.description }} | Country.is" />
<title>Country | {{ page.title }}</title>
<link rel="canonical" href="{{ page.url }}" />
<title>{{ page.title }}</title>
<link rel="stylesheet" href="https://fonts.xz.style/serve/inter.css" />
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@exampledev/new.css@latest/new.min.css"
/>
<link rel="stylesheet" href="styles/application.css" />
<script defer src="javascripts/application.js"></script>
<script
defer
src="https://kit.fontawesome.com/d12ab438e8.js"
Expand Down
187 changes: 81 additions & 106 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
@@ -1,111 +1,86 @@
---
layout: compress
layout: default
title: IP-to-Country Geolocation API
---

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta
name="description"
content="Free, open-source IP-to-country geolocation API that finds and returns a user’s country based on their IPv4/IPv6 address"
/>
<link rel="canonical" href="https://country.is/" />
<title>IP-to-Country Geolocation API | Country.is</title>
<script
defer
src="https://kit.fontawesome.com/d12ab438e8.js"
crossorigin="anonymous"
></script>
<script defer src="javascripts/application.js"></script>
<link rel="stylesheet" href="https://fonts.xz.style/serve/inter.css" />
<link rel="stylesheet" href="styles/application.css" />
</head>
<body>
<header>
<i class="fa-sharp-duotone fa-solid fa-earth-americas fa-3x"></i>
<h1>Country</h1>
<a href="https://github.com/hakanensari/country">GitHub</a> /
<a href="https://hub.docker.com/r/hakanensari/country">Docker</a>
<p>
Country is an IP-to-country geolocation API that returns a user’s
country based on their IP address.
</p>
<p>
We offer a <a href="https://api.country.is">free instance</a>—no API key
needed. You can also self-host if preferred.
</p>
</header>
<h2>Usage</h2>
<p>The API has a minimal interface.</p>
<dl>
<dt>GET /</dt>
<dd>
Returns the country of the IP making the request, typically the user’s
browser or app.
</dd>
<dd>
<pre><code data-url="https://api.country.is/"></code></pre>
</dd>
<dt>GET /{ip}</dt>
<dd>
Returns the country of any given IP. The API supports both with IPv4 and
IPv6.
</dd>
<dd>
<pre><code data-url="https://api.country.is/77.1.2.3"></code></pre>
</dd>
<dt>GET /info</dt>
<dd>
Provides metadata about the API, including when the data sources were
last updated.
</dd>
<dd>
<pre><code data-url="https://api.country.is/info"></code></pre>
</dd>
</dl>
<header>
<i class="fa-sharp-duotone fa-solid fa-earth-americas fa-3x"></i>
<h1>Country</h1>
<a href="https://github.com/hakanensari/country">GitHub</a> /
<a href="https://hub.docker.com/r/hakanensari/country">Docker</a>
<p>
Country is an IP-to-country geolocation API that returns a user’s country
based on their IP address.
</p>
<p>
We run a <a href="https://api.country.is">free instance</a>—no API key
needed. You can also self-host if preferred.
</p>
</header>
<h2>Usage</h2>
<p>The API has a minimal interface.</p>
<dl>
<dt>GET /</dt>
<dd>
Returns the country of the IP making the request, typically the user’s
browser or app.
</dd>
<dd>
<pre><code data-url="https://api.country.is/"></code></pre>
</dd>
<dt>GET /{ip}</dt>
<dd>
Returns the country of any given IP. The API supports both with IPv4 and
IPv6.
</dd>
<dd>
<pre><code data-url="https://api.country.is/77.1.2.3"></code></pre>
</dd>
<dt>GET /info</dt>
<dd>
Provides metadata about the API, including when the data sources were last
updated.
</dd>
<dd>
<pre><code data-url="https://api.country.is/info"></code></pre>
</dd>
<dd>
The API automatically updates MaxMind data every 24 hours in the background.
</dd>
</dl>

<p>
The API automatically updates MaxMind data every 24 hours in the
background.
</p>
<h2>Deployment</h2>
<p>
If you prefer not to use our hosted service, you can self-host with Docker.
</p>
<pre><code>docker run -d -p 3000:3000 -e ACCOUNT_ID=YOUR_MAXMIND_ACCOUNT_ID -e LICENSE_KEY=YOUR_MAXMIND_LICENSE_KEY hakanensari/country</code></pre>
<p>
Replace <code>YOUR_MAXMIND_ACCOUNT_ID</code> and
<code>YOUR_LICENSE_KEY</code> with your MaxMind account ID and the
<a href="https://www.maxmind.com/en/geolite2/signup"
>license key associated with it</a
>.
</p>

<h2>Deployment</h2>
<p>
If you prefer not to use our hosted service, you can self-host with
Docker.
</p>
<pre><code>{% include docker.sh %}</code></pre>
<p>
Replace <code>YOUR_MAXMIND_ACCOUNT_ID</code> and
<code>YOUR_LICENSE_KEY</code> with your MaxMind account ID and the
<a href="https://www.maxmind.com/en/geolite2/signup"
>license key associated with it</a
>.
</p>

<h2>Notes</h2>
<ul>
<li>
The API uses geolocation data provided by
<a href="https://www.maxmind.com">MaxMind</a> and optionally
<a
href="https://support.cloudflare.com/hc/en-us/articles/200168236-Configuring-IP-geolocation"
>Cloudfare</a
>.
</li>
<li>
Since 30 December 2019, you need to register for a
<a href="https://www.maxmind.com/en/geolite2/signup">license key</a> to
download the MaxMind data if you're self-hosting.
</li>
<li>
Our public instance rate-limits queries from the same IP at 10 requests
per second. If you need to make more requests server-side, consider
self-hosting or querying the MaxMind data directly.
</li>
<li>The API does not log any requests.</li>
</ul>
</body>
</html>
<h2>Notes</h2>
<ul>
<li>
The API uses geolocation data provided by
<a href="https://www.maxmind.com">MaxMind</a> and optionally
<a
href="https://support.cloudflare.com/hc/en-us/articles/200168236-Configuring-IP-geolocation"
>Cloudfare</a
>.
</li>
<li>
Since 30 December 2019, you need to register for a
<a href="https://www.maxmind.com/en/geolite2/signup">license key</a> to
download the MaxMind data if you're self-hosting.
</li>
<li>
Our public instance rate-limits queries from the same IP at 10 requests per
second. If you need to make more requests server-side, consider self-hosting
or querying the MaxMind data directly.
</li>
<li>The API does not log any requests.</li>
</ul>
13 changes: 7 additions & 6 deletions docs/styles/application.css
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,22 +65,23 @@ dd {
margin: 0;
}

pre {
padding: 1rem 1.4rem;
}

code {
font-family: var(--font-mono);
white-space: pre-wrap;
}

code,
pre {
pre,
code {
background: var(--bg-2);
border: 1px solid var(--bg-3);
border-radius: 4px;
font-size: 0.9em;
}

pre {
padding: 1rem 1.4rem;
}

pre code {
background: inherit;
border: 0;
Expand Down

0 comments on commit 7c8aa57

Please sign in to comment.