Pular para conteúdo

IPCA

indexes(start, end)

Obtém os valores do número-índice do IPCA para um intervalo.

Realiza chamada à API do portal de dados do IBGE no formato: https://servicodados.ibge.gov.br/api/v3/agregados/6691/periodos/YYYYMM-YYYYMM/variaveis/2266?localidades=N1[all]

Parameters:

Name Type Description Default
start DateLike

Data de início do intervalo.

 required
end DateLike

Data de fim do intervalo.

 required

Returns:

Type Description
DataFrame

pl.DataFrame com colunas 'periodo' e 'valor'.
Output Columns
  • periodo (Int64): período no formato YYYYMM.
  • valor (Float64): número-índice do IPCA.

Examples:

>>> from pyield import ipca
>>> # Obter os números-índice do IPCA para o primeiro trimestre
>>> ipca.indexes(start="01-01-2025", end="01-03-2025")
shape: (3, 2)
┌─────────┬─────────┐
│ periodo ┆ valor   │
│ ---     ┆ ---     │
│ i64     ┆ f64     │
╞═════════╪═════════╡
│ 202501  ┆ 7111.86 │
│ 202502  ┆ 7205.03 │
│ 202503  ┆ 7245.38 │
└─────────┴─────────┘
Source code in pyield/ipca/historical.py 
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
def indexes(start: DateLike, end: DateLike) -> pl.DataFrame:
    """Obtém os valores do número-índice do IPCA para um intervalo.

    Realiza chamada à API do portal de dados do IBGE no formato:
    https://servicodados.ibge.gov.br/api/v3/agregados/6691/periodos/YYYYMM-YYYYMM/variaveis/2266?localidades=N1[all]

    Args:
        start: Data de início do intervalo.
        end: Data de fim do intervalo.

    Returns:
        pl.DataFrame com colunas 'periodo' e 'valor'.

    Output Columns:
        * periodo (Int64): período no formato YYYYMM.
        * valor (Float64): número-índice do IPCA.

    Examples:
        >>> from pyield import ipca
        >>> # Obter os números-índice do IPCA para o primeiro trimestre
        >>> ipca.indexes(start="01-01-2025", end="01-03-2025")
        shape: (3, 2)
        ┌─────────┬─────────┐
        │ periodo ┆ valor   │
        │ ---     ┆ ---     │
        │ i64     ┆ f64     │
        ╞═════════╪═════════╡
        │ 202501  ┆ 7111.86 │
        │ 202502  ┆ 7205.03 │
        │ 202503  ┆ 7245.38 │
        └─────────┴─────────┘
    """
    return _buscar_periodo(start, end, _VAR_INDICE)

last_indexes(qtd_meses=1)

Obtém os últimos valores do número-índice do IPCA.

Realiza chamada à API do portal de dados do IBGE no formato: https://servicodados.ibge.gov.br/api/v3/agregados/6691/periodos/-N/variaveis/2266?localidades=N1[all]

Parameters:

Name Type Description Default
qtd_meses int

Número de meses a recuperar. Padrão: 1.

 1

Returns:

Type Description
DataFrame

pl.DataFrame com colunas 'periodo' e 'valor'.
Output Columns
  • periodo (Int64): período no formato YYYYMM.
  • valor (Float64): número-índice do IPCA.

Raises:

Type Description
ValueError

Se qtd_meses for menor ou igual a 0.

Examples:

>>> from pyield import ipca
>>> # Obter o número-índice do IPCA do último mês
>>> df = ipca.last_indexes(1)
>>> # Obter os números-índice do IPCA dos últimos 3 meses
>>> df = ipca.last_indexes(3)
Source code in pyield/ipca/historical.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
def last_indexes(qtd_meses: int = 1) -> pl.DataFrame:
    """Obtém os últimos valores do número-índice do IPCA.

    Realiza chamada à API do portal de dados do IBGE no formato:
    https://servicodados.ibge.gov.br/api/v3/agregados/6691/periodos/-N/variaveis/2266?localidades=N1[all]

    Args:
        qtd_meses: Número de meses a recuperar. Padrão: 1.

    Returns:
        pl.DataFrame com colunas 'periodo' e 'valor'.

    Output Columns:
        * periodo (Int64): período no formato YYYYMM.
        * valor (Float64): número-índice do IPCA.

    Raises:
        ValueError: Se qtd_meses for menor ou igual a 0.

    Examples:
        >>> from pyield import ipca
        >>> # Obter o número-índice do IPCA do último mês
        >>> df = ipca.last_indexes(1)
        >>> # Obter os números-índice do IPCA dos últimos 3 meses
        >>> df = ipca.last_indexes(3)
    """
    return _buscar_ultimos(qtd_meses, _VAR_INDICE)

