IP Geolocation REST API

♻️ This is the official and maintained fork of the original @shopping24 repository maintained by @tboeghk.

This project provides a simple REST web service which returns geolocation information for a given IP address. The service loads location information from Maxminds GeoLite2 or GeoIP2 City (commercial) database.

You can use this project in a microservice infrastructure if you have multiple services requesting geolocation data. This service can be used together with the Logstash http filter plugin to enrich log data.

• Running the container
• Using the API
• Kubernetes & Docker-Compose Examples

💨 Running the container

The Docker image available on Docker Hub comes bundled with a recent GeoLite2 city database. The container is built every week with a recent version of the database.

$ docker run -p 8080:8080 ghcr.io/observabilitystack/geoip-api:latest

$ docker run -p 8080:8080 observabilitystack/geoip-api:latest

Available tags & repositories

💡 Although running containers tagged as latest is not recommended in production, for geoip-api we highly recommend this to have the most up-to-data geoip data.

• Images are available on both Docker Hub and GitHub Container Registry.
• The images are tagged in yyyy-VV (year & week number) format.
• The most recent container is tagged as latest.
• Images are available for amd64 and arm64 architectures.
• Updates (data & code) are released weekly.

Using a custom (commercial) database

☝️ When running in production, using a commercial Maxmind GeoIP2 City database is highly recommeded due to it's increased precision and general data quality.

You can mount the database in mmdb format into the container. The location of the database can be customized using the following variables:

Variable	Description	Default value
CITY_DB_FILE	The location of the GeoIP2 City or GeoLite2 database file.	/srv/GeoLite2-City.mmdb
ASN_DB_FILE	The location of the GeoIP2 ASN database file.	/srv/GeoLite2-ASN.mmdb
ISP_DB_FILE	The location of the GeoIP2 ISP database file.	(none)

Examples

The examples folder contains examples how to run geoip-api in Docker-Compose or Kubernetes.

🤓 Using the API

The prefered way to query the API is via simple HTTP GET requests. Supply the ip address to resolve as path variable.

$ curl -s http://localhost:8080/8.8.8.8
{
  "country": "US",
  "latitude": "37.751",
  "longitude": "-97.822",
  "continent": "NA",
  "timezone": "America/Chicago",
  "accuracyRadius": 1000,
  "asn": 15169,
  "asnOrganization": "GOOGLE",
  "asnNetwork": "8.8.8.0/24"
}
$ curl -s "http://localhost:8080/$(curl -s https://ifconfig.me/ip)"
{
  "country": "DE",
  "stateprov": "Free and Hanseatic City of Hamburg",
  "stateprovCode": "HH",
  "city": "Hamburg",
  "latitude": "53.5742",
  "longitude": "10.0497",
  "continent": "EU",
  "timezone": "Europe/Berlin",
  "asn": 15943,
  "asnOrganization": "wilhelm.tel GmbH"
}

Additional data links

Geoip-API returns links to extensive absuse and ripe information in the Link header. The ripe-asn information can be retrieved directly. The abuse link requires registration and an API key for retrieval.

curl  "http://localhost:8080/$(curl -s https://ifconfig.me/ip)"
HTTP/1.1 200
Link: <https://api.abuseipdb.com/api/v2/check?ipAddress=104.151.58.228>; rel="abuse",
      <https://stat.ripe.net/data/as-overview/data.json?resource=8881>; rel="ripe-asn"

{
  "country": "DE",
  "stateprov": "Land Berlin",
  "stateprovCode": "BE",
  "city": "Berlin",
  "latitude": "52.5196",
  "longitude": "13.4069",
  "continent": "EU",
  "timezone": "Europe/Berlin",
  "accuracyRadius": 200,
  "asn": 8881,
  "asnOrganization": "1&1 Versatel Deutschland GmbH",
  "asnNetwork": "104.151.0.0/17"
}

Querying by HTTP header

The X-Geoip-Address header is an alternative way to query the api (as used in the Nginx-Geoip example). Here the address to resolve is supplied as header value. The geoip information is returned as header values as well. The return code is always 204.

$ curl -sI -H "X-Geoip-Address: $(curl -s https://ifconfig.me/ip)" "http://localhost:8080/"
HTTP/1.1 204
X-Geoip-Country: DE
X-Geoip-StateProv: Free and Hanseatic City of Hamburg
X-Geoip-City: Hamburg
X-Geoip-Latitude: 53.6042
X-Geoip-Longitude: 10.0596
X-Geoip-Continent: EU
X-Geoip-Timezone: Europe/Berlin

Querying multiple IPs via POST

curl --location 'http://localhost:8080/' \
--header 'Content-Type: application/json' \
--data '[
    "8.8.8.8",
    "8.8.4.4"
]'

{
  "8.8.4.4": {
    "country":"US",
    "latitude":"37.751",
    "longitude":"-97.822",
    "continent":"NA",
    "timezone":"America/Chicago",
    "accuracyRadius":1000,
    "asn":15169,
    "asnOrganization":"GOOGLE",
    "asnNetwork":"8.8.4.0/24"
  },
  "8.8.8.8": {
    "country":"US",
    "latitude":"37.751",
    "longitude":"-97.822",
    "continent":"NA",
    "timezone":"America/Chicago",
    "accuracyRadius":1000,
    "asn":15169,
    "asnOrganization":"GOOGLE",
    "asnNetwork":"8.8.8.0/24"
  }
}

Takes up to 100 addresses at once.

Result will be a JSON object indexed by requested IP address.

If a requested address can not be resolved, the entry will be missing in the response.

📦 Building the project

The project is built through multi stage Docker builds. You need a valid Maxmind lincense key to download the Geoip2 database.

$ export MAXMIND_LICENSE_KEY=...
$ docker build \
    --build-arg MAXMIND_LICENSE_KEY=${MAXMIND_LICENSE_KEY} \
    --build-arg VERSION=$(date +%Y-%V) \
    -t geoip-api:latest .

If you want to build (or test) a multi-platform build, use the Docker Buildx extension:

$ docker buildx create --use --name multi-platform
$ docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --build-arg MAXMIND_LICENSE_KEY=${MAXMIND_LICENSE_KEY} \
    -t geoip-api:latest-native -f Dockerfile.native .

👋 Contributing

We're looking forward to your comments, issues and pull requests!

⚖️ License

This project is licensed under the Apache License, Version 2.

This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.