Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.0.0] — 2026-07-31

Localize.Address.Ecto.Map.Type stores an address as jsonb, keeping its components separate so a stored address still formats to each territory's conventions. Components that are nil are omitted, and a component added later needs no migration.

Requires localize ~> 1.0 and unicode_string ~> 2.3. ecto is an optional dependency; the Ecto type compiles only when it is present.
Adds json_polyfill on OTP 26, which has no built-in :json module. It is not added on OTP 27 and later.

Subdivision lookup no longer calls Localize.Territory.Subdivision.known_subdivisions/0, which Localize 1.0 removed. It now uses subdivision_names_for/1, which returns the localized names directly rather than resolving each candidate separately.

Concurrent load testing revealed that libpostal isn't as thread safe as claimed. We now wrap the libpostal call in a Mutex.

Initial release of Localize.Address providing address parsing via libpostal NIF and locale-aware address formatting via OpenCageData address-formatting templates.

Parse unstructured address strings into a structured Localize.Address.Address struct with labeled components (house number, road, city, state, postcode, country, etc.).
Format addresses according to local conventions for 267 countries and territories. Passes 450/459 (98%) of the OpenCageData conformance test suite with 242/251 countries at 100%.
Capitalize parsed addresses with Unicode-aware titlecasing via Unicode.String.titlecase/2, with postcodes uppercased and codes/numbers left unchanged.
Territory resolution from explicit territory codes, locale identifiers, or the current process locale, following the same pattern as Localize.PhoneNumber.
State and county code lookup using OpenCageData state_codes data with Localize.Territory.subdivision_name/2 as a fallback for reverse lookups (e.g., "California" ↔ "CA").
Dependent territory handling including NL → CW/AW/SX remapping for Caribbean territories, CN → default template for Macau/Hong Kong SARs, and use_country template inheritance with change_country interpolation for 40+ dependent territories.

See the README for usage examples and the Conformance document for full test suite details.