Domains

A domain is a geographic bounding box identified by an ISO 3166-1 alpha-2 code. Each domain constrains the coordinate space, giving better resolution per code character than a global system.

Available Domains

import yoro

for code, info in yoro.DOMAINS.items():
    print(f"{code}: {info['name']}")

West Africa (Focus)

Code	Country	Lat Range	Lon Range
CI	Cote d'Ivoire	4.36 — 10.74	-8.60 — -2.49
BF	Burkina Faso	9.00 — 15.50	-5.50 — 2.50
ML	Mali	10.00 — 25.00	-12.50 — 4.50
GN	Guinee	7.19 — 12.68	-15.08 — -7.64
GH	Ghana	4.74 — 11.17	-3.26 — 1.20
SN	Senegal	12.31 — 16.69	-17.54 — -11.36
NE	Niger	11.50 — 24.00	0.00 — 16.00
NG	Nigeria	4.27 — 13.89	2.69 — 14.68
CM	Cameroun	1.65 — 13.08	8.49 — 16.19
TG	Togo	6.10 — 11.14	-0.15 — 1.81
BJ	Benin	6.14 — 12.41	0.77 — 3.85
GM	Gambie	13.06 — 13.83	-16.82 — -13.79
GW	Guinee-Bissau	10.87 — 12.68	-16.71 — -13.64
SL	Sierra Leone	6.93 — 10.00	-13.30 — -10.27
LR	Liberia	4.35 — 8.55	-11.49 — -7.37
MR	Mauritanie	14.72 — 27.30	-17.07 — -4.83

Other Africa

Code	Country
CD	RD Congo
MG	Madagascar
TZ	Tanzanie
KE	Kenya
UG	Ouganda
ET	Ethiopie

Europe & Americas

Code	Country
FR	France
DE	Allemagne
NL	Pays-Bas
BE	Belgique
CH	Suisse
US	Etats-Unis

Global

Code	Description
XX	Worldwide (-90/+90 lat, -180/+180 lon)

Domain Resolution

The resolution depends on the domain's geographic extent. Smaller countries get finer resolution at the same code length:

# 5-character codes (p=12)
yoro.resolution(12, "CI")  #  ~173 m (small country)
yoro.resolution(12, "NG")  #  ~369 m (larger country)
yoro.resolution(12, "XX")  # ~5533 m (whole globe)

Auto-Detection

domain_for_country() maps any ISO country code to its domain, falling back to XX:

yoro.domain_for_country("CI")    # "CI"
yoro.domain_for_country("JP")    # "XX" (no specific domain, uses global)
yoro.domain_for_country(None)    # "XX"

Reading the domain back off a code costs a string split — no need to decode:

yoro.domain_of("CI-4H7A3B")      # "CI"

A country is not its bounding box

Domains are rectangles; countries are not. A point can be genuinely inside a country and outside its box — border areas, enclaves, offshore islands — and some countries have no domain at all. Since 0.3.0 encode() raises rather than clamping such a point onto the edge, because clamping quietly produced a valid code for the wrong place.

That leaves every caller writing the same fallback, so 0.3.1 ships it:

yoro.encode_for_country(6.8, -5.3, "CI")      # "CI-…" — inside the box
yoro.encode_for_country(64.1, -21.9, "CI")    # "XX-…" — Reykjavik is not
yoro.encode_for_country(14.6, 120.9, "PH")    # "XX-…" — no PH domain

Use it whenever the coordinates are not known to sit inside the box. Reach for encode(..., domain=...) only when you want the strict behavior — when a point outside the domain is a bug you would rather hear about.