WhereGo

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:

{
  "City": {
    "Names": {"en": "Mountain View", ...},
    "GeoNameID": 5375480
  },
  "Country": {
    "Names": {"en": "United States", "es": "Estados Unidos", ...},
    "IsoCode": "US",
    "GeoNameID": 6252001,
    "IsInEuropeanUnion": false
  },
  "Continent": {
    "Names": {"en": "North America", ...},
    "Code": "NA",
    "GeoNameID": 6255149
  },
  "Location": {
    "TimeZone": "America/Los_Angeles",
    "Latitude": 37.386,
    "Longitude": -122.0838,
    "MetroCode": 807,
    "AccuracyRadius": 1000
  },
  "Postal": {"Code": "94035"},
  "Subdivisions": [{"Names": {"en": "California"}, "IsoCode": "CA", ...}],
  "RegisteredCountry": {...},
  "RepresentedCountry": {...},
  "Traits": {
    "IsAnonymousProxy": false,
    "IsAnycast": false,
    "IsSatelliteProvider": false
  }
}

Health Check

curl http://localhost:8080/health

Response:

{"status":"ok"}

Performance

Benchmarks on Intel Core i5-12500H:

goos: windows
goarch: amd64
cpu: 12th Gen Intel(R) Core(TM) i5-12500H
BenchmarkLookup-16                107030             11093 ns/op            8131 B/op         85 allocs/op
BenchmarkLookupParallel-16        260906              4364 ns/op            8129 B/op         85 allocs/op

Run benchmarks yourself:

go test -bench=Benchmark -benchmem -run=^$ ./internal/handlers/

Configuration

License

MIT License - see LICENSE for details.