hibare / gogeoip

GeoIP Rest API

GoGeoIP

A fully self-hosted Rest IP to fetch Geo information for an IP. Geo information such as City, Country, ASN, Organization etc., details.

Rest API depends on MaxMind City, Country & ASN Lite database.

MaxMind offers City, Country & ASN Lite databases for free for individual uses.

The program downloads City, Country and ASN databases from MaxMind and runs lookups on local DB.

1. Features
2. Getting Started
3. Endpoints
4. CLI
5. Environment Variables
6. Contributing

Features

• Rest API to translate IP to Geo info
• Automatically download, verify and load MaxMind lite databases on boot.
• Regularly run jobs to update MaxMind local databases.
• No API lookup limits.

Getting Started

GoGeoIP is packaged as docker container. Docker image is available on Docker Hub.

To use GoGeoIP, you require MaxMind license key to download lite databases. Head over to MaxMind and sign-up for a free account.

Get MaxMind License Key

• Login to MaxMind
• Click on Manage License Keys in left side menu.
• Click on Generate new license key, fill out description and click confirm.
• Save license key safely

Docker run

docker run -it -p 5000:5000 -e DB_LICENSE_KEY=<LICENSE_KEY> -e API_LISTEN_ADDR=0.0.0.0 -e API_KEYS=test-key hibare/go-geo-ip

Replace <LICENSE_KEY> with the license key from MaxMind. Replace test-key with randomly generated API key. This is used to authenticate all IP lookup rest calls.

INFO[0000] Loaded config
INFO[0000] Downloading all DB files
INFO[0000] Downloading DB file, path=/tmp/GeoLite2-Country.tar.gz
INFO[0000] Scheduling DB update job
INFO[0003] Downloaded DB file, path=/tmp/GeoLite2-Country.tar.gz
INFO[0003] Downloading sha256 file, path=/tmp/GeoLite2-Country.tar.gz.sha256
INFO[0005] Downloaded sha256 file, path=/tmp/GeoLite2-Country.tar.gz.sha256
INFO[0005] Checksum validated for archive /tmp/GeoLite2-Country.tar.gz
INFO[0005] Extracting file GeoLite2-Country.mmdb from archive /tmp/GeoLite2-Country.tar.gz
INFO[0005] Extracted file GeoLite2-Country.mmdb from archive /tmp/GeoLite2-Country.tar.gz at /tmp/GeoLite2-Country.mmdb
INFO[0005] Loading new DB file data/GeoLite2-Country.mmdb
INFO[0005] New DB file loaded data/GeoLite2-Country.mmdb
INFO[0005] Downloading DB file, path=/tmp/GeoLite2-City.tar.gz
INFO[0013] Downloaded DB file, path=/tmp/GeoLite2-City.tar.gz
INFO[0013] Downloading sha256 file, path=/tmp/GeoLite2-City.tar.gz.sha256
INFO[0014] Downloaded sha256 file, path=/tmp/GeoLite2-City.tar.gz.sha256
INFO[0014] Checksum validated for archive /tmp/GeoLite2-City.tar.gz
INFO[0014] Extracting file GeoLite2-City.mmdb from archive /tmp/GeoLite2-City.tar.gz
INFO[0015] Extracted file GeoLite2-City.mmdb from archive /tmp/GeoLite2-City.tar.gz at /tmp/GeoLite2-City.mmdb
INFO[0015] Loading new DB file data/GeoLite2-City.mmdb
INFO[0015] New DB file loaded data/GeoLite2-City.mmdb
INFO[0015] Downloading DB file, path=/tmp/GeoLite2-ASN.tar.gz
INFO[0017] Downloaded DB file, path=/tmp/GeoLite2-ASN.tar.gz
INFO[0017] Downloading sha256 file, path=/tmp/GeoLite2-ASN.tar.gz.sha256
INFO[0018] Downloaded sha256 file, path=/tmp/GeoLite2-ASN.tar.gz.sha256
INFO[0018] Checksum validated for archive /tmp/GeoLite2-ASN.tar.gz
INFO[0018] Extracting file GeoLite2-ASN.mmdb from archive /tmp/GeoLite2-ASN.tar.gz
INFO[0018] Extracted file GeoLite2-ASN.mmdb from archive /tmp/GeoLite2-ASN.tar.gz at /tmp/GeoLite2-ASN.mmdb
INFO[0018] Loading new DB file data/GeoLite2-ASN.mmdb
INFO[0018] New DB file loaded data/GeoLite2-ASN.mmdb
INFO[0018] Listening for address 0.0.0.0 on port 5000

