Overview

Scope: geo:read for catalog and search, geo:resolve for address matching. Base path: /geo.

Why this exists

Address labels vary across Arabic, French and transliterated spellings. Carriers also use different identifiers and coverage tables. Geo maps these inputs to a common place graph. Postal codes are nullable fields in the catalog; their presence depends on the dataset, not a country-wide guarantee.

Geo is the fix: one canonical place graph (country → state → city, trilingual, GPS-anchored), one matcher that turns dirty input into that graph (Resolve), and one search surface over it (Search).

Three things to know before you integrate

Confidence is explicit, never silent. resolve returns autoAccept: false with ranked alternatives when it isn't sure — it never guesses across states. If your integration ignores autoAccept and always takes the top match, an ambiguous input (the same commune name exists in two wilayas, for instance) can silently attach to the wrong one. Check autoAccept before trusting a resolution unattended; when it's false, either show the caller alternatives[] or fail the order rather than guessing.

lang never changes the resource identity. Every catalog item always returns the full locales map; ?lang= only sets which language populates displayName. Resource IDs remain stable across languages, but localized responses must be cached with their query and language. Conditional ETag responses are not implemented.

Pickups key to the exact same city rows carriers do. A pickup point's city.id always resolves against /geo/cities — there is no separate "pickup geography." If you're building a stop-desk picker, resolve the address first, then filter pickups by the resolved city.id, not by free-text matching against the pickup's own city name.

Where to go

Catalog — countries, states, cities, polygons, carriers, pickups. Resolve — dirty label → canonical code, with confidence. Search — autocomplete, nearby, and reverse geocoding.