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

Module for handling the IBGE Calendar API (v3) — Calendário de Divulgações.

Provides access to the IBGE release calendar, including scheduled and past
releases of surveys and publications.

## Query Parameters

Both `all/1` and `by_research/2` accept the following options:

  * `:quantity` (`:qtd`) — number of items per page (default: 10).
  * `:from` (`:de`) — start date filter in `ddMMyyyy` format.
  * `:to` (`:ate`) — end date filter in `ddMMyyyy` format.

## Examples

    # Get upcoming releases
    ExIbge.Calendar.all()

    # Get releases for a specific research
    ExIbge.Calendar.by_research(9173)

    # With date filters
    ExIbge.Calendar.all(from: "01012024", to: "31122024", quantity: 5)

# `all`

```elixir
@spec all(keyword()) :: {:ok, map()} | {:error, any()}
```

Get the calendar of releases.

## Parameters

  * `query` — optional keyword list of query parameters (see module docs).

## Examples

    iex> ExIbge.Calendar.all()
    {:ok, %{count: 100, page: 1, total_pages: 10, items: [%ExIbge.Calendar.Release{}, ...]}}

## See Also

[IBGE API: Calendário](https://servicodados.ibge.gov.br/api/docs/calendario?versao=3#api-Calendario-rootGet)

# `all!`

```elixir
@spec all!(keyword()) :: map()
```

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

# `by_research`

```elixir
@spec by_research(
  integer() | String.t(),
  keyword()
) :: {:ok, map()} | {:error, any()}
```

Get the calendar of releases for a specific research.

## Parameters

  * `research_id` — the research identifier.
  * `query` — optional keyword list of query parameters (see module docs).

## Examples

    iex> ExIbge.Calendar.by_research(9173)
    {:ok, %{count: 10, page: 1, total_pages: 1, items: [%ExIbge.Calendar.Release{}, ...]}}

## See Also

[IBGE API: Calendário por pesquisa](https://servicodados.ibge.gov.br/api/docs/calendario?versao=3#api-Calendario-pesquisaGet)

# `by_research!`

```elixir
@spec by_research!(
  integer() | String.t(),
  keyword()
) :: map()
```

Same as `by_research/2`, but raises on failure.

---

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