WhereGo

README

WhereGo

🚀 The fastest and lightweight open-source IP geolocation API built with Go and Echo.

Features

• ⚡ Ultra-fast - ~1ms per lookup
• 🌐 Multi-language - Location names in 8 languages
• 🐳 Docker ready - Multi-arch images (amd64/arm64)
• 📦 Tiny image - ~40MB distroless container
• 🛡️ Production ready - Health checks, graceful shutdown

Quick Start

Docker

docker run -p 8080:8080 gustavosett/wherego:latest

From Source

git clone https://github.com/gustavosett/WhereGo.git
cd WhereGo
go run ./cmd/api

API Endpoints

Lookup IP

curl http://localhost:8080/lookup/8.8.8.8

Response:

{
    "traits": {
        "ip_address": "8.8.8.8",
        "network": "8.8.8.0/24",
        "is_anycast": false
    },
    "postal": {
        "code": ""
    },
    "continent": {
        "names": {
            "de": "Nordamerika",
            "en": "North America",
            "es": "Norteamérica",
            "fr": "Amérique du Nord",
            "ja": "北アメリカ",
            "pt-BR": "América do Norte",
            "ru": "Северная Америка",
            "zh-CN": "北美洲"
        },
        "code": "NA",
        "geoname_id": 6255149
    },
    "city": {
        "names": {
            "de": "",
            ...
        },
        "geoname_id": 0
    },
    "subdivisions": null,
    "represented_country": {
        "names": {
            "de": "",
            ...
        },
        "iso_code": "",
        "type": "",
        "geoname_id": 0,
        "is_in_european_union": false
    },
    "country": {
        "names": {
            "de": "USA",
            "en": "United States",
            "es": "Estados Unidos",
            "fr": "États Unis",
            "ja": "アメリカ",
            "pt-BR": "EUA",
            "ru": "США",
            "zh-CN": "美国"
        },
        "iso_code": "US",
        "geoname_id": 6252001,
        "is_in_european_union": false
    },
    "registered_country": {
        "names": {
            "de": "USA",
            "en": "United States",
            "es": "Estados Unidos",
            "fr": "États Unis",
            "ja": "アメリカ",
            "pt-BR": "EUA",
            "ru": "США",
            "zh-CN": "美国"
        },
        "iso_code": "US",
        "geoname_id": 6252001,
        "is_in_european_union": false
    },
    "location": {
        "latitude": 37.751,
        "longitude": -97.822,
        "time_zone": "America/Chicago",
        "metro_code": 0,
        "accuracy_radius": 1000
    }
}

Health Check

curl http://localhost:8080/health

Performance

Load Test Results (K6)

Tests performed on a Docker container restricted to 8 CPUs:

Metric	Result	Status
Throughput	34,214 req/s	🚀 Ultra Fast
Latency (Mean)	1.04 ms	⚡ Instant
Latency (P95)	2.12 ms	⚡ Consistent
Success Rate	100%	✅ Stable
Total Requests	6,842,910	(Zero failures)

Configuration

Environment Variable	Default	Description
PORT	8080	Server port

Architecture

WhereGo is designed for high performance and low resource usage.

• Language: Go 1.24
• Web Framework: Echo v4 (Fast HTTP router)
• Database: MaxMind MMDB (Memory-mapped for speed)
• JSON Serialization: json-iterator (Faster than stdlib)
• Container: Distroless (Secure and lightweight)

Roadmap

• automation to update the database
• Increase test coverage
• gRPC endpoint
• Built-in rate limiting

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

License

MIT License - see LICENSE for details.