Batch Geocoding

This guide shows how to encode large datasets of GPS coordinates to Yoro codes — useful for geocoding CSV files, database records, or GeoJSON features.

CSV Geocoding

Encode a CSV file

import csv
import yoro

with open("locations.csv") as fin, open("locations_with_yoro.csv", "w", newline="") as fout:
    reader = csv.DictReader(fin)
    fieldnames = reader.fieldnames + ["yoro_code", "yoro_precision", "resolution_m"]
    writer = csv.DictWriter(fout, fieldnames=fieldnames)
    writer.writeheader()

    for row in reader:
        lat = float(row["latitude"])
        lon = float(row["longitude"])
        code = yoro.encode(lat, lon, precision=12, domain="CI")
        decoded = yoro.decode(code)
        res = yoro.resolution(decoded["precision"], domain="CI")

        row["yoro_code"] = code
        row["yoro_precision"] = decoded["precision"]
        row["resolution_m"] = round(res, 1)
        writer.writerow(row)

Input (locations.csv)

name,latitude,longitude
Abidjan Plateau,5.322,-4.017
Bouake Centre,7.694,-5.031
Yamoussoukro,6.827,-5.276
San Pedro Port,4.748,-6.636

Output (locations_with_yoro.csv)

name,latitude,longitude,yoro_code,yoro_precision,resolution_m
Abidjan Plateau,5.322,-4.017,CI-PW2MK,12,172.9
Bouake Centre,7.694,-5.031,CI-NX3WB,12,172.9
Yamoussoukro,6.827,-5.276,CI-NW64D,12,172.9
San Pedro Port,4.748,-6.636,CI-KYB8G,12,172.9

Pandas DataFrame

import pandas as pd
import yoro

df = pd.read_csv("locations.csv")

# Vectorized encoding
df["yoro_code"] = df.apply(
    lambda row: yoro.encode(row["latitude"], row["longitude"], domain="CI"), axis=1
)

# Add decoded info
decoded = df["yoro_code"].apply(yoro.decode)
df["yoro_lat"] = decoded.apply(lambda d: d["lat"])
df["yoro_lon"] = decoded.apply(lambda d: d["lon"])
df["cell_lat_min"] = decoded.apply(lambda d: d["bounds"]["lat_min"])
df["cell_lat_max"] = decoded.apply(lambda d: d["bounds"]["lat_max"])

print(df)

GeoJSON

Add Yoro codes to GeoJSON features

import json
import yoro

with open("parcels.geojson") as f:
    geojson = json.load(f)

for feature in geojson["features"]:
    geom = feature["geometry"]

    if geom["type"] == "Point":
        lon, lat = geom["coordinates"]
    elif geom["type"] == "Polygon":
        # Use centroid of first ring
        coords = geom["coordinates"][0]
        lon = sum(c[0] for c in coords) / len(coords)
        lat = sum(c[1] for c in coords) / len(coords)
    else:
        continue

    code = yoro.encode(lat, lon, domain="CI")
    feature["properties"]["yoro_code"] = code

with open("parcels_with_yoro.geojson", "w") as f:
    json.dump(geojson, f, indent=2)

Django Bulk Assignment

For existing database records without Yoro codes:

from django.contrib.gis.geos import Point
from yoro.django.services import get_or_create_altius_code

from myapp.models import Producer

# Find all producers without a Yoro code
producers = Producer.objects.filter(
    location__isnull=False,
    altius_code__isnull=True,
)

updated = []
for producer in producers.iterator(chunk_size=500):
    lat, lon = producer.location.y, producer.location.x
    code_obj = get_or_create_altius_code(lat, lon, domain="CI")
    producer.altius_code = code_obj
    updated.append(producer)

    if len(updated) >= 500:
        Producer.objects.bulk_update(updated, ["altius_code"])
        updated = []

if updated:
    Producer.objects.bulk_update(updated, ["altius_code"])

Performance

Yoro encoding is pure math — no I/O, no network calls:

import time
import yoro

# Benchmark: 100,000 encodes
start = time.perf_counter()
for i in range(100_000):
    yoro.encode(5.0 + i * 0.00005, -4.0 + i * 0.00003, domain="CI")
elapsed = time.perf_counter() - start

print(f"100,000 encodes in {elapsed:.2f}s ({100_000 / elapsed:.0f} ops/sec)")
# Typical: ~200,000 ops/sec on modern hardware

No need for async or multiprocessing

At ~200K encodes/second, even a million-row dataset takes only 5 seconds. No parallelization needed for most use cases.