🌍 GeoIP API Service

A lightweight, fast, and free IP geolocation lookup API service built with Go and powered by MaxMind's GeoLite2 database.

Features

• High Performance - Built with Go for optimal speed and low memory footprint
• Detailed Geolocation - Returns country, city, coordinates, postal code, and timezone
• Graceful Shutdown - Finishes active requests before stopping

Quick Start

Prerequisites:

• Docker and Docker Compose installed on your machine

• Download the latest free version of the GeoLite2 City database from MaxMind. You will need to create a free account to access the download link.

• Extract the downloaded file and place the GeoLite2-City.mmdb file in the project root.

• Start the service

docker compose up -d

Health Check:

curl -i http://localhost:8888/healthz

Example Request:

curl http://localhost:8888/172.68.100.190

Example Response:

{
  "ip": "172.68.100.190",
  "country": "Portugal",
  "country_code": "PT",
  "city": "Lisbon",
  "postal_code": "1000-005",
  "latitude": 38.7219,
  "longitude": -9.1398,
  "timezone": "Europe/Lisbon"
}

Architecture

• Web Framework: Go standard library (net/http)
• Database: MaxMind GeoLite2-City (MMDB format)
• Database Reader: maxminddb-golang

License

This project is licensed under the MIT License.