last_rates(qtd_meses=1)

Obtém as últimas taxas mensais do IPCA.

Realiza chamada à API do portal de dados do IBGE no formato: https://servicodados.ibge.gov.br/api/v3/agregados/6691/periodos/-N/variaveis/63?localidades=N1[all]

Parameters:

Name Type Description Default
qtd_meses int

Número de meses a recuperar. Padrão: 1.

 1

Returns:

Type Description
DataFrame

pl.DataFrame com colunas 'periodo' e 'valor'.
Output Columns
  • periodo (Int64): período no formato YYYYMM.
  • valor (Float64): taxa mensal em decimal.

Raises:

Type Description
ValueError

Se qtd_meses for menor ou igual a 0.

Examples:

>>> from pyield import ipca
>>> # Obter a taxa do IPCA do último mês
>>> df = ipca.last_rates(1)
>>> # Obter as taxas do IPCA dos últimos 3 meses
>>> df = ipca.last_rates(3)
Source code in pyield/ipca/historical.py 
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
def last_rates(qtd_meses: int = 1) -> pl.DataFrame:
    """Obtém as últimas taxas mensais do IPCA.

    Realiza chamada à API do portal de dados do IBGE no formato:
    https://servicodados.ibge.gov.br/api/v3/agregados/6691/periodos/-N/variaveis/63?localidades=N1[all]

    Args:
        qtd_meses: Número de meses a recuperar. Padrão: 1.

    Returns:
        pl.DataFrame com colunas 'periodo' e 'valor'.

    Output Columns:
        * periodo (Int64): período no formato YYYYMM.
        * valor (Float64): taxa mensal em decimal.

    Raises:
        ValueError: Se qtd_meses for menor ou igual a 0.

    Examples:
        >>> from pyield import ipca
        >>> # Obter a taxa do IPCA do último mês
        >>> df = ipca.last_rates(1)
        >>> # Obter as taxas do IPCA dos últimos 3 meses
        >>> df = ipca.last_rates(3)
    """
    return _buscar_ultimos(qtd_meses, _VAR_TAXA, em_percentual=True)

projected_rate()

Obtém a projeção atual do IPCA no site da ANBIMA.

A função baixa a planilha XLS de indicadores da ANBIMA e extrai os dados da projeção do IPCA.

Returns:

Name Type Description
ProjecaoIndicador ProjecaoIndicador

Objeto contendo: - ultima_atualizacao (dt.datetime): Data e hora da última atualização. - periodo_referencia (str): Período de referência no formato "MMM/YY" (ex.: "mar/26"). - valor_projetado (float): Valor projetado do IPCA (decimal).

Raises:

Type Description
ConnectionError

Se houver erro de conexão com o site da ANBIMA.
ValueError

Se os dados esperados não forem encontrados na planilha.
Notes

Requer conexão com a internet para acessar o site da ANBIMA.

Examples:

