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

Module for handling Subdistrict (Subdistrito) queries from IBGE.

This module provides functions to fetch Subdistricts by various geographical hierarchies
(District, Municipality, State, etc.).

# `all`

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

Get all subdistricts.

## Parameters

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

## Examples

    iex> ExIbge.Locality.Subdistrict.all()
    {:ok, [%ExIbge.Geography.Subdistrict{id: 53001080517, name: "Brasília", ...}, ...]}

## See Also

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

# `all!`

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

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

## Examples

    iex> ExIbge.Locality.Subdistrict.all!()
    [%ExIbge.Geography.Subdistrict{id: 53001080517, name: "Brasília", ...}, ...]

# `find`

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

Get subdistrict(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.Subdistrict.find(53001080517)
    {:ok, [%ExIbge.Geography.Subdistrict{id: 53001080517, name: "Brasília", ...}]}

## See Also

[IBGE API: Subdistrito por ID](https://servicodados.ibge.gov.br/api/docs/localidades#api-Subdistritos-subdistritosIdGet)

# `find!`

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

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

## Examples

    iex> ExIbge.Locality.Subdistrict.find!(53001080517)
    [%ExIbge.Geography.Subdistrict{id: 53001080517, name: "Brasília", ...}]

# `get_by_district`

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

Get subdistricts by district identifier(s).

## Parameters

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

## Examples

    iex> ExIbge.Locality.Subdistrict.get_by_district(530010805)
    {:ok, [%ExIbge.Geography.Subdistrict{...}, ...]}

## See Also

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

# `get_by_district!`

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

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

## Examples

    iex> ExIbge.Locality.Subdistrict.get_by_district!(530010805)
    [%ExIbge.Geography.Subdistrict{...}, ...]

# `get_by_immediate_region`

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

Get subdistricts by immediate region identifier(s).

## Parameters

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

## Examples

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

## See Also

[IBGE API: Subdistritos por Região Imediata](https://servicodados.ibge.gov.br/api/docs/localidades#api-Subdistritos-regioes_imediatasRegiaoImediataSubdistritosGet)

# `get_by_immediate_region!`

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

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

## Examples

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

# `get_by_mesoregion`

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

Get subdistricts 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.Subdistrict.get_by_mesoregion(5301)
    {:ok, [%ExIbge.Geography.Subdistrict{...}, ...]}

## See Also

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

# `get_by_mesoregion!`

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

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

## Examples

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

# `get_by_microregion`

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

Get subdistricts 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.Subdistrict.get_by_microregion(53001)
    {:ok, [%ExIbge.Geography.Subdistrict{...}, ...]}

## See Also

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

# `get_by_microregion!`

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

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

## Examples

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

# `get_by_municipality`

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

Get subdistricts 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.Subdistrict.get_by_municipality(5300108)
    {:ok, [%ExIbge.Geography.Subdistrict{...}, ...]}

## See Also

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

# `get_by_municipality!`

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

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

## Examples

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

# `get_by_region`

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

Get subdistricts by region identifier(s).

## Parameters

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

## Examples

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

## See Also

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

# `get_by_region!`

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

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

## Examples

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

# `get_by_state`

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

Get subdistricts 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.Subdistrict.get_by_state(53)
    {:ok, [%ExIbge.Geography.Subdistrict{...}, ...]}

## See Also

[IBGE API: Subdistritos por UF](https://servicodados.ibge.gov.br/api/docs/localidades#api-Subdistritos-estadosUFSubdistritosGet)

# `get_by_state!`

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

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

## Examples

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

---

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