@spec available?() :: boolean()

Returns whether the NIF backend is available.

Returns

• true if the NIF shared library was loaded successfully.

• false if the NIF is not compiled or libpostal is missing.

Examples

iex> is_boolean(Localize.Address.available?())
true

@spec capitalize(
  t(),
  keyword()
) :: t()

Capitalizes the text fields of an address struct.

Applies Unicode-aware titlecase to place names, street names, and administrative region fields. Postcodes are uppercased. House numbers, territory codes, and the raw input string are left unchanged.

Arguments

• address is a Localize.Address.Address struct.

Options

• :locale is a locale identifier passed through to Unicode.String.titlecase/2 for locale-specific casing rules (e.g., Dutch "ij" → "IJ", Turkish dotted-I handling).

Returns

• A new Localize.Address.Address struct with capitalized fields.

Examples

iex> address = %Localize.Address.Address{
...>   road: "hamilton avenue",
...>   city: "palo alto",
...>   postcode: "sw1a 2aa"
...> }
iex> capitalized = Localize.Address.capitalize(address)
iex> capitalized.road
"Hamilton Avenue"
iex> capitalized.city
"Palo Alto"
iex> capitalized.postcode
"SW1A 2AA"

@spec parse(
  String.t(),
  keyword()
) :: {:ok, t()} | {:error, String.t()}

Parses an unstructured address string into a Localize.Address.Address struct.

Uses libpostal's machine-learning models to identify address components such as house number, road, city, state, and postcode.

Arguments

• address_string is the unstructured address string to parse.

Options

• :territory is an explicit ISO 3166-1 alpha-2 territory code (e.g., "US", "GB", or an atom like :US). Used as the territory code on the resulting struct and as context for parsing.

• :locale is a locale identifier used to derive the territory. Accepts a string (e.g., "en-US"), an atom (e.g., :en_US), or a Localize.LanguageTag.t() struct.

When neither :territory nor :locale is given, the territory is derived from Localize.get_locale/0.

Returns

• {:ok, address} where address is a Localize.Address.Address struct.

• {:error, reason} if the address cannot be parsed.

Examples

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

iex> {:ok, address} = Localize.Address.parse("10 Downing Street, London", territory: "GB")
iex> address.territory_code
"GB"

@spec to_string(
  t(),
  keyword()
) :: {:ok, String.t()} | {:error, String.t()}

Formats an address struct into a locale-appropriate string.

Uses OpenCageData address formatting templates to produce a properly formatted address for the territory associated with the address.

Arguments

• address is a Localize.Address.Address struct.

Options

• :territory overrides the territory code used for template selection. Defaults to address.territory_code.

Returns

• {:ok, formatted_string} on success.

• {:error, reason} if formatting fails.

Examples

iex> address = %Localize.Address.Address{
...>   house_number: "301",
...>   road: "Hamilton Avenue",
...>   city: "Palo Alto",
...>   state: "CA",
...>   postcode: "94303",
...>   territory: "United States of America",
...>   territory_code: "US"
...> }
iex> {:ok, formatted} = Localize.Address.to_string(address)
iex> is_binary(formatted)
true