# `Brasilapi.Cep.API`
[🔗](https://github.com/stlucasgarcia/brasilapi-ex/blob/main/lib/brasilapi/cep/api.ex#L1)

Client for BrasilAPI CEP endpoints.

Provides functions to fetch information about Brazilian postal codes (CEP)
using v1 or v2 endpoints with multiple providers for fallback.

# `get_by_cep`

```elixir
@spec get_by_cep(
  String.t() | integer(),
  keyword()
) :: {:ok, Brasilapi.Cep.Address.t()} | {:error, map()}
```

Fetches information about a CEP (postal code).

By default, uses the v2 endpoint which provides geolocation data and uses
multiple providers for better reliability. You can explicitly request v1
using the `version` option.

## Parameters

  * `cep` - The CEP (postal code) as string or integer. Must be 8 digits.
  * `opts` - Optional keyword list with:
    * `:version` - API version to use (`:v1` or `:v2`). Defaults to `:v2`.

## Examples

    iex> Brasilapi.Cep.API.get_by_cep("89010025")
    {:ok, %Brasilapi.Cep.Address{
      cep: "89010025",
      state: "SC",
      city: "Blumenau",
      neighborhood: "Centro",
      street: "Rua Doutor Luiz de Freitas Melro",
      service: "viacep",
      location: %{type: "Point", coordinates: %{}}
    }}

    iex> Brasilapi.Cep.API.get_by_cep("89010025", version: :v1)
    {:ok, %Brasilapi.Cep.Address{
      cep: "89010025",
      state: "SC",
      city: "Blumenau",
      neighborhood: "Centro",
      street: "Rua Doutor Luiz de Freitas Melro",
      service: "open-cep",
      location: nil
    }}

    iex> Brasilapi.Cep.API.get_by_cep("00000000")
    {:error, %{status: 404, message: "Not found"}}

## API Reference
  * V2: https://brasilapi.com.br/docs#tag/CEP-V2/paths/~1cep~1v2~1%7Bcep%7D/get
  * V1: https://brasilapi.com.br/docs#tag/CEP/paths/~1cep~1v1~1%7Bcep%7D/get

---

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