# Yoro

**Geographic addressing via Hilbert curves — GPS ↔ compact alphanumeric codes.**

*"Yoro" means "place" in Manding (West Africa).*

---

Yoro encodes any GPS coordinate into a short, human-readable code like `CI-NW64D`, and decodes it back. It uses [Hilbert space-filling curves](https://en.wikipedia.org/wiki/Hilbert_curve) to map 2D geographic space into a 1D index, then encodes that index in base-29 (an alphabet designed to avoid ambiguous characters like `0/O`, `1/I/L`).

## Why Yoro?

In many parts of Africa, **street addresses don't exist**. Field agents, cooperatives, and logistics operators need a way to identify locations that is:

- **Short** — `CI-NW64D` (5 characters + domain) vs. `6.80000732, -5.29961548`
- **Hierarchical** — longer codes = finer precision, and codes in the same area share prefixes
- **Offline** — pure math, no database or API call needed to encode/decode
- **Domain-scoped** — each country has its own bounding box for maximum resolution

## Install

```bash
pip install yoro
```

With optional integrations:

```bash
pip install yoro[django]      # Django/GeoDjango model + views
pip install yoro[fastapi]     # FastAPI HTTP server
pip install yoro[all]         # everything
```

## Quick example

```python
import yoro

# Encode Abidjan coordinates
code = yoro.encode(5.345, -4.028, domain="CI")
print(code)  # "CI-PV9XD"

# Decode back
result = yoro.decode(code)
print(result["lat"], result["lon"])  # 5.345..., -4.028...
print(result["bounds"])  # cell bounding box

# Find neighbors
for neighbor in yoro.neighbors(code):
    print(neighbor)

# Explore available precision levels
for level in yoro.precision_levels(domain="CI"):
    print(f"p={level['precision']}: {level['code_length']} chars, ~{level['resolution_m']}m")
```

## Architecture

Yoro is structured in three layers:

| Layer | Install | Dependencies |
|-------|---------|-------------|
| **Core** (`import yoro`) | `pip install yoro` | None (pure Python) |
| **Django** (`yoro.django`) | `pip install yoro[django]` | Django ≥ 4.2, GeoDjango |
| **FastAPI** (`yoro.fastapi`) | `pip install yoro[fastapi]` | FastAPI, uvicorn |

The core codec has **zero dependencies** — only the Python standard library (`math`). It works anywhere Python runs: servers, mobile (via Kivy/BeeWare), embedded, WASM.

## Theory

Yoro was designed by **Paul Guindo** at [Altius Academy SNC](https://altius-group.ch) for agricultural traceability in West Africa (EUDR compliance, cocoa supply chains).

The algorithm is a bijection between GPS coordinates and compact alphanumeric codes using 2D Hilbert curves. The mathematical foundations are described in the [How It Works](concepts/how-it-works.md) section.
