Skip to content

FastAPI Integration

Setup

pip install yoro[fastapi]

Standalone Server

The fastest way to run a Yoro API:

yoro serve --port 8000

Or with Python:

python -m yoro.fastapi

This starts a uvicorn server with automatic OpenAPI docs at /docs.

Embed in Your App

from yoro.fastapi import create_app

# Standalone
app = create_app()

# With URL prefix
app = create_app(prefix="/api/v1/geo")

Endpoints

GET /encode

Encode GPS coordinates to a Yoro code.

Parameter Type Default Description
lat float required Latitude (WGS 84)
lon float required Longitude (WGS 84)
domain string "CI" ISO domain code
precision int 12 Hilbert order (1-20)

Response:

{
  "code": "CI-PV9XD",
  "lat": 5.34519287,
  "lon": -4.02868774,
  "precision": 12,
  "resolution_m": 172.9,
  "bounds": {
    "lat_min": 5.34441406,
    "lat_max": 5.34597168,
    "lon_min": -4.02943359,
    "lon_max": -4.02794189
  }
}

GET /decode

Decode a Yoro code to GPS coordinates.

Parameter Type Description
code string Yoro code (e.g. CI-PV9XD)

Response includes neighbors (8 adjacent cell codes).

GET /precisions

List canonical precision levels for a domain.

Parameter Type Default Description
domain string "CI" ISO domain code
max_code_length int 10 Max characters to show

GET /domains

List all available domains with bounding boxes.

GET /health

Health check. Returns {"status": "ok", "version": "..."}.

OpenAPI / Swagger

When running, interactive API docs are available at:

  • Swagger UI: http://localhost:8000/docs
  • ReDoc: http://localhost:8000/redoc