Skip to main content

Switching from OpenCage

OpenCage is a pleasure to use: forward and reverse geocodinggeocodingThe process of converting an address into geographic coordinates (latitude and longitude). Mailwoman geocodes in a multi-tier cascade: exact address-point match → street interpolation → locality centroid. Each tier is progressively coarser but more widely available. plus a rich annotations block — timezone, coordinate formats, calling code, currency, flag, and more — on every result. It's also a hosted API with a key to guard and a per-request bill that grows with you.

Mailwoman's whole annotations layerlayerOne transformer block — attention plus a feed-forward network, with normalization and residual connections — applied to every position. Stacking layers lets the model build up richer representations; Mailwoman's encoder has 6. exists to give you that same block, self-hosted, with no API key and no monthly fee. You run @mailwoman/nominatim, and the OpenCage-keyed annotations come attached.

One command​

npx @mailwoman/nominatim serve --port 8080
curl "http://localhost:8080/search?q=Boston MA"
{
	"lat": "42.332235",
	"lon": "-71.016397",
	"display_name": "Boston, MA",
	"annotations": {
		"DMS": { "lat": "42° 19′ 56.05″ N", "lng": "71° 0′ 59.03″ W" },
		"Maidenhead": "FN42lh",
		"Mercator": { "x": -7905509, "y": 5210877 },
		"geohash": "drt2zfr7n",
		"flag": "🇺🇸",
		"timezone": { "name": "America/New_York", "offset_sec": -14400 }
	}
}

The annotations keys mirror OpenCage's (DMS, Maidenhead, Mercator, timezone.offset_sec, …), so code that reads OpenCage annotations reads these.

What's different​

  • No key, no fee, no rate limit. It runs on your box, from a SQLite file.
  • The forward search uses the Nominatim response shape with the OpenCage annotations block layered on — close to, but not byte-identical to, OpenCage's envelope.

What's missing​

  • Annotation coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present. is growing. Shipped: coordinate formats (DMS, geohash, Maidenhead, Mercator, qibla), flag, ISO, and the IANA timezone with a DST-correct offset. Calling code, currency, UN/LOCODE, and NUTS are on the way; what3words is proprietary and out of scope.
  • Aggregated coveragecoverageThe fraction of a population or region for which a data source has real, non-placeholder entries — e.g. 47% rooftop coverage on Texas addresses. Distinct from accuracy on the rows that are present.. OpenCage blends several backends, so it can resolve some places Mailwoman doesn't yet. Where that matters, OpenCage's multi-service guidance and Mailwoman's free first pass compose well.

See how Mailwoman compares for the capability matrix, and Switching from Nominatim for the full endpoint contract.