# `ExIbge.Bngb`
[🔗](https://github.com/pedrohfonseca81/ex_ibge/blob/main/lib/ex_ibge/bngb.ex#L1)

Module for handling IBGE BNGB API (v1) — Banco de Nomes Geográficos do Brasil.

Provides access to geographic names, their locations, categories, and classes
as maintained by IBGE's geographic names database.

# `by_bounding_box`

```elixir
@spec by_bounding_box(number(), number(), number(), number()) ::
  {:ok, [ExIbge.Bngb.GeographicName.t()]} | {:error, any()}
```

Get geographic names within a bounding box defined by four coordinates.

## Parameters

  * `lon_w` - Western longitude.
  * `lat_s` - Southern latitude.
  * `lon_e` - Eastern longitude.
  * `lat_n` - Northern latitude.

## Examples

    iex> ExIbge.Bngb.by_bounding_box(-48.0, -16.0, -47.0, -15.0)
    {:ok, [%ExIbge.Bngb.GeographicName{...}, ...]}

## See Also

[IBGE API: Nomes Geográficos por enquadramento](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Nomes%20Geograficos-6)

# `by_bounding_box!`

```elixir
@spec by_bounding_box!(number(), number(), number(), number()) :: [
  ExIbge.Bngb.GeographicName.t()
]
```

Same as `by_bounding_box/4`, but raises on failure.

# `by_category`

```elixir
@spec by_category(String.t()) ::
  {:ok, [ExIbge.Bngb.GeographicName.t()]} | {:error, any()}
```

Get geographic names belonging to a given category.

## Parameters

  * `category` - The category name (e.g., "Hidrografia", "Relevo").

## Examples

    iex> ExIbge.Bngb.by_category("Hidrografia")
    {:ok, [%ExIbge.Bngb.GeographicName{category: "Hidrografia", ...}, ...]}

## See Also

[IBGE API: Nomes Geográficos por categoria](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Nomes%20Geograficos-7)

# `by_category!`

```elixir
@spec by_category!(String.t()) :: [ExIbge.Bngb.GeographicName.t()]
```

Same as `by_category/1`, but raises on failure.

# `by_class`

```elixir
@spec by_class(String.t()) ::
  {:ok, [ExIbge.Bngb.GeographicName.t()]} | {:error, any()}
```

Get geographic names belonging to a given class.

## Parameters

  * `class` - The class name (e.g., "ilha", "curso_dagua").

## Examples

    iex> ExIbge.Bngb.by_class("ilha")
    {:ok, [%ExIbge.Bngb.GeographicName{class: "ilha", ...}, ...]}

## See Also

[IBGE API: Nomes Geográficos por classe](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Nomes%20Geograficos-8)

# `by_class!`

```elixir
@spec by_class!(String.t()) :: [ExIbge.Bngb.GeographicName.t()]
```

Same as `by_class/1`, but raises on failure.

# `by_municipality`

```elixir
@spec by_municipality(integer() | String.t()) ::
  {:ok, [ExIbge.Bngb.GeographicName.t()]} | {:error, any()}
```

Get geographic names by municipality geocode.

## Parameters

  * `geocode` - The municipality geocode (e.g., "5300108" for Brasília).

## Examples

    iex> ExIbge.Bngb.by_municipality("5300108")
    {:ok, [%ExIbge.Bngb.GeographicName{...}, ...]}

## See Also

[IBGE API: Nomes Geográficos por município](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Nomes%20Geograficos-3)

# `by_municipality!`

```elixir
@spec by_municipality!(integer() | String.t()) :: [ExIbge.Bngb.GeographicName.t()]
```

Same as `by_municipality/1`, but raises on failure.

# `by_proximity`

```elixir
@spec by_proximity(number(), number(), number()) ::
  {:ok, [ExIbge.Bngb.GeographicName.t()]} | {:error, any()}
```

Get geographic names near a coordinate within a given distance.

## Parameters

  * `lat` - Latitude of the reference point.
  * `lon` - Longitude of the reference point.
  * `km` - Search radius in kilometers.

## Examples

    iex> ExIbge.Bngb.by_proximity(-15.79, -47.88, 10)
    {:ok, [%ExIbge.Bngb.GeographicName{...}, ...]}

## See Also

[IBGE API: Nomes Geográficos por proximidade](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Nomes%20Geograficos-5)

# `by_proximity!`

```elixir
@spec by_proximity!(number(), number(), number()) :: [ExIbge.Bngb.GeographicName.t()]
```

Same as `by_proximity/3`, but raises on failure.

# `by_state`

```elixir
@spec by_state(atom() | String.t()) ::
  {:ok, [ExIbge.Bngb.GeographicName.t()]} | {:error, any()}
```

Get geographic names by state (UF).

## Parameters

  * `state` - The state abbreviation as a string (e.g., "DF") or atom (e.g., `:df`).

## Examples

    iex> ExIbge.Bngb.by_state(:df)
    {:ok, [%ExIbge.Bngb.GeographicName{...}, ...]}

    iex> ExIbge.Bngb.by_state("RJ")
    {:ok, [%ExIbge.Bngb.GeographicName{...}, ...]}

## See Also

[IBGE API: Nomes Geográficos por UF](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Nomes%20Geograficos-4)

# `by_state!`

```elixir
@spec by_state!(atom() | String.t()) :: [ExIbge.Bngb.GeographicName.t()]
```

Same as `by_state/1`, but raises on failure.

# `categories`

```elixir
@spec categories() :: {:ok, [ExIbge.Bngb.Category.t()]} | {:error, any()}
```

Get the list of categories available in the BNGB (EDGV 3.0).

## Examples

    iex> ExIbge.Bngb.categories()
    {:ok, [%ExIbge.Bngb.Category{name: "Hidrografia"}, ...]}

## See Also

[IBGE API: Lista de categorias](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Outros-listacategoria)

# `categories!`

```elixir
@spec categories!() :: [ExIbge.Bngb.Category.t()]
```

Same as `categories/0`, but raises on failure.

# `classes`

```elixir
@spec classes() :: {:ok, [ExIbge.Bngb.Class.t()]} | {:error, any()}
```

Get the list of classes available in the BNGB (EDGV 3.0).

## Examples

    iex> ExIbge.Bngb.classes()
    {:ok, [%ExIbge.Bngb.Class{name: "ilha", description: "...", category: "Hidrografia"}, ...]}

## See Also

[IBGE API: Lista de classes](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Outros-listaclasse)

# `classes!`

```elixir
@spec classes!() :: [ExIbge.Bngb.Class.t()]
```

Same as `classes/0`, but raises on failure.

# `dictionary`

```elixir
@spec dictionary() :: {:ok, [ExIbge.Bngb.DictionaryEntry.t()]} | {:error, any()}
```

Get the dictionary of API terms with translations to English, Spanish, and Portuguese labels.

## Examples

    iex> ExIbge.Bngb.dictionary()
    {:ok, [%ExIbge.Bngb.DictionaryEntry{term: "Hidrografia", label_pt: "Hidrografia", ...}, ...]}

## See Also

[IBGE API: Dicionário](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Outros-dicionario)

# `dictionary!`

```elixir
@spec dictionary!() :: [ExIbge.Bngb.DictionaryEntry.t()]
```

Same as `dictionary/0`, but raises on failure.

# `geo_names`

```elixir
@spec geo_names() :: {:ok, [ExIbge.Bngb.GeoName.t()]} | {:error, any()}
```

Get the list of all geographic names in the BNGB.

## Examples

    iex> ExIbge.Bngb.geo_names()
    {:ok, [%ExIbge.Bngb.GeoName{term: "Rio Amazonas"}, ...]}

## See Also

[IBGE API: Lista dos nomes geográficos](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Outros-listanomegeo)

# `geo_names!`

```elixir
@spec geo_names!() :: [ExIbge.Bngb.GeoName.t()]
```

Same as `geo_names/0`, but raises on failure.

# `get`

```elixir
@spec get(integer() | String.t()) ::
  {:ok, [ExIbge.Bngb.GeographicName.t()]} | {:error, any()}
```

Get a geographic name by its identifier.

## Parameters

  * `id` - The BNGB identifier of the geographic name.

## Examples

    iex> ExIbge.Bngb.get(180379)
    {:ok, [%ExIbge.Bngb.GeographicName{name: "Brasília", ...}]}

## See Also

[IBGE API: Nome Geográfico](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Nomes%20Geograficos-1)

# `get!`

```elixir
@spec get!(integer() | String.t()) :: [ExIbge.Bngb.GeographicName.t()]
```

Same as `get/1`, but raises on failure.

# `search`

```elixir
@spec search(String.t()) :: {:ok, [ExIbge.Bngb.GeographicName.t()]} | {:error, any()}
```

Search geographic names by a pattern in the name.

## Parameters

  * `pattern` - The search pattern to match against geographic names.

## Examples

    iex> ExIbge.Bngb.search("brasilia")
    {:ok, [%ExIbge.Bngb.GeographicName{name: "Brasília", ...}, ...]}

## See Also

[IBGE API: Nomes Geográficos por padrão](https://servicodados.ibge.gov.br/api/docs/bngb?versao=1#api-Nomes%20Geograficos-2)

# `search!`

```elixir
@spec search!(String.t()) :: [ExIbge.Bngb.GeographicName.t()]
```

Same as `search/1`, but raises on failure.

---

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