Docker Compose

Create a .env file and copy the content from .env.example. Alternatively, rename .env.example to .env. Replace values of all variables in .env file with appropriate values.

A minimalistic docker-compose.yml file is provided in the repo. Download docker-compose.yml file.

curl https://raw.githubusercontent.com/hibare/GoGeoIP/main/docker-compose.yml -o docker-compose.yml

Run docker-compose.yml file

docker compose up

Endpoints

1. Check health [GET] /api/v1/health

❯ curl http://127.0.0.1:5000/api/v1/health

{ "ok": true }

2. IP Geo [GET] /api/v1/ip/{lookup_ip}

❯ curl -H "Authorization: test-key" http://127.0.0.1:5000/api/v1/ip/8.8.8.8

3. What is My IP [GET] /api/v1/ip/

❯ curl -H http://127.0.0.1:5000/api/v1/ip/

{
  "city": "",
  "country": "United States",
  "continent": "North America",
  "iso_country_code": "US",
  "iso_continent_code": "NA",
  "is_anonymous_proxy": false,
  "is_satellite_provider": false,
  "timezone": "America/Chicago",
  "latitude": 37.751,
  "longitude": -97.822,
  "asn": 15169,
  "organization": "GOOGLE",
  "ip": "8.8.8.8"
}

Cli

GoGeoIP also has cli commands for quick actions. Binary is go_geo_ip.

For docker containers prefix all commands with docker exec -it {container_name}

❯ go_geo_ip -h

API to fetch Geo information for an IP

Usage:
  go_geo_ip [command]

Available Commands:
  completion  Generate the autocompletion script for the specified shell
  db          IP DB related commands
  geoip       Lookup Geo information for an IP
  help        Help about any command
  keys        Manage API Keys
  serve       Start API Server

Flags:
  -h, --help      help for go_geo_ip
  -v, --version   version for go_geo_ip

Use "go_geo_ip [command] --help" for more information about a command.

Start API Server

❯ go_geo_ip serve

Download DB

❯ go_geo_ip db download

List API Keys

❯ go_geo_ip keys list

Version

❯ go_geo_ip --version

Environment Variables

Variable	Description	Required	Default Value	Value Type
API_LISTEN_ADDR	IP address to bind API server	No	0.0.0.0	string
API_LISTEN_PORT	Port to listen	No	5000	int
API_KEYS	Comma separated API keys to authenticated REST calls	No	Auto generated during runtime	comma separated string
DB_LICENSE_KEY	MaxMind License key	Yes	-	string
DB_AUTOUPDATE	Flag to enable/disable DB auto-update	No	true	boolean
DB_AUTOUPDATE_INTERVAL	Auto update interval.	No	24 Hours	Time duration (ex: 24h, 1h, 6h)

Contributing

Requirements

To participate in GoGepIP development, ensure you have the most up-to-date versions of Go, Docker, and make installed. While we suggest using vscode for development, other IDEs are also suitable.

Run Local Service

make api-up

Build Docker image

make docker-build

Run tests

make test

gogeoip's Issues

Fix code scanning alert - Clear-text logging of sensitive information

Tracking issue for:

• https://github.com/hibare/GoGeoIP/security/code-scanning/1