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

Module for handling IBGE Names API (v2).

Provides data about the frequency of Brazilian names by decade of birth,
collected in the 2010 Census.

> Note: The API does not support compound names (e.g., "Maria Luiza"),
> only the first name and last surname were collected.

# `frequency`

```elixir
@spec frequency(String.t() | [String.t()], Keyword.t()) ::
  {:ok, [ExIbge.Name.Frequency.t()]} | {:error, any()}
```

Get the frequency of births by decade for the given name(s).

## Parameters

  * `names` - A single name or a list of names.
  * `query` - Optional parameters:
    * `sex`: Filter by sex ("M" for male, "F" for female).
    * `group_by`: Group results by geographic level (only "UF" is valid). Only works with a single name.
    * `locality`: Filter by locality ID or atom (e.g., "BR", "33", `:rj`, "3300100").

## Examples

    iex> ExIbge.Name.frequency("joao")
    {:ok, [%ExIbge.Name.Frequency{name: "JOAO", ...}]}

    iex> ExIbge.Name.frequency(["joao", "maria"])
    {:ok, [%ExIbge.Name.Frequency{name: "JOAO", ...}, %ExIbge.Name.Frequency{name: "MARIA", ...}]}

    iex> ExIbge.Name.frequency("ariel", sex: "F")
    {:ok, [%ExIbge.Name.Frequency{name: "ARIEL", sex: "F", ...}]}

    iex> ExIbge.Name.frequency("joao", locality: :rj)
    {:ok, [%ExIbge.Name.Frequency{name: "JOAO", locality: "33", ...}]}

## See Also

[IBGE API: Nomes](https://servicodados.ibge.gov.br/api/docs/nomes)

# `frequency!`

```elixir
@spec frequency!(String.t() | [String.t()], Keyword.t()) :: [
  ExIbge.Name.Frequency.t()
]
```

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

# `ranking`

```elixir
@spec ranking(Keyword.t()) :: {:ok, [ExIbge.Name.Ranking.t()]} | {:error, any()}
```

Get the ranking of names by frequency of births.

## Parameters

  * `query` - Optional parameters:
    * `decade`: Filter by decade of birth (e.g., "1950", "1980").
    * `locality`: Filter by locality ID or atom (e.g., "BR", `:rj`, "3300100").
    * `sex`: Filter by sex ("M" for male, "F" for female).

## Examples

    iex> ExIbge.Name.ranking()
    {:ok, [%ExIbge.Name.Ranking{locality: "BR", ...}]}

    iex> ExIbge.Name.ranking(decade: "1950")
    {:ok, [%ExIbge.Name.Ranking{...}]}

    iex> ExIbge.Name.ranking(locality: :sp, sex: "F")
    {:ok, [%ExIbge.Name.Ranking{locality: "35", sex: "F", ...}]}

## See Also

[IBGE API: Ranking de Nomes](https://servicodados.ibge.gov.br/api/docs/nomes)

# `ranking!`

```elixir
@spec ranking!(Keyword.t()) :: [ExIbge.Name.Ranking.t()]
```

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

---

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