Pular para conteúdo

IPCA

indice(data)

Número-índice do IPCA para um mês específico.

Parameters:

Name Type Description Default
data DateLike

Qualquer data dentro do mês desejado.

 required

Returns:

Type Description
float

Número-índice do IPCA ou nan se não disponível.

Examples:

>>> from pyield import ipca
>>> ipca.indice("01-01-2025")
7111.86
Source code in pyield/ipca/historico.py 
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
def indice(data: DateLike) -> float:
    """Número-índice do IPCA para um mês específico.

    Args:
        data: Qualquer data dentro do mês desejado.

    Returns:
        Número-índice do IPCA ou ``nan`` se não disponível.

    Examples:
        >>> from pyield import ipca
        >>> ipca.indice("01-01-2025")
        7111.86
    """
    if any_is_empty(data):
        return float("nan")
    return _extrair_escalar(indices(data, data), "indice")

indices(inicio, fim)

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
inicio DateLike

Data de início do intervalo.

 required
fim DateLike

Data de fim do intervalo.

 required

Returns:

Type Description
DataFrame

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

Examples:

>>> from pyield import ipca
>>> # Obter os números-índice do IPCA para o primeiro trimestre
>>> ipca.indices(inicio="01-01-2025", fim="01-03-2025")
shape: (3, 2)
┌─────────┬─────────┐
│ periodo ┆ indice  │
│ ---     ┆ ---     │
│ i64     ┆ f64     │
╞═════════╪═════════╡
│ 202501  ┆ 7111.86 │
│ 202502  ┆ 7205.03 │
│ 202503  ┆ 7245.38 │
└─────────┴─────────┘
Source code in pyield/ipca/historico.py 
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
def indices(inicio: DateLike, fim: 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:
        inicio: Data de início do intervalo.
        fim: Data de fim do intervalo.

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

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

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

indices_ultimos(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 'indice'.
Output Columns
  • periodo (Int64): período no formato YYYYMM.
  • indice (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.indices_ultimos(1)
>>> # Obter os números-índice do IPCA dos últimos 3 meses
>>> df = ipca.indices_ultimos(3)
Source code in pyield/ipca/historico.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
def indices_ultimos(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 'indice'.

    Output Columns:
        * periodo (Int64): período no formato YYYYMM.
        * indice (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.indices_ultimos(1)
        >>> # Obter os números-índice do IPCA dos últimos 3 meses
        >>> df = ipca.indices_ultimos(3)
    """
    return _buscar_ultimos(qtd_meses, _VAR_INDICE).rename({"valor": "indice"})

taxa(data)

Taxa mensal do IPCA para um mês específico.

Parameters:

Name Type Description Default
data DateLike

Qualquer data dentro do mês desejado.

 required

Returns:

Type Description
float

Taxa mensal do IPCA em decimal ou nan se não disponível.

Examples:

>>> from pyield import ipca
>>> ipca.taxa("01-01-2025")  # decimal (0.0016 = 0,16%)
0.0016
Source code in pyield/ipca/historico.py 
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
def taxa(data: DateLike) -> float:
    """Taxa mensal do IPCA para um mês específico.

    Args:
        data: Qualquer data dentro do mês desejado.

    Returns:
        Taxa mensal do IPCA em decimal ou ``nan`` se não disponível.

    Examples:
        >>> from pyield import ipca
        >>> ipca.taxa("01-01-2025")  # decimal (0.0016 = 0,16%)
        0.0016
    """
    if any_is_empty(data):
        return float("nan")
    return _extrair_escalar(taxas(data, data), "taxa")

taxa_projetada()

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.taxa_projetada()
ProjecaoIndicador(ultima_atualizacao=..., periodo_referencia=..., valor_projetado=...)
Source code in pyield/ipca/projetado.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 taxa_projetada() -> 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.taxa_projetada()
        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,
    )

taxas(inicio, fim)

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
inicio DateLike

Data de início do intervalo.

 required
fim DateLike

Data de fim do intervalo.

 required

Returns:

Type Description
DataFrame

pl.DataFrame com colunas 'periodo' e 'taxa' (decimal).
Output Columns
  • periodo (Int64): período no formato YYYYMM.
  • taxa (Float64): taxa mensal em decimal (ex: 0.0016 = 0,16%).

Examples:

>>> from pyield import ipca
>>> ipca.taxas("01-01-2025", "01-03-2025")  # decimal (0.0016 = 0,16%)
shape: (3, 2)
┌─────────┬────────┐
│ periodo ┆ taxa   │
│ ---     ┆ ---    │
│ i64     ┆ f64    │
╞═════════╪════════╡
│ 202501  ┆ 0.0016 │
│ 202502  ┆ 0.0131 │
│ 202503  ┆ 0.0056 │
└─────────┴────────┘
Source code in pyield/ipca/historico.py 
 88
 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
122
123
def taxas(inicio: DateLike, fim: 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:
        inicio: Data de início do intervalo.
        fim: Data de fim do intervalo.

    Returns:
        pl.DataFrame com colunas 'periodo' e 'taxa' (decimal).

    Output Columns:
        * periodo (Int64): período no formato YYYYMM.
        * taxa (Float64): taxa mensal em decimal (ex: 0.0016 = 0,16%).

    Examples:
        >>> from pyield import ipca
        >>> ipca.taxas("01-01-2025", "01-03-2025")  # decimal (0.0016 = 0,16%)
        shape: (3, 2)
        ┌─────────┬────────┐
        │ periodo ┆ taxa   │
        │ ---     ┆ ---    │
        │ i64     ┆ f64    │
        ╞═════════╪════════╡
        │ 202501  ┆ 0.0016 │
        │ 202502  ┆ 0.0131 │
        │ 202503  ┆ 0.0056 │
        └─────────┴────────┘
    """
    return (
        _buscar_periodo(inicio, fim, _VAR_TAXA)
        .with_columns(taxa=pct_para_decimal(pl.col("valor")))
        .select("periodo", "taxa")
    )

taxas_ultimas(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 'taxa' (decimal).
Output Columns
  • periodo (Int64): período no formato YYYYMM.
  • taxa (Float64): taxa mensal em decimal (ex: 0.0016 = 0,16%).

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.taxas_ultimas(1)
>>> # Obter as taxas do IPCA dos últimos 3 meses
>>> df = ipca.taxas_ultimas(3)
Source code in pyield/ipca/historico.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
def taxas_ultimas(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 'taxa' (decimal).

    Output Columns:
        * periodo (Int64): período no formato YYYYMM.
        * taxa (Float64): taxa mensal em decimal (ex: 0.0016 = 0,16%).

    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.taxas_ultimas(1)
        >>> # Obter as taxas do IPCA dos últimos 3 meses
        >>> df = ipca.taxas_ultimas(3)
    """
    return (
        _buscar_ultimos(qtd_meses, _VAR_TAXA)
        .with_columns(taxa=pct_para_decimal(pl.col("valor")))
        .select("periodo", "taxa")
    )