Localize.Address

Address parsing and locale-aware formatting for Elixir.

Parses unstructured address strings into structured components using libpostal via NIF, and formats structured addresses into locale-appropriate string representations using templates from the OpenCageData address-formatting project. Supports Unicode-aware capitalization via Unicode.String.

Installation

Add localize_address to your list of dependencies in mix.exs:

def deps do
  [
    {:localize_address, "~> 0.1"}
  ]
end

System Dependencies

• libpostal is required for address parsing. Install with:

  brew install libpostal    # macOS
  apt-get install libpostal-dev   # Debian/Ubuntu

• Address templates must be downloaded before formatting. Run once after install and whenever upstream templates are updated:

  mix localize.address.download_templates

Quick Start

Parse an address, capitalize it, and format for its territory:

iex> {:ok, address} = Localize.Address.parse(
...>   "301 Hamilton Avenue, Palo Alto, CA 94303",
...>   capitalize: true
...> )
iex> address.road
"Hamilton Avenue"
iex> address.city
"Palo Alto"

iex> {:ok, formatted} = Localize.Address.to_string(address)
iex> IO.puts(formatted)
301 Hamilton Avenue
Palo Alto, CA 94303

Different countries format addresses differently:

# United States: house road / city, STATE postcode / country
iex> Localize.Address.to_string(%Localize.Address.Address{
...>   house_number: "1600", road: "Pennsylvania Avenue NW",
...>   city: "Washington", state: "District of Columbia",
...>   postcode: "20500", territory: "United States of America",
...>   territory_code: "US"
...> })
{:ok, "1600 Pennsylvania Avenue NW\nWashington, DC 20500\nUnited States of America"}

# Germany: road number / postcode city / country
iex> Localize.Address.to_string(%Localize.Address.Address{
...>   house_number: "1", road: "Unter den Linden",
...>   city: "Berlin", postcode: "10117",
...>   territory: "Germany", territory_code: "DE"
...> })
{:ok, "Unter den Linden 1\n10117 Berlin\nGermany"}

See the Parsing and Formatting guide for detailed usage including territory options, capitalization, and manual struct construction.

Primary API

• Localize.Address.parse/2 — parse an unstructured address string into a struct.

• Localize.Address.to_string/2 — format a struct into a locale-appropriate string.

• Localize.Address.capitalize/2 — titlecase text fields and uppercase postcodes.

• Localize.Address.available?/0 — check if the libpostal NIF is loaded.

Source References

• libpostal — C library for parsing and normalizing street addresses using statistical NLP and open geo data. Powers Localize.Address.parse/2.

• OpenCageData address-formatting — Templates and rules for formatting addresses according to local conventions, covering 267 countries and territories. Powers Localize.Address.to_string/2.

• Localize — Provides territory validation, locale resolution, and subdivision name lookups (e.g., "California" ↔ "CA") used for state/county code resolution.

• Unicode.String — Unicode-aware titlecase, used by Localize.Address.capitalize/2.

Conformance

Validated against the full OpenCageData test suite (459 test cases across 251 countries and territories).

450/459 tests passing (98.0%). 242/251 countries at 100%.

All major countries pass at 100%: US, GB, DE, FR, CA, AU, IT, ES, IE, JP, SG, IN, BR, NL.

The 9 remaining failures are documented with root causes in the conformance document.

License

Apache License 2.0. See LICENSE.md for details.