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

Module for handling District (Distrito) queries from IBGE.

Districts are administrative subdivisions of municipalities.
This module allows fetching districts by various geographical hierarchies (State, Mesoregion, Municipality, etc.).

# `all`

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

Get all districts.

## Parameters

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

## Examples

    iex> ExIbge.Locality.District.all()
    {:ok, [%ExIbge.Geography.District{id: 520005005, name: "Abadia de Goiás", ...}, ...]}

## See Also

[IBGE API: Distritos](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-distritosGet)

# `all!`

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

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

## Examples

    iex> ExIbge.Locality.District.all!()
    [%ExIbge.Geography.District{...}, ...]

# `find`

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

Get district(s) by identifier(s).

## Parameters

  * `ids` - A single integer ID or a list of integer IDs.
  * `query` - Optional parameters supported by the API.

## Examples

    iex> ExIbge.Locality.District.find(160030312)
    {:ok, [%ExIbge.Geography.District{id: 160030312, name: "Fazendinha", ...}]}

## See Also

[IBGE API: Distrito por ID](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-distritosIdGet)

# `find!`

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

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

## Examples

    iex> ExIbge.Locality.District.find!(160030312)
    [%ExIbge.Geography.District{id: 160030312, name: "Fazendinha", ...}]

# `get_by_immediate_region`

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

Get districts by immediate region identifier(s).

Example:

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

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

# `get_by_immediate_region!`

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

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

## Examples

    iex> ExIbge.Locality.District.get_by_immediate_region!(310037)
    [%ExIbge.Geography.District{...}, ...]

# `get_by_intermediate_region`

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

Get districts by intermediate region identifier(s).

Example:

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

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

# `get_by_intermediate_region!`

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

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

## Examples

    iex> ExIbge.Locality.District.get_by_intermediate_region!(2603)
    [%ExIbge.Geography.District{...}, ...]

# `get_by_mesoregion`

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

Get districts by mesoregion identifier(s).

## Parameters

  * `mesoregion_ids` - A single integer ID or a list of integer IDs.
  * `query` - Optional parameters supported by the API.

## Examples

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

## See Also

[IBGE API: Distritos por Mesorregião](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-mesorregioesMesorregiaoDistritosGet)

# `get_by_mesoregion!`

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

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

## Examples

    iex> ExIbge.Locality.District.get_by_mesoregion!(1602)
    [%ExIbge.Geography.District{...}, ...]

# `get_by_microregion`

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

Get districts by microregion identifier(s).

## Parameters

  * `microregion_ids` - A single integer ID or a list of integer IDs.
  * `query` - Optional parameters supported by the API.

## Examples

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

## See Also

[IBGE API: Distritos por Microrregião](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-microrregioesMicrorregiaoDistritosGet)

# `get_by_microregion!`

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

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

## Examples

    iex> ExIbge.Locality.District.get_by_microregion!(16003)
    [%ExIbge.Geography.District{...}, ...]

# `get_by_municipality`

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

Get districts by municipality identifier(s).

## Parameters

  * `municipality_ids` - A single integer ID or a list of integer IDs.
  * `query` - Optional parameters supported by the API.

## Examples

    iex> ExIbge.Locality.District.get_by_municipality(3550308)
    {:ok, [%ExIbge.Geography.District{...}, ...]}

## See Also

[IBGE API: Distritos por Município](https://servicodados.ibge.gov.br/api/docs/localidades#api-Distritos-municipiosMunicipioDistritosGet)

# `get_by_municipality!`

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

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

## Examples

    iex> ExIbge.Locality.District.get_by_municipality!(3550308)
    [%ExIbge.Geography.District{...}, ...]

# `get_by_region`

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

Get districts by region identifier(s).

Example:

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

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

# `get_by_region!`

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

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

## Examples

    iex> ExIbge.Locality.District.get_by_region!(3)
    [%ExIbge.Geography.District{...}, ...]

# `get_by_state`

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

Get districts by state identifier(s).

## Parameters

  * `uf_ids` - A single identifier or list of identifiers (Integer ID or Atom UFs).
  * `query` - Optional parameters supported by the API.

## Examples

    iex> ExIbge.Locality.District.get_by_state(33)
    {:ok, [%ExIbge.Geography.District{...}, ...]}

    iex> ExIbge.Locality.District.get_by_state(:rj)
    {:ok, [%ExIbge.Geography.District{...}, ...]}

## See Also

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

# `get_by_state!`

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

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

## Examples

    iex> ExIbge.Locality.District.get_by_state!(33)
    [%ExIbge.Geography.District{...}, ...]

---

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