tamanois/location-resolver repository overview

⁠Location Resolver

A lightweight FastAPI microservice that resolves location queries via geocoding providers. Designed for LLM agent tool-calling with bounded rate limiting and queueing built in.

⁠Quick Start

cp .env.example .env
# Edit .env: set PROVIDER and API_KEY
docker compose up -d

⁠API

# Health check
curl http://localhost:8000/health
# → {"status":"ok"}

# Resolve a location
curl "http://localhost:8000/resolve?query=Paris"
# → {"formattedAddress":"Paris, France","latitude":48.85...,"longitude":2.34...}

⁠Configuration

⁠docker compose

services:
  location-resolver:
    image: tamanois/location-resolver:latest
    ports:
      - "8000:8000"
    restart: unless-stopped
    env_file:
      - .env
    healthcheck:
      test: ["CMD", "python", "-c", "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 5s

⁠Providers

• Nominatim (free, no key) — OpenStreetMap geocoding. Requires a User-Agent header.
• OpenCage (requires API key) — Commercial geocoding with higher rate limits and confidence scores.

⁠Rate Limiting

Requests are processed one-at-a-time at GLOBAL_RATE_LIMIT per second. Additional requests are queued in a bounded FIFO queue (up to MAX_QUEUE_SIZE). When full, new requests receive HTTP 503.

⁠Image size

~350 MB — based on python:3.10-slim, installs only FastAPI + uvicorn + requests.