>>> from pyield import ipca
>>> # Obter a projeção atual do IPCA na ANBIMA
>>> ipca.projected_rate()
ProjecaoIndicador(ultima_atualizacao=..., periodo_referencia=..., valor_projetado=...)
Source code in pyield/ipca/projected.py 
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
def projected_rate() -> ProjecaoIndicador:
    """
    Obtém a projeção atual do IPCA no site da ANBIMA.

    A função baixa a planilha XLS de indicadores da ANBIMA e extrai os
    dados da projeção do IPCA.

    Returns:
        ProjecaoIndicador: Objeto contendo:
            - ultima_atualizacao (dt.datetime): Data e hora da última
              atualização.
            - periodo_referencia (str): Período de referência no formato
              "MMM/YY" (ex.: "mar/26").
            - valor_projetado (float): Valor projetado do IPCA (decimal).

    Raises:
        ConnectionError: Se houver erro de conexão com o site da ANBIMA.
        ValueError: Se os dados esperados não forem encontrados na
            planilha.

    Notes:
        Requer conexão com a internet para acessar o site da ANBIMA.

    Examples:
        >>> from pyield import ipca
        >>> # Obter a projeção atual do IPCA na ANBIMA
        >>> ipca.projected_rate()
        ProjecaoIndicador(ultima_atualizacao=..., periodo_referencia=..., valor_projetado=...)
    """
    conteudo = _baixar_planilha()
    df = pl.read_excel(conteudo, has_header=False)

    # Linha 0: "Data e Hora da Última Atualização: DD/MM/YYYY - HH:MM h"
    texto_atualizacao = df.item(0, "column_1")
    ultima_atualizacao = _extrair_datetime(texto_atualizacao)

    # Linha do IPCA: column_1 começa com "IPCA" e column_2 com "Projeção"
    linha_ipca = df.filter(
        pl.col("column_1").str.starts_with("IPCA")
        & pl.col("column_2").str.starts_with("Projeção")
    )
    if linha_ipca.is_empty():
        raise ValueError("Não foi possível encontrar a projeção do IPCA na planilha.")

    periodo_referencia = _extrair_periodo(linha_ipca.item(0, "column_2"))
    valor_projetado = round(float(linha_ipca.item(0, "column_3")) / 100, 4)

    return ProjecaoIndicador(
        ultima_atualizacao=ultima_atualizacao,
        periodo_referencia=periodo_referencia,
        valor_projetado=valor_projetado,
    )

rates(start, end)

Obtém as taxas mensais do IPCA para um intervalo de datas.

Realiza chamada à API do portal de dados do IBGE no formato: https://servicodados.ibge.gov.br/api/v3/agregados/6691/periodos/YYYYMM-YYYYMM/variaveis/63?localidades=N1[all]

Parameters:

Name Type Description Default
start DateLike

Data de início do intervalo.

 required
end DateLike

Data de fim do intervalo.

 required

Returns:

Type Description
DataFrame

pl.DataFrame com colunas 'periodo' e 'valor'.
Output Columns
  • periodo (Int64): período no formato YYYYMM.
  • valor (Float64): taxa mensal em decimal.

Examples:

>>> from pyield import ipca
>>> # Obter as taxas do IPCA para o primeiro trimestre de 2025
>>> ipca.rates("01-01-2025", "01-03-2025")
shape: (3, 2)
┌─────────┬────────┐
│ periodo ┆ valor  │
│ ---     ┆ ---    │
│ i64     ┆ f64    │
╞═════════╪════════╡
│ 202501  ┆ 0.0016 │
│ 202502  ┆ 0.0131 │
│ 202503  ┆ 0.0056 │
└─────────┴────────┘
Source code in pyield/ipca/historical.py 
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
def rates(start: DateLike, end: DateLike) -> pl.DataFrame:
    """Obtém as taxas mensais do IPCA para um intervalo de datas.

    Realiza chamada à API do portal de dados do IBGE no formato:
    https://servicodados.ibge.gov.br/api/v3/agregados/6691/periodos/YYYYMM-YYYYMM/variaveis/63?localidades=N1[all]

    Args:
        start: Data de início do intervalo.
        end: Data de fim do intervalo.

    Returns:
        pl.DataFrame com colunas 'periodo' e 'valor'.

    Output Columns:
        * periodo (Int64): período no formato YYYYMM.
        * valor (Float64): taxa mensal em decimal.

    Examples:
        >>> from pyield import ipca
        >>> # Obter as taxas do IPCA para o primeiro trimestre de 2025
        >>> ipca.rates("01-01-2025", "01-03-2025")
        shape: (3, 2)
        ┌─────────┬────────┐
        │ periodo ┆ valor  │
        │ ---     ┆ ---    │
        │ i64     ┆ f64    │
        ╞═════════╪════════╡
        │ 202501  ┆ 0.0016 │
        │ 202502  ┆ 0.0131 │
        │ 202503  ┆ 0.0056 │
        └─────────┴────────┘
    """
    return _buscar_periodo(start, end, _VAR_TAXA, em_percentual=True)