- Notifications
You must be signed in to change notification settings - Fork14
A JSON REST API for Maxmind GeoIP databases
License
observabilitystack/geoip-api
Folders and files
| Name | Name | Last commit message | Last commit date | |
|---|---|---|---|---|
Repository files navigation
♻️ 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 fromMaxminds 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 theLogstash http filter plugin to enrich log data.
The Docker image available on Docker Hub comes bundled with a recentGeoLite2 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💡 Although running containers tagged aslatest isnot recommended in production, for geoip-api we highlyrecommend this to have the most up-to-data geoipdata.
- Images are available on bothDocker Hub andGitHub 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
amd64andarm64architectures. - Updates (data & code) are released weekly.
☝️ When running in production, using a commercialMaxmind GeoIP2 City database is highly recommeded due to it's increasedprecision and general data quality.
You can mount the database inmmdb format into the container. The location of the database can be customized using the followingvariables:
| 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) |
Theexamples folder contains examples howto rungeoip-api in Docker-Compose or Kubernetes.
The prefered way to query the API is via simple HTTP GET requests. Supplythe 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"}Geoip-API returns links to extensive absuse and ripe informationin theLink header. Theripe-asn information can be retrieveddirectly. Theabuse link requires registration andan API key for retrieval.
curl"http://localhost:8080/$(curl -s https://ifconfig.me/ip)"HTTP/1.1 200Link:<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"}
TheX-Geoip-Address header is an alternative way to query the api(as used in theNginx-Geoip example). Herethe address to resolve is supplied as header value. The geoip informationis returned as header values as well. The return code is always204.
$ curl -sI -H"X-Geoip-Address:$(curl -s https://ifconfig.me/ip)""http://localhost:8080/"HTTP/1.1 204X-Geoip-Country: DEX-Geoip-StateProv: Free and Hanseatic City of HamburgX-Geoip-City: HamburgX-Geoip-Latitude: 53.6042X-Geoip-Longitude: 10.0596X-Geoip-Continent: EUX-Geoip-Timezone: Europe/Berlin
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.
The project is built through multi stage Docker builds. You needa 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, usetheDocker 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.
We're looking forward to your comments, issues and pull requests!
This project is licensed under theApache License, Version 2.
This product includes GeoLite2 data created by MaxMind, available fromhttps://www.maxmind.com.
About
A JSON REST API for Maxmind GeoIP databases
Topics
Resources
License
Uh oh!
There was an error while loading.Please reload this page.
Stars
Watchers
Forks
Packages0
Uh oh!
There was an error while loading.Please reload this page.
Uh oh!
There was an error while loading.Please reload this page.
Languages
- Java93.7%
- Dockerfile4.5%
- Shell1.8%