Skip to content

README.md

Latest commit

 

History

History
58 lines (44 loc) · 1.74 KB

README.md

File metadata and controls

58 lines (44 loc) · 1.74 KB
Raw

🌍 GeoIP API Service

Go Version Docker

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.