# Quick Start

## Encode a GPS coordinate

```python
import yoro

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

The result is a string like `CI-PV9XD` where:

- `CI` — the domain (Cote d'Ivoire)
- `PV9XD` — the Hilbert cell index in base-29

## Decode a code

```python
result = yoro.decode("CI-PV9XD")
```

Returns a dict:

```python
{
    "lat": 5.34519287,
    "lon": -4.02868774,
    "precision": 12,
    "domain": "CI",
    "bounds": {
        "lat_min": 5.34441406,
        "lat_max": 5.34597168,
        "lon_min": -4.02943359,
        "lon_max": -4.02794189,
    },
}
```

The `lat`/`lon` is the **center** of the Hilbert cell. The `bounds` give the exact cell rectangle.

## Find neighbors

```python
neighbors = yoro.neighbors("CI-PV9XD")
# Returns up to 8 adjacent cell codes
```

## Check resolution

```python
# What resolution does precision 12 give for Cote d'Ivoire?
meters = yoro.resolution(12, domain="CI")
print(f"{meters:.1f} m")  # 172.9 m
```

## See all precision levels

```python
for level in yoro.precision_levels(domain="CI"):
    print(
        f"p={level['precision']:>2}, "
        f"{level['code_length']} chars, "
        f"~{level['resolution_m']:.1f} m"
    )
```

Output:

```
p= 2, 1 chars, ~177045.0 m
p= 4, 2 chars, ~44261.2 m
p= 7, 3 chars, ~5532.7 m
p= 9, 4 chars, ~1383.2 m
p=12, 5 chars, ~172.9 m      ← default
p=14, 6 chars, ~43.2 m
p=17, 7 chars, ~5.4 m
p=19, 8 chars, ~1.4 m
p=21, 9 chars, ~0.3 m
p=24, 10 chars, ~0.0 m
```

## Control precision

```python
# Low precision (neighborhood level)
yoro.encode(5.345, -4.028, precision=7, domain="CI")   # "CI-B4J" (3 chars)

# High precision (meter-level)
yoro.encode(5.345, -4.028, precision=19, domain="CI")  # "CI-XXXXXXXX" (8 chars)

# Check what precision you'll actually get
yoro.snap_precision(18)  # 19 — p=18 snaps to canonical p=19
```

## Use in Django models

```python
from django.db import models
from yoro.django.fields import YoroField

class Shop(models.Model):
    name = models.CharField(max_length=100)
    address = YoroField(domain="CI", precision=12)
```

The `address` field:

- Stores `"CI-PV9XD"` in the database (a simple `CharField`)
- Auto-encodes from tuples: `shop.address = (5.345, -4.028)`
- Renders an **interactive Leaflet map picker** in forms and Django admin
- Validates Yoro codes on form submission

See the full [Django integration guide](../integrations/django.md).

## Use the CLI

```bash
yoro encode 5.345 -4.028 --domain CI
yoro decode CI-PV9XD
yoro precisions --domain CI
```
