# FastAPI Integration

## Setup

```bash
pip install yoro[fastapi]
```

## Standalone Server

The fastest way to run a Yoro API:

```bash
yoro serve --port 8000
```

Or with Python:

```bash
python -m yoro.fastapi
```

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

## Embed in Your App

```python
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:**

```json
{
  "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`
