# `ExIbge.Locality.State`
[🔗](https://github.com/pedrohfonseca81/ex_ibge/blob/main/lib/ex_ibge/locality/state.ex#L1)

Module for handling State (UF) queries from IBGE.

This module provides functions to fetch States (e.g., São Paulo, Rio de Janeiro), covering the "Unidades da Federação".
It supports querying by ID, acronym (atom), or region.

# `all`

```elixir
@spec all(Keyword.t()) :: {:ok, [ExIbge.Geography.State.t()]} | {:error, any()}
```

Get all states (UFs).

## Parameters

  * `query` - Optional parameters supported by the API (e.g., `order_by: :name`).

## Examples

    iex> ExIbge.Locality.State.all()
    {:ok, [%ExIbge.Geography.State{id: 35, acronym: "SP", name: "São Paulo", ...}, ...]}

    iex> ExIbge.Locality.State.all(order_by: :name)
    {:ok, [%ExIbge.Geography.State{id: 35, acronym: "SP", name: "São Paulo", ...}, ...]}

## See Also

[IBGE API: Estados](https://servicodados.ibge.gov.br/api/docs/localidades#api-UFs-estadosGet)

# `all!`

```elixir
@spec all!(Keyword.t()) :: [ExIbge.Geography.State.t()]
```

Same as `all/1`, but raises an error on failure.

Params and options are the same as `all/1`.

## Examples

    iex> ExIbge.Locality.State.all!()
    [%ExIbge.Geography.State{id: 35, acronym: "SP", name: "São Paulo", ...}, ...]

# `find`

```elixir
@spec find(
  integer() | atom() | String.t() | [integer() | atom() | String.t()],
  Keyword.t()
) ::
  {:ok, [ExIbge.Geography.State.t()]} | {:error, any()}
```

Get state(s) by identifier(s).

## Parameters

  * `ids` - A single identifier or list of identifiers. Can be integer IDs (e.g. `35`) or atom acronyms (e.g. `:sp`).
  * `query` - Optional parameters supported by the API.

## Examples

    # Get by integer ID
    iex> ExIbge.Locality.State.find(35)
    {:ok, [%ExIbge.Geography.State{id: 35, acronym: "SP", ...}]}

    # Get by atom acronym
    iex> ExIbge.Locality.State.find(:sp)
    {:ok, [%ExIbge.Geography.State{id: 35, acronym: "SP", ...}]}

    # Get multiple states
    iex> ExIbge.Locality.State.find([33, 35])
    {:ok, [%ExIbge.Geography.State{id: 33, ...}, %ExIbge.Geography.State{id: 35, ...}]}

## See Also

[IBGE API: Estado por ID](https://servicodados.ibge.gov.br/api/docs/localidades#api-UFs-estadosUFGet)

# `find!`

```elixir
@spec find!(
  integer() | atom() | String.t() | [integer() | atom() | String.t()],
  Keyword.t()
) :: [ExIbge.Geography.State.t()]
```

Same as `find/2`, but raises an error on failure.

Params and options are the same as `find/2`.

## Examples

    iex> ExIbge.Locality.State.find!(35)
    [%ExIbge.Geography.State{id: 35, acronym: "SP", ...}]

# `get_by_region`

```elixir
@spec get_by_region(integer() | String.t() | [integer() | String.t()], Keyword.t()) ::
  {:ok, [ExIbge.Geography.State.t()]} | {:error, any()}
```

Get states by region identifier(s).

## Parameters

  * `region_ids` - A single integer ID or list of integer IDs representing the region(s).
  * `query` - Optional parameters supported by the API.

## Examples

    iex> ExIbge.Locality.State.get_by_region(3)
    {:ok, [%ExIbge.Geography.State{id: 35, acronym: "SP", ...}, ...]}

## See Also

[IBGE API: Estados por Região](https://servicodados.ibge.gov.br/api/docs/localidades#api-UFs-regioesMacrorregiaoEstadosGet)

# `get_by_region!`

```elixir
@spec get_by_region!(integer() | String.t() | [integer() | String.t()], Keyword.t()) ::
  [
    ExIbge.Geography.State.t()
  ]
```

Same as `get_by_region/2`, but raises an error on failure.

Params and options are the same as `get_by_region/2`.

## Examples

    iex> ExIbge.Locality.State.get_by_region!(3)
    [%ExIbge.Geography.State{id: 35, acronym: "SP", ...}, ...]

---

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