A lightweight Go REST API service for IP geolocation and ASN lookups. GIPI uses MMDB databases to provide fast, local lookups without external API calls at query time.
- IP geolocation (country, continent, coordinates)
- ASN information (AS number, name, domain)
- Supports both IPInfo and MaxMind GeoLite2 databases
- Automatic database updates via cron
- Hot-reload of databases without service restart
- Multiple response formats (JSON, XML, plain text)
- Swagger/OpenAPI documentation
# Build
go build ./cmd/gipi
# Run with IPInfo token
GIPI_IPINFO_TOKEN=your_token ./gipi
# Or run with config file
./gipi -config /path/to/config.yamlGIPI loads configuration from config.yaml or /etc/gipi/config.yaml. Environment variables with the GIPI_ prefix override config file values.
| Config Key | Env Variable | Description |
|---|---|---|
server.port |
GIPI_SERVER_PORT |
HTTP port (default: 8080) |
server.ip_header |
GIPI_SERVER_IP_HEADER |
Header for client IP extraction (e.g., X-Forwarded-For) |
server.trusted_proxies |
- | List of trusted proxy IPs |
| Config Key | Env Variable | Description |
|---|---|---|
ipinfo.token |
GIPI_IPINFO_TOKEN |
IPInfo API token for database downloads |
ipinfo.path |
GIPI_IPINFO_PATH |
Path to MMDB file (default: ./data/ipinfo_lite.mmdb) |
ipinfo.auto_update |
GIPI_IPINFO_AUTO_UPDATE |
Enable automatic updates (default: true) |
ipinfo.cron_schedule |
GIPI_IPINFO_CRON_SCHEDULE |
Update schedule (default: weekly Sunday midnight) |
ipinfo.disabled |
GIPI_IPINFO_DISABLED |
Disable IPInfo provider |
| Config Key | Env Variable | Description |
|---|---|---|
maxmind.account_id |
GIPI_MAXMIND_ACCOUNT_ID |
MaxMind account ID |
maxmind.license_key |
GIPI_MAXMIND_LICENSE_KEY |
MaxMind license key |
maxmind.editions |
- | Editions to download (City, Country, ASN) |
maxmind.base_path |
GIPI_MAXMIND_BASE_PATH |
Base directory for databases |
maxmind.auto_update |
GIPI_MAXMIND_AUTO_UPDATE |
Enable automatic updates (default: true) |
maxmind.cron_schedule |
GIPI_MAXMIND_CRON_SCHEDULE |
Update schedule (default: weekly Wednesday midnight) |
maxmind.disabled |
GIPI_MAXMIND_DISABLED |
Disable MaxMind provider |
All endpoints are under /api/v1/ and support both GET and POST methods.
Interactive API documentation available at /api/docs/.
This project uses geolocation data from:
-
IPInfo - IP address data and API services. The free IPInfo Lite database provides country and ASN data.
-
MaxMind GeoLite2 - This product includes GeoLite2 data created by MaxMind, available from https://www.maxmind.com.
See LICENSE for details.