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

Module for handling Municipality (Município) queries from IBGE.

This module provides functions to fetch Municipalities by various geographical hierarchies
(State, Mesoregion, Microregion, Immediate Region, Intermediate Region, Region).

# `all`

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

Get all municipalities.

Example:

    iex> ExIbge.Locality.Municipality.all()
    {:ok, [%ExIbge.Geography.Municipality{id: 1100015, name: "Alta Floresta D'Oeste", ...}, ...]}

Example with query:

    iex> ExIbge.Locality.Municipality.all(order_by: :name, view: "nivelado")
    {:ok, [%ExIbge.Geography.Municipality{id: 1100015, name: "Alta Floresta D'Oeste", ...}, ...]}

For more information, see the [IBGE API documentation](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-municipiosGet).

# `all!`

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

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

## Examples

    iex> ExIbge.Locality.Municipality.all!()
    [%ExIbge.Geography.Municipality{id: 1100015, name: "Alta Floresta D'Oeste", ...}, ...]

# `find`

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

Get municipalities by identifier(s).

Example:

    iex> ExIbge.Locality.Municipality.find(3550308)
    {:ok, [%ExIbge.Geography.Municipality{id: 3550308, name: "São Paulo", ...}]}

Example with multiple IDs:

    iex> ExIbge.Locality.Municipality.find([3304557, 3550308])
    {:ok, [%ExIbge.Geography.Municipality{id: 3304557, name: "Rio de Janeiro", ...}, ...]}

For more information, see the [IBGE API documentation](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-municipiosIdGet).

# `find!`

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

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

## Examples

    iex> ExIbge.Locality.Municipality.find!(3550308)
    [%ExIbge.Geography.Municipality{id: 3550308, name: "São Paulo", ...}]

# `get_by_immediate_region`

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

Get municipalities by immediate region identifier(s).

Example:

    iex> ExIbge.Locality.Municipality.get_by_immediate_region(310055)
    {:ok, [%ExIbge.Geography.Municipality{...}, ...]}

For more information, see the [IBGE API documentation](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-regioes_imediatasRegiaoImediataMunicipiosGet).

# `get_by_immediate_region!`

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

Get municipalities by immediate region identifier(s) or raise an error.

# `get_by_intermediate_region`

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

Get municipalities by intermediate region identifier(s).

Example:

    iex> ExIbge.Locality.Municipality.get_by_intermediate_region(5202)
    {:ok, [%ExIbge.Geography.Municipality{...}, ...]}

For more information, see the [IBGE API documentation](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-regioes_intermediariasRegiaoIntermediariaMunicipiosGet).

# `get_by_intermediate_region!`

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

Get municipalities by intermediate region identifier(s) or raise an error.

# `get_by_mesoregion`

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

Get municipalities by mesoregion identifier(s).

Example:

    iex> ExIbge.Locality.Municipality.get_by_mesoregion(3301)
    {:ok, [%ExIbge.Geography.Municipality{...}, ...]}

For more information, see the [IBGE API documentation](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-mesorregioesMesorregiaoMunicipiosGet).

# `get_by_mesoregion!`

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

Get municipalities by mesoregion identifier(s) or raise an error.

# `get_by_microregion`

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

Get municipalities by microregion identifier(s).

Example:

    iex> ExIbge.Locality.Municipality.get_by_microregion(33001)
    {:ok, [%ExIbge.Geography.Municipality{...}, ...]}

For more information, see the [IBGE API documentation](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-microrregioesMicrorregiaoMunicipiosGet).

# `get_by_microregion!`

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

Get municipalities by microregion identifier(s) or raise an error.

# `get_by_region`

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

Get municipalities by region identifier(s).

Example:

    iex> ExIbge.Locality.Municipality.get_by_region(3)
    {:ok, [%ExIbge.Geography.Municipality{...}, ...]}

For more information, see the [IBGE API documentation](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-regioesMacrorregiaoMunicipiosGet).

# `get_by_region!`

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

Get municipalities by region identifier(s) or raise an error.

# `get_by_state`

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

Get municipalities by state identifier(s).

Example:

    iex> ExIbge.Locality.Municipality.get_by_state(33)
    {:ok, [%ExIbge.Geography.Municipality{id: 3300100, name: "Angra dos Reis", ...}, ...]}

Example with multiple states:

    iex> ExIbge.Locality.Municipality.get_by_state([33, 35])
    {:ok, [%ExIbge.Geography.Municipality{id: 3300100, name: "Angra dos Reis", ...}, ...]}

Example with state atom:

    iex> ExIbge.Locality.Municipality.get_by_state(:rj)
    {:ok, [%ExIbge.Geography.Municipality{id: 3300100, name: "Angra dos Reis", ...}, ...]}

For more information, see the [IBGE API documentation](https://servicodados.ibge.gov.br/api/docs/localidades#api-Municipios-estadosUFMunicipiosGet).

# `get_by_state!`

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

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

## Examples

    iex> ExIbge.Locality.Municipality.get_by_state!(33)
    [%ExIbge.Geography.Municipality{id: 3300100, name: "Angra dos Reis", ...}, ...]

---

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