@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