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

Module for handling IBGE Aggregates API (v3).

Allows accessing aggregated data from surveys and censuses (SIDRA).

# `all`

```elixir
@spec all(Keyword.t()) :: {:ok, [ExIbge.Aggregate.Research.t()]} | {:error, any()}
```

Get all aggregates grouped by research.

## Parameters

  * `query` - Optional parameters:
    * `period`: Filter by period (e.g. "P5[202001]")
    * `subject`: Filter by subject ID (e.g. 70)
    * `classification`: Filter by classification ID (e.g. 12896)
    * `periodicity`: Filter by periodicity (e.g. "P5")
    * `level`: Filter by geographical level (e.g. "N6")

## Examples

    iex> ExIbge.Aggregate.all()
    {:ok, [%ExIbge.Aggregate.Research{...}, ...]}

## See Also

[IBGE API: Agregados](https://servicodados.ibge.gov.br/api/docs/agregados#api-Agregados-agregadosGet)

# `all!`

```elixir
@spec all!(Keyword.t()) :: [ExIbge.Aggregate.Research.t()]
```

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

# `get_locations`

```elixir
@spec get_locations(integer() | String.t(), String.t()) ::
  {:ok, [map()]} | {:error, any()}
```

Get locations associated with an aggregate for specific geographical level(s).

## Parameters

  * `aggregate_id` - ID of the aggregate (e.g. 1705)
  * `level` - Geographical level ID(s), pipe-separated (e.g. "N6" or "N7|N6")

## Examples

    iex> ExIbge.Aggregate.get_locations(1705, "N6")
    {:ok, [%{id: "3304557", nome: "Rio de Janeiro", ...}, ...]}

    iex> ExIbge.Aggregate.get_locations(1705, "N7|N6")
    {:ok, [%{id: "3301", ...}, ...]}

## See Also

[IBGE API: Localidades por agregado](https://servicodados.ibge.gov.br/api/docs/agregados#api-Localidades-agregadosAgregadoLocalidadesNivelGet)

# `get_locations!`

```elixir
@spec get_locations!(integer() | String.t(), String.t()) :: [map()]
```

# `get_metadata`

```elixir
@spec get_metadata(integer() | String.t()) ::
  {:ok, ExIbge.Aggregate.Metadata.t()} | {:error, any()}
```

Get metadata for a specific aggregate.

## Parameters

  * `aggregate_id` - ID of the aggregate (e.g. 1705)

## Examples

    iex> ExIbge.Aggregate.get_metadata(1705)
    {:ok, %ExIbge.Aggregate.Metadata{...}}

## See Also

[IBGE API: Metadados](https://servicodados.ibge.gov.br/api/docs/agregados#api-Metadados-agregadosAgregadoMetadadosGet)

# `get_metadata!`

```elixir
@spec get_metadata!(integer() | String.t()) :: ExIbge.Aggregate.Metadata.t()
```

# `get_periods`

```elixir
@spec get_periods(integer() | String.t()) ::
  {:ok, [ExIbge.Aggregate.Period.t()]} | {:error, any()}
```

Get periods for a specific aggregate.

## Parameters

  * `aggregate_id` - ID of the aggregate (e.g. 1705)

## Examples

    iex> ExIbge.Aggregate.get_periods(1705)
    {:ok, [%ExIbge.Aggregate.Period{...}, ...]}

## See Also

[IBGE API: Períodos](https://servicodados.ibge.gov.br/api/docs/agregados#api-Periodos-agregadosAgregadoPeriodosGet)

# `get_periods!`

```elixir
@spec get_periods!(integer() | String.t()) :: [ExIbge.Aggregate.Period.t()]
```

# `get_variables`

```elixir
@spec get_variables(
  integer() | String.t(),
  String.t(),
  String.t() | nil,
  Keyword.t()
) :: {:ok, [ExIbge.Aggregate.Variable.t()]} | {:error, any()}
```

Get variables data for an aggregate.

This function allows querying the data for specific variables, periods, and locations/classifications.

## Parameters

  * `aggregate_id` - ID of the aggregate (e.g. 1712)
  * `periods` - Period identifier(s) (e.g. "-6", "201701", "201701-201706")
  * `variables` - Variable identifier(s) (e.g. "214", "all", "allxp"). Defaults to "allxp" if nil.
  * `query` - Additional query parameters:
    * `locations`: Required. Location filter (e.g. "BR", "N6[3304557]")
    * `classifications`: Optional. Classification filter (e.g. "226[4844]")
    * `view`: Optional. "OLAP" or "flat".

## Examples

    iex> ExIbge.Aggregate.get_variables(1712, "-6", "214", locations: "BR")
    {:ok, [%ExIbge.Aggregate.Variable{...}, ...]}

## See Also

[IBGE API: Variáveis](https://servicodados.ibge.gov.br/api/docs/agregados#api-Variaveis-agregadosAgregadoPeriodosPeriodosVariaveisVariavelGet)

# `get_variables!`

```elixir
@spec get_variables!(
  integer() | String.t(),
  String.t(),
  String.t() | nil,
  Keyword.t()
) :: [ExIbge.Aggregate.Variable.t()]
```

---

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