Quick Start¶

Encode a GPS coordinate¶

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¶

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

Returns a dict:

{
    "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¶

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

Check resolution¶

# 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¶

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¶

# 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¶

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.

Use the CLI¶

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