# `Localize.Address`
[🔗](https://github.com/elixir-localize/localize_address/blob/v0.2.0/lib/localize/address.ex#L1)

Parses unstructured address strings and formats structured
addresses into locale-appropriate string representations.

Address parsing is powered by libpostal via NIF. Address formatting
uses templates from the OpenCageData address-formatting project,
compiled to Erlang term format.

The primary functions are `parse/2` for parsing raw address strings
and `to_string/2` for formatting an `Address` struct.

# `t`

```elixir
@type t() :: Localize.Address.Address.t()
```

# `available?`

```elixir
@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

# `capitalize`

```elixir
@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"

# `parse`

```elixir
@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"

# `to_string`

```elixir
@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

---

*Consult [api-reference.md](api-reference.md) for complete listing*