DadosAbertosBrasil.bacen

Módulo de captura de dados das APIs do Banco Central do Brasil.


View Source
"""Módulo de captura de dados das APIs do Banco Central do Brasil.

References
----------
.. [1] SGS - Sistema Gerenciador de Séries Temporais
    https://www3.bcb.gov.br/sgspub/
.. [2] Cotação do Câmbio
    https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/swagger-ui3
.. [3] Expectativas de Mercado
    https://olinda.bcb.gov.br/olinda/servico/Expectativas/versao/v1/swagger-ui3#/

"""

from datetime import datetime
from typing import Union, Optional

import pandas as pd

from ._utils import parse
from ._utils.get_data import get_data



def _df(path:str, params:dict=None) -> pd.DataFrame:
    data = get_data(
        endpoint = 'https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/',
        path = path,
        params = params
    )
    return pd.DataFrame(data['value'])



def moedas():
    """Obtém os nomes e símbolos das principais moedas internacionais.

    Returns
    -------
    pandas.core.frame.DataFrame
        DataFrame contendo os nomes e símbolos das principais moedas
        internacionais.

    See Also
    --------
    DadosAbertosBrasil.bacen.cambio :
        Utilize a função `bacen.moedas` para identificar os argumentos da
        função `bacen.cambio`.

    Notes
    -----
    Moedas do tipo 'A':
        - Para calcular o valor equivalente em US$ (dólar americano), divida o
          montante na moeda consultada pela respectiva paridade.
        - Para obter o valor em R$ (reais), multiplique o montante na moeda
          consultada pela respectiva taxa.
    Moedas do tipo 'B':
        - Para calcular o valor equivalente em US$ (dólar americano),
          multiplique o montante na moeda consultada pela respectiva paridade.
        - Para obter o valor em R$ (reais), multiplique o montante na moeda
          consultada pela respectiva taxa. 

    References
    ----------
    .. [1] Cotação do Câmbio
        https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/swagger-ui3

    Examples
    --------
    >>> bacen.moedas()
      simbolo                      nome tipo
    0     AUD         Dólar australiano    B
    1     CAD           Dólar canadense    A
    2     CHF              Franco suíço    A
    3     DKK        Coroa dinamarquesa    A
    4     EUR                      Euro    B
    5     GBP           Libra Esterlina    B
    6     JPY                      Iene    A
    7     NOK          Coroa norueguesa    A
    8     SEK               Coroa sueca    A
    9     USD  Dólar dos Estados Unidos    A

    """

    df = _df('Moedas')
    df.columns = ['simbolo', 'nome', 'tipo']
    return df



def cambio(
        moedas = 'USD',
        inicio: Union[datetime, str] = '2000-01-01',
        fim: Union[datetime, str] = None,
        cotacao: str = 'compra',
        boletim: str = 'fechamento',
        index: bool = False
    ) -> pd.DataFrame:
    """Taxa de câmbio das principais moedas internacionais.

    É possível escolher várias moedas inserindo uma lista no campo `moeda`.
    Defina o período da consulta pelos campos `inicio` e `fim`.

    Parameters
    ----------
    moedas : str or list of str, default='USD'
        Sigla da moeda ou lista de siglas de moedas que serão pesquisadas no
        formato 'MMM' (três letras). Utilize a função `bacen.moedas` para
        obter a lista de moedas válidas.
    inicio : datetime or str, default='2000-01-01'
        String no formato de data 'AAAA-MM-DD' que representa o primeiro dia
        da pesquisa.
    fim : datetime or str, default=None
        String no formato de data 'AAAA-MM-DD' que representa o último dia da
        pesquisa. Caso este campo seja None, será considerada a data de hoje.
    cotacao : {'compra', 'venda'}, default='compra'
        Tipo de cotação.
    boletim : {'abertura', 'intermediário', 'fechamento'}, default='fechamento'
        Tipo de boletim.
    index : bool, default=False
        Define se a coluna 'Data' será o index do DataFrame.

    Returns
    -------
    pandas.core.frame.DataFrame
        DataFrame contendo as cotações diárias das moedas selecionadas.

    Raises
    ------
    DAB_DataError
        Caso seja inserida uma data inválida.
    DAB_MoedaError
        Caso seja inserida uma moeda inválida.
    ValueError
        Caso nenhum dado seja encontrado devido a argumentos inválidos.

    See Also
    --------
    DadosAbertosBrasil.bacen.moedas :
        Utilize a função `bacen.moedas` para identificar as moedas que serão
        usadas no argumento da função `bacen.cambio`.

    References
    ----------
    .. [1] Cotação do Câmbio
        https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/swagger-ui3

    Examples
    --------
    Retornar uma moeda usando argumentos padrões.

    >>> bacen.cambio(moedas='EUR')
                Data      EUR
    0    2000-01-03  1.84601
    1    2000-01-04  1.88695
    2    2000-01-05  1.91121
    3    2000-01-06  1.90357
    4    2000-01-07  1.87790
    ..          ...      ...

    Retornar várias moedas, alterando argumentos.

    >>> bacen.cambio(
    ...     moedas = ['USD', 'CAD'],
    ...     inicio = '2021-01-01',
    ...     fim = '2021-01-10',
    ...     cotacao = 'venda',
    ...     boletim = 'abertura',
    ...     index = True
    ... )
                    USD     CAD
    Data                      
    2021-01-04  5.1402  4.0500
    2021-01-05  5.3405  4.1890
    2021-01-06  5.3013  4.1798
    2021-01-07  5.3174  4.1833
    2021-01-08  5.3612  4.2237

    """

    inicio = parse.data(inicio, 'bacen')
    if fim == None:
        fim = datetime.today().strftime('%m-%d-%Y')
    else:
        fim = parse.data(fim, 'bacen')
    
    moedas = parse.moeda(moedas)
    
    cotacao_moedas = []
    for moeda in moedas:
        cotacao_moeda = _df(
            "CotacaoMoedaPeriodo(" \
            + "[email protected]," \
            + "[email protected]," \
            + "[email protected])" \
            + f"[email protected]='{moeda}'" \
            + f"&@dataInicial='{inicio}'" \
            + f"&@dataFinalCotacao='{fim}'" \
            + f"&$filter=contains(tipoBoletim%2C'{boletim.title()}')" \
            + f"&$select=cotacao{cotacao.title()},dataHoraCotacao"
        )
        if cotacao_moeda.empty:
            raise ValueError('Nenhum dado encontrado. Verifique os argumentos da função.')
        cotacao_moeda.dataHoraCotacao = cotacao_moeda.dataHoraCotacao \
            .apply(lambda x: datetime.strptime(x[:10], '%Y-%m-%d'))

        cotacao_moedas.append(
            cotacao_moeda.rename(columns = {
                f'cotacao{cotacao.title()}': moeda,
                'dataHoraCotacao': 'Data'
            }).groupby('Data').last())

    cotacoes = pd.concat(cotacao_moedas, axis=1).reset_index()

    cotacoes.Data = pd.to_datetime(cotacoes.Data, format='%Y-%m-%d %H:%M:%S')
    if index:
        cotacoes.set_index('Data', inplace=True)
    
    return cotacoes



def serie(
        cod: int,
        ultimos: Optional[int] = None,
        inicio: Union[datetime, str] = None,
        fim: Union[datetime, str] = None,
        index: bool = False
    ) -> pd.DataFrame:
    """Série do Sistema Gerenciador de Série Temporais (SGS) do Banco Central.

    Parameters
    ----------
    cod : int
        Código da série temporal.
        Utilize o seguinte link para obter o número da série desejada:
        https://www3.bcb.gov.br/sgspub/
    ultimos : int, optional
        Retorna os últimos N valores da série numérica.
    inicio : datetime or str, optional
        Valor datetime ou string no formato de data 'AAAA-MM-DD' que
        representa o primeiro dia da pesquisa.
    fim : datetime or str, optional
        Valor datetime ou string no formato de data 'AAAA-MM-DD' que
        representa o último dia da pesquisa. Caso este campo seja None, será
        considerada a data de hoje.
    index : bool, default=False
        Define se a coluna 'data' será o index do DataFrame.

    Returns
    -------
    pandas.core.frame.DataFrame
        DataFrame contendo os valores da série temporal pesquisada.

    Raises
    ------
    JSONDecodeError
        Em caso de parâmetros inválidos.

    See Also
    --------
    DadosAbertosBrasil.favoritos :
        O módulo `favoritos` apresenta as principais séries temporáis do Banco
        Central do Brasil.

    Notes
    -----
    Os argumentos `inicio` e `fim` devem ser usados em conjunto para
    funcionar.

    References
    ----------
    .. [1] SGS - Sistema Gerenciador de Séries Temporais
        https://www3.bcb.gov.br/sgspub/

    Examples
    --------
    Capturar a taxa SELIC desde 2010 até 2021.

    >>> bacen.serie(cod=432, inicio='2010-01-01', fim='2021-01-01')
               data valor
    0    2010-01-01  8.75
    1    2010-01-02  8.75
    2    2010-01-03  8.75
    3    2010-01-04  8.75
    4    2010-01-05  8.75
    ..          ...   ...

    Capturar os últimos 5 valores da meta de inflação.

    >>> bacen.serie(cod=13521, ultimos=5)
            data valor
    0 2019-01-01  4.25
    1 2020-01-01  4.00
    2 2021-01-01  3.75
    3 2022-01-01  3.50
    4 2023-01-01  3.25

    Capturar toda a série de reservas internacionais (em milhões de dólares)
    usando a data como index do DataFrame.

    >>> bacen.serie(cod=3546, index=True)
                 valor
    data              
    1970-12-01    1187
    1971-01-01    1229
    1971-02-01    1280
    1971-03-01    1316
    1971-04-01    1379
    ...            ...

    """

    path = f'dados/serie/bcdata.sgs.{cod}/dados'
    if ultimos is not None:
        path += f'/ultimos/{ultimos}'

    params = []
    if inicio is not None:
        params.append(f"dataInicial={parse.data(inicio, modulo='sgs')}")
    if fim is not None:
        params.append(f"dataFinal={parse.data(fim, modulo='sgs')}")

    if len(params) > 0:
        path += f'?{"&".join(params)}'

    data = get_data(
        endpoint = 'https://api.bcb.gov.br/',
        path = path
    )

    df = pd.DataFrame(data)

    df.data = pd.to_datetime(df.data, format='%d/%m/%Y')
    if 'datafim' in df.columns:
        df.datafim = pd.to_datetime(df.datafim, format='%d/%m/%Y')

    if index:
        df.set_index('data', inplace=True)

    return df



def expectativas(
        expectativa: str,
        indicador: Optional[str] = None,
        top: Optional[int] = None,
        ordenar_por: str = 'Data',
        asc: bool = False
    ) -> pd.DataFrame:
    """Expectativas de mercado para os principais indicadores macroeconômicos.

    Parameters
    ----------
    expectativa : str
        Tipo ou periodicidade da expectativa.
            - 'mensal' ou 'mensais';
            - 'trimestral' ou 'trimestrais';
            - 'anual' ou 'anuais';
            - 'inflacao' ou 'inflacao12meses';
            - 'top5mensal' ou 'top5mensais',
            - 'top5anual' ou 'top5anuais',
            - 'instituicoes'.
    indicador : str, optional
        Capturar apenas o indicador desejado. Deve ser um dos seguintes
        indicadores, desde que esteja de acordo com a `expectativa` escolhida:
            - 'Balança Comercial';
            - 'Balanço de Pagamentos';
            - 'Fiscal';
            - 'IGP-DI';
            - 'IGP-M';
            - 'INPC';
            - 'IPA-DI';
            - 'IPA-M';
            - 'IPC-FIPE';
            - 'IPC-FIPEPreços administrados por contrato e monitorados';
            - 'IPCA';
            - 'IPCA-15';
            - 'Meta para taxa over-selic';
            - 'PIB Agropecuária';
            - 'PIB Industrial';
            - 'PIB Serviços';
            - 'PIB Total';
            - 'PIB TotalMeta para taxa over-selic';
            - 'Preços administrados por contrato e monitorados';
            - 'Produção industrial';
            - 'Taxa de câmbio'.
        Caso o valor seja None, retorna todos os indicadores disponíveis.
    top : int, optional
        Número máximo de registros que será retornado.
    ordenar_por : str, default='Data'
        Por qual coluna da tabela os registros serão ordenados.
    asc : bool, default=False
        - Se True, ordena os registros pela coluna selecionada no argumento
          `ordenar_por` em ordem crescente (A-Z ou 0-9);
        - Se False, ordena em ordem descrescente (Z-A ou 9-0).

    Returns
    -------
    pandas.core.frame.DataFrame
        Tabela contendo uma breve estatística descritiva da expectativa de
        mercado de cada indicador poe período de referência.

    Raises
    ------
    ValueError
        Em caso de parâmetros inválidos.

    References
    ----------
    .. [1] Expectativas de Mercado
        https://olinda.bcb.gov.br/olinda/servico/Expectativas/versao/v1/swagger-ui3#/

    Examples
    --------
    >>> bacen.expectativa(expectativa='mensal', indicador='IGP-M')
          Indicador        Data DataReferencia  Media  Mediana  DesvioPadrao  ...
    0         IGP-M  2021-06-25        07/2022   0.31     0.30          0.21  ...
    1         IGP-M  2021-06-25        07/2021   0.64     0.61          0.42  ...
    2         IGP-M  2021-06-25        06/2021   1.25     1.10          0.58  ...
    3         IGP-M  2021-06-25        11/2022   0.47     0.47          0.16  ...
    4         IGP-M  2021-06-25        11/2021   0.50     0.50          0.24  ...
    ..          ...         ...            ...    ...      ...           ...  ...

    >>> bacen.expectativa(
    ...     expectativa = 'trimestral',
    ...     indicador = 'PIB Total',
    ...     top = 3,
    ...     ordenar_por = 'Media',
    ...     asc = True
    ... )
       Indicador        Data DataReferencia  Media  Mediana  DesvioPadrao  ...
    0  PIB Total  2020-06-02         2/2020 -14.00    -14.0          3.92  ...
    1  PIB Total  2020-06-09         2/2020 -14.00    -13.4          3.55  ...
    2  PIB Total  2020-06-01         2/2020 -13.99    -14.0          3.91  ...

    """

    URL = 'https://olinda.bcb.gov.br/olinda/servico/Expectativas/versao/v1/odata/'
    orderby = f'&%24orderby={ordenar_por}%20{"asc" if asc else "desc"}'
    topn = '' if top is None else f'&%24top={top}'

    expectativa = expectativa.lower()
    if expectativa in ('mensal', 'mensais'):
        expec = 'ExpectativaMercadoMensais'
        KPIS = (
            'IGP-DI',
            'IGP-M',
            'INPC',
            'IPA-DI',
            'IPA-M',
            'IPCA',
            'IPCA-15',
            'IPC-FIPE',
            'Produção industrial',
            'Meta para taxa over-selic',
            'Taxa de câmbio'
        )
    elif expectativa in ('trimestral', 'trimestrais'):
        expec = 'ExpectativasMercadoTrimestrais'
        KPIS = (
            'PIB Agropecuária',
            'PIB Industrial',
            'PIB Serviços',
            'PIB Total'
        )
    elif expectativa in ('anual', 'anuais'):
        expec = 'ExpectativasMercadoAnuais'
        KPIS = (
            'Balança Comercial',
            'Balanço de Pagamentos',
            'Fiscal',
            'IGP-DI',
            'IGP-M',
            'INPC',
            'IPA-DI',
            'IPA-M',
            'IPCA',
            'IPCA-15',
            'IPC-FIPE',
            'Preços administrados por contrato e monitorados',
            'Produção industrial',
            'PIB Agropecuária',
            'PIB Industrial',
            'PIB Serviços',
            'PIB Total',
            'Meta para taxa over-selic',
            'Taxa de câmbio'
        )
    elif expectativa in ('inflacao', 'inflacao12meses'):
        expec = 'ExpectativasMercadoInflacao12Meses'
        KPIS = (
            'IGP-DI',
            'IGP-M',
            'INPC',
            'IPA-DI',
            'IPA-M',
            'IPCA',
            'IPCA-15',
            'IPC-FIPE'
        )
    elif expectativa in ('top5mensal', 'top5mensais'):
        expec = 'ExpectativasMercadoTop5Mensais'
        KPIS = (
            'IGP-DI',
            'IGP-M',
            'IPCA',
            'Meta para taxa over-selic',
            'Taxa de câmbio'
        )
    elif expectativa in ('top5anual', 'top5anuais'):
        expec = 'ExpectativasMercadoTop5Anuais'
        KPIS = (
            'IGP-DI',
            'IGP-M',
            'IPCA',
            'Meta para taxa over-selic',
            'Taxa de câmbio'
        )
    elif expectativa == 'instituicoes':
        expec = 'ExpectativasMercadoInstituicoes'
        KPIS = (
            'Balança Comercial',
            'Balanço de Pagamentos',
            'Fiscal',
            'IGP-DI',
            'IGP-M',
            'INPC',
            'IPA-DI',
            'IPA-M',
            'IPCA',
            'IPCA-15',
            'IPC-FIPE',
            'Preços administrados por contrato e monitorados',
            'Produção industrial',
            'PIB Agropecuária',
            'PIB Industrial', 'PIB Serviços',
            'PIB Total',
            'Meta para taxa over-selic',
            'Taxa de câmbio'
        )
    else:
        raise ValueError('''Valor inválido para o argumento `expectativa`. Insira um dos seguintes valores:
            - 'mensal' ou 'mensais';
            - 'trimestral' ou 'trimestrais';
            - 'anual' ou 'anuais';
            - 'inflacao' ou 'inflacao12meses';
            - 'top5mensal' ou 'top5mensais',
            - 'top5anual' ou 'top5anuais',
            - 'instituicoes'.''')

    if indicador is None:
        kpi = ''
    elif indicador in KPIS:
        kpi = f"&%24filter=Indicador%20eq%20'{indicador}'"
    else:
        raise ValueError(f''''{indicador}' é um indicador inválido para expectativa '{expectativa.title()}'. Insira um dos seguintes valores:
        - {", ".join(KPIS)}.''')

    path = f'{expec}?%24format=json{orderby}{kpi}{topn}'
    data = get_data(URL, path=path)
    return pd.DataFrame(data['value'])
#   def moedas():
View Source
def moedas():
    """Obtém os nomes e símbolos das principais moedas internacionais.

    Returns
    -------
    pandas.core.frame.DataFrame
        DataFrame contendo os nomes e símbolos das principais moedas
        internacionais.

    See Also
    --------
    DadosAbertosBrasil.bacen.cambio :
        Utilize a função `bacen.moedas` para identificar os argumentos da
        função `bacen.cambio`.

    Notes
    -----
    Moedas do tipo 'A':
        - Para calcular o valor equivalente em US$ (dólar americano), divida o
          montante na moeda consultada pela respectiva paridade.
        - Para obter o valor em R$ (reais), multiplique o montante na moeda
          consultada pela respectiva taxa.
    Moedas do tipo 'B':
        - Para calcular o valor equivalente em US$ (dólar americano),
          multiplique o montante na moeda consultada pela respectiva paridade.
        - Para obter o valor em R$ (reais), multiplique o montante na moeda
          consultada pela respectiva taxa. 

    References
    ----------
    .. [1] Cotação do Câmbio
        https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/swagger-ui3

    Examples
    --------
    >>> bacen.moedas()
      simbolo                      nome tipo
    0     AUD         Dólar australiano    B
    1     CAD           Dólar canadense    A
    2     CHF              Franco suíço    A
    3     DKK        Coroa dinamarquesa    A
    4     EUR                      Euro    B
    5     GBP           Libra Esterlina    B
    6     JPY                      Iene    A
    7     NOK          Coroa norueguesa    A
    8     SEK               Coroa sueca    A
    9     USD  Dólar dos Estados Unidos    A

    """

    df = _df('Moedas')
    df.columns = ['simbolo', 'nome', 'tipo']
    return df

Obtém os nomes e símbolos das principais moedas internacionais.

Returns
  • pandas.core.frame.DataFrame: DataFrame contendo os nomes e símbolos das principais moedas internacionais.
See Also
Notes
  • Moedas do tipo 'A': Para calcular o valor equivalente em US$ (dólar americano), divida o montante na moeda consultada pela respectiva paridade. Para obter o valor em R$ (reais), multiplique o montante na moeda consultada pela respectiva taxa.
  • Moedas do tipo 'B': Para calcular o valor equivalente em US$ (dólar americano), multiplique o montante na moeda consultada pela respectiva paridade. Para obter o valor em R$ (reais), multiplique o montante na moeda consultada pela respectiva taxa.
Examples
>>> bacen.moedas()
  simbolo                      nome tipo
0     AUD         Dólar australiano    B
1     CAD           Dólar canadense    A
2     CHF              Franco suíço    A
3     DKK        Coroa dinamarquesa    A
4     EUR                      Euro    B
5     GBP           Libra Esterlina    B
6     JPY                      Iene    A
7     NOK          Coroa norueguesa    A
8     SEK               Coroa sueca    A
9     USD  Dólar dos Estados Unidos    A

#   def cambio( moedas='USD', inicio: Union[datetime.datetime, str] = '2000-01-01', fim: Union[datetime.datetime, str] = None, cotacao: str = 'compra', boletim: str = 'fechamento', index: bool = False ) -> pandas.core.frame.DataFrame:
View Source
def cambio(
        moedas = 'USD',
        inicio: Union[datetime, str] = '2000-01-01',
        fim: Union[datetime, str] = None,
        cotacao: str = 'compra',
        boletim: str = 'fechamento',
        index: bool = False
    ) -> pd.DataFrame:
    """Taxa de câmbio das principais moedas internacionais.

    É possível escolher várias moedas inserindo uma lista no campo `moeda`.
    Defina o período da consulta pelos campos `inicio` e `fim`.

    Parameters
    ----------
    moedas : str or list of str, default='USD'
        Sigla da moeda ou lista de siglas de moedas que serão pesquisadas no
        formato 'MMM' (três letras). Utilize a função `bacen.moedas` para
        obter a lista de moedas válidas.
    inicio : datetime or str, default='2000-01-01'
        String no formato de data 'AAAA-MM-DD' que representa o primeiro dia
        da pesquisa.
    fim : datetime or str, default=None
        String no formato de data 'AAAA-MM-DD' que representa o último dia da
        pesquisa. Caso este campo seja None, será considerada a data de hoje.
    cotacao : {'compra', 'venda'}, default='compra'
        Tipo de cotação.
    boletim : {'abertura', 'intermediário', 'fechamento'}, default='fechamento'
        Tipo de boletim.
    index : bool, default=False
        Define se a coluna 'Data' será o index do DataFrame.

    Returns
    -------
    pandas.core.frame.DataFrame
        DataFrame contendo as cotações diárias das moedas selecionadas.

    Raises
    ------
    DAB_DataError
        Caso seja inserida uma data inválida.
    DAB_MoedaError
        Caso seja inserida uma moeda inválida.
    ValueError
        Caso nenhum dado seja encontrado devido a argumentos inválidos.

    See Also
    --------
    DadosAbertosBrasil.bacen.moedas :
        Utilize a função `bacen.moedas` para identificar as moedas que serão
        usadas no argumento da função `bacen.cambio`.

    References
    ----------
    .. [1] Cotação do Câmbio
        https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/swagger-ui3

    Examples
    --------
    Retornar uma moeda usando argumentos padrões.

    >>> bacen.cambio(moedas='EUR')
                Data      EUR
    0    2000-01-03  1.84601
    1    2000-01-04  1.88695
    2    2000-01-05  1.91121
    3    2000-01-06  1.90357
    4    2000-01-07  1.87790
    ..          ...      ...

    Retornar várias moedas, alterando argumentos.

    >>> bacen.cambio(
    ...     moedas = ['USD', 'CAD'],
    ...     inicio = '2021-01-01',
    ...     fim = '2021-01-10',
    ...     cotacao = 'venda',
    ...     boletim = 'abertura',
    ...     index = True
    ... )
                    USD     CAD
    Data                      
    2021-01-04  5.1402  4.0500
    2021-01-05  5.3405  4.1890
    2021-01-06  5.3013  4.1798
    2021-01-07  5.3174  4.1833
    2021-01-08  5.3612  4.2237

    """

    inicio = parse.data(inicio, 'bacen')
    if fim == None:
        fim = datetime.today().strftime('%m-%d-%Y')
    else:
        fim = parse.data(fim, 'bacen')
    
    moedas = parse.moeda(moedas)
    
    cotacao_moedas = []
    for moeda in moedas:
        cotacao_moeda = _df(
            "CotacaoMoedaPeriodo(" \
            + "[email protected]," \
            + "[email protected]," \
            + "[email protected])" \
            + f"[email protected]='{moeda}'" \
            + f"&@dataInicial='{inicio}'" \
            + f"&@dataFinalCotacao='{fim}'" \
            + f"&$filter=contains(tipoBoletim%2C'{boletim.title()}')" \
            + f"&$select=cotacao{cotacao.title()},dataHoraCotacao"
        )
        if cotacao_moeda.empty:
            raise ValueError('Nenhum dado encontrado. Verifique os argumentos da função.')
        cotacao_moeda.dataHoraCotacao = cotacao_moeda.dataHoraCotacao \
            .apply(lambda x: datetime.strptime(x[:10], '%Y-%m-%d'))

        cotacao_moedas.append(
            cotacao_moeda.rename(columns = {
                f'cotacao{cotacao.title()}': moeda,
                'dataHoraCotacao': 'Data'
            }).groupby('Data').last())

    cotacoes = pd.concat(cotacao_moedas, axis=1).reset_index()

    cotacoes.Data = pd.to_datetime(cotacoes.Data, format='%Y-%m-%d %H:%M:%S')
    if index:
        cotacoes.set_index('Data', inplace=True)
    
    return cotacoes

Taxa de câmbio das principais moedas internacionais.

É possível escolher várias moedas inserindo uma lista no campo moeda. Defina o período da consulta pelos campos inicio e fim.

Parameters
  • moedas (str or list of str, default='USD'): Sigla da moeda ou lista de siglas de moedas que serão pesquisadas no formato 'MMM' (três letras). Utilize a função bacen.moedas para obter a lista de moedas válidas.
  • inicio (datetime or str, default='2000-01-01'): String no formato de data 'AAAA-MM-DD' que representa o primeiro dia da pesquisa.
  • fim (datetime or str, default=None): String no formato de data 'AAAA-MM-DD' que representa o último dia da pesquisa. Caso este campo seja None, será considerada a data de hoje.
  • cotacao ({'compra', 'venda'}, default='compra'): Tipo de cotação.
  • boletim ({'abertura', 'intermediário', 'fechamento'}, default='fechamento'): Tipo de boletim.
  • index (bool, default=False): Define se a coluna 'Data' será o index do DataFrame.
Returns
  • pandas.core.frame.DataFrame: DataFrame contendo as cotações diárias das moedas selecionadas.
Raises
  • DAB_DataError: Caso seja inserida uma data inválida.
  • DAB_MoedaError: Caso seja inserida uma moeda inválida.
  • ValueError: Caso nenhum dado seja encontrado devido a argumentos inválidos.
See Also
Examples
  • Retornar uma moeda usando argumentos padrões.
>>> bacen.cambio(moedas='EUR')
           Data      EUR
0    2000-01-03  1.84601
1    2000-01-04  1.88695
2    2000-01-05  1.91121
3    2000-01-06  1.90357
4    2000-01-07  1.87790
..          ...      ...
  • Retornar várias moedas, alterando argumentos.
>>> bacen.cambio(
...     moedas = ['USD', 'CAD'],
...     inicio = '2021-01-01',
...     fim = '2021-01-10',
...     cotacao = 'venda',
...     boletim = 'abertura',
...     index = True
... )
               USD     CAD
Data                      
2021-01-04  5.1402  4.0500
2021-01-05  5.3405  4.1890
2021-01-06  5.3013  4.1798
2021-01-07  5.3174  4.1833
2021-01-08  5.3612  4.2237

#   def serie( cod: int, ultimos: Union[int, NoneType] = None, inicio: Union[datetime.datetime, str] = None, fim: Union[datetime.datetime, str] = None, index: bool = False ) -> pandas.core.frame.DataFrame:
View Source
def serie(
        cod: int,
        ultimos: Optional[int] = None,
        inicio: Union[datetime, str] = None,
        fim: Union[datetime, str] = None,
        index: bool = False
    ) -> pd.DataFrame:
    """Série do Sistema Gerenciador de Série Temporais (SGS) do Banco Central.

    Parameters
    ----------
    cod : int
        Código da série temporal.
        Utilize o seguinte link para obter o número da série desejada:
        https://www3.bcb.gov.br/sgspub/
    ultimos : int, optional
        Retorna os últimos N valores da série numérica.
    inicio : datetime or str, optional
        Valor datetime ou string no formato de data 'AAAA-MM-DD' que
        representa o primeiro dia da pesquisa.
    fim : datetime or str, optional
        Valor datetime ou string no formato de data 'AAAA-MM-DD' que
        representa o último dia da pesquisa. Caso este campo seja None, será
        considerada a data de hoje.
    index : bool, default=False
        Define se a coluna 'data' será o index do DataFrame.

    Returns
    -------
    pandas.core.frame.DataFrame
        DataFrame contendo os valores da série temporal pesquisada.

    Raises
    ------
    JSONDecodeError
        Em caso de parâmetros inválidos.

    See Also
    --------
    DadosAbertosBrasil.favoritos :
        O módulo `favoritos` apresenta as principais séries temporáis do Banco
        Central do Brasil.

    Notes
    -----
    Os argumentos `inicio` e `fim` devem ser usados em conjunto para
    funcionar.

    References
    ----------
    .. [1] SGS - Sistema Gerenciador de Séries Temporais
        https://www3.bcb.gov.br/sgspub/

    Examples
    --------
    Capturar a taxa SELIC desde 2010 até 2021.

    >>> bacen.serie(cod=432, inicio='2010-01-01', fim='2021-01-01')
               data valor
    0    2010-01-01  8.75
    1    2010-01-02  8.75
    2    2010-01-03  8.75
    3    2010-01-04  8.75
    4    2010-01-05  8.75
    ..          ...   ...

    Capturar os últimos 5 valores da meta de inflação.

    >>> bacen.serie(cod=13521, ultimos=5)
            data valor
    0 2019-01-01  4.25
    1 2020-01-01  4.00
    2 2021-01-01  3.75
    3 2022-01-01  3.50
    4 2023-01-01  3.25

    Capturar toda a série de reservas internacionais (em milhões de dólares)
    usando a data como index do DataFrame.

    >>> bacen.serie(cod=3546, index=True)
                 valor
    data              
    1970-12-01    1187
    1971-01-01    1229
    1971-02-01    1280
    1971-03-01    1316
    1971-04-01    1379
    ...            ...

    """

    path = f'dados/serie/bcdata.sgs.{cod}/dados'
    if ultimos is not None:
        path += f'/ultimos/{ultimos}'

    params = []
    if inicio is not None:
        params.append(f"dataInicial={parse.data(inicio, modulo='sgs')}")
    if fim is not None:
        params.append(f"dataFinal={parse.data(fim, modulo='sgs')}")

    if len(params) > 0:
        path += f'?{"&".join(params)}'

    data = get_data(
        endpoint = 'https://api.bcb.gov.br/',
        path = path
    )

    df = pd.DataFrame(data)

    df.data = pd.to_datetime(df.data, format='%d/%m/%Y')
    if 'datafim' in df.columns:
        df.datafim = pd.to_datetime(df.datafim, format='%d/%m/%Y')

    if index:
        df.set_index('data', inplace=True)

    return df

Série do Sistema Gerenciador de Série Temporais (SGS) do Banco Central.

Parameters
  • cod (int): Código da série temporal. Utilize o seguinte link para obter o número da série desejada: https://www3.bcb.gov.br/sgspub/
  • ultimos (int, optional): Retorna os últimos N valores da série numérica.
  • inicio (datetime or str, optional): Valor datetime ou string no formato de data 'AAAA-MM-DD' que representa o primeiro dia da pesquisa.
  • fim (datetime or str, optional): Valor datetime ou string no formato de data 'AAAA-MM-DD' que representa o último dia da pesquisa. Caso este campo seja None, será considerada a data de hoje.
  • index (bool, default=False): Define se a coluna 'data' será o index do DataFrame.
Returns
  • pandas.core.frame.DataFrame: DataFrame contendo os valores da série temporal pesquisada.
Raises
  • JSONDecodeError: Em caso de parâmetros inválidos.
See Also
Notes
  • Os argumentos inicio e fim devem ser usados em conjunto para funcionar.
Examples
  • Capturar a taxa SELIC desde 2010 até 2021.
>>> bacen.serie(cod=432, inicio='2010-01-01', fim='2021-01-01')
           data valor
0    2010-01-01  8.75
1    2010-01-02  8.75
2    2010-01-03  8.75
3    2010-01-04  8.75
4    2010-01-05  8.75
..          ...   ...
  • Capturar os últimos 5 valores da meta de inflação.
>>> bacen.serie(cod=13521, ultimos=5)
        data valor
0 2019-01-01  4.25
1 2020-01-01  4.00
2 2021-01-01  3.75
3 2022-01-01  3.50
4 2023-01-01  3.25
  • Capturar toda a série de reservas internacionais (em milhões de dólares) usando a data como index do DataFrame.
>>> bacen.serie(cod=3546, index=True)
             valor
data              
1970-12-01    1187
1971-01-01    1229
1971-02-01    1280
1971-03-01    1316
1971-04-01    1379
...            ...

#   def expectativas( expectativa: str, indicador: Union[str, NoneType] = None, top: Union[int, NoneType] = None, ordenar_por: str = 'Data', asc: bool = False ) -> pandas.core.frame.DataFrame:
View Source
def expectativas(
        expectativa: str,
        indicador: Optional[str] = None,
        top: Optional[int] = None,
        ordenar_por: str = 'Data',
        asc: bool = False
    ) -> pd.DataFrame:
    """Expectativas de mercado para os principais indicadores macroeconômicos.

    Parameters
    ----------
    expectativa : str
        Tipo ou periodicidade da expectativa.
            - 'mensal' ou 'mensais';
            - 'trimestral' ou 'trimestrais';
            - 'anual' ou 'anuais';
            - 'inflacao' ou 'inflacao12meses';
            - 'top5mensal' ou 'top5mensais',
            - 'top5anual' ou 'top5anuais',
            - 'instituicoes'.
    indicador : str, optional
        Capturar apenas o indicador desejado. Deve ser um dos seguintes
        indicadores, desde que esteja de acordo com a `expectativa` escolhida:
            - 'Balança Comercial';
            - 'Balanço de Pagamentos';
            - 'Fiscal';
            - 'IGP-DI';
            - 'IGP-M';
            - 'INPC';
            - 'IPA-DI';
            - 'IPA-M';
            - 'IPC-FIPE';
            - 'IPC-FIPEPreços administrados por contrato e monitorados';
            - 'IPCA';
            - 'IPCA-15';
            - 'Meta para taxa over-selic';
            - 'PIB Agropecuária';
            - 'PIB Industrial';
            - 'PIB Serviços';
            - 'PIB Total';
            - 'PIB TotalMeta para taxa over-selic';
            - 'Preços administrados por contrato e monitorados';
            - 'Produção industrial';
            - 'Taxa de câmbio'.
        Caso o valor seja None, retorna todos os indicadores disponíveis.
    top : int, optional
        Número máximo de registros que será retornado.
    ordenar_por : str, default='Data'
        Por qual coluna da tabela os registros serão ordenados.
    asc : bool, default=False
        - Se True, ordena os registros pela coluna selecionada no argumento
          `ordenar_por` em ordem crescente (A-Z ou 0-9);
        - Se False, ordena em ordem descrescente (Z-A ou 9-0).

    Returns
    -------
    pandas.core.frame.DataFrame
        Tabela contendo uma breve estatística descritiva da expectativa de
        mercado de cada indicador poe período de referência.

    Raises
    ------
    ValueError
        Em caso de parâmetros inválidos.

    References
    ----------
    .. [1] Expectativas de Mercado
        https://olinda.bcb.gov.br/olinda/servico/Expectativas/versao/v1/swagger-ui3#/

    Examples
    --------
    >>> bacen.expectativa(expectativa='mensal', indicador='IGP-M')
          Indicador        Data DataReferencia  Media  Mediana  DesvioPadrao  ...
    0         IGP-M  2021-06-25        07/2022   0.31     0.30          0.21  ...
    1         IGP-M  2021-06-25        07/2021   0.64     0.61          0.42  ...
    2         IGP-M  2021-06-25        06/2021   1.25     1.10          0.58  ...
    3         IGP-M  2021-06-25        11/2022   0.47     0.47          0.16  ...
    4         IGP-M  2021-06-25        11/2021   0.50     0.50          0.24  ...
    ..          ...         ...            ...    ...      ...           ...  ...

    >>> bacen.expectativa(
    ...     expectativa = 'trimestral',
    ...     indicador = 'PIB Total',
    ...     top = 3,
    ...     ordenar_por = 'Media',
    ...     asc = True
    ... )
       Indicador        Data DataReferencia  Media  Mediana  DesvioPadrao  ...
    0  PIB Total  2020-06-02         2/2020 -14.00    -14.0          3.92  ...
    1  PIB Total  2020-06-09         2/2020 -14.00    -13.4          3.55  ...
    2  PIB Total  2020-06-01         2/2020 -13.99    -14.0          3.91  ...

    """

    URL = 'https://olinda.bcb.gov.br/olinda/servico/Expectativas/versao/v1/odata/'
    orderby = f'&%24orderby={ordenar_por}%20{"asc" if asc else "desc"}'
    topn = '' if top is None else f'&%24top={top}'

    expectativa = expectativa.lower()
    if expectativa in ('mensal', 'mensais'):
        expec = 'ExpectativaMercadoMensais'
        KPIS = (
            'IGP-DI',
            'IGP-M',
            'INPC',
            'IPA-DI',
            'IPA-M',
            'IPCA',
            'IPCA-15',
            'IPC-FIPE',
            'Produção industrial',
            'Meta para taxa over-selic',
            'Taxa de câmbio'
        )
    elif expectativa in ('trimestral', 'trimestrais'):
        expec = 'ExpectativasMercadoTrimestrais'
        KPIS = (
            'PIB Agropecuária',
            'PIB Industrial',
            'PIB Serviços',
            'PIB Total'
        )
    elif expectativa in ('anual', 'anuais'):
        expec = 'ExpectativasMercadoAnuais'
        KPIS = (
            'Balança Comercial',
            'Balanço de Pagamentos',
            'Fiscal',
            'IGP-DI',
            'IGP-M',
            'INPC',
            'IPA-DI',
            'IPA-M',
            'IPCA',
            'IPCA-15',
            'IPC-FIPE',
            'Preços administrados por contrato e monitorados',
            'Produção industrial',
            'PIB Agropecuária',
            'PIB Industrial',
            'PIB Serviços',
            'PIB Total',
            'Meta para taxa over-selic',
            'Taxa de câmbio'
        )
    elif expectativa in ('inflacao', 'inflacao12meses'):
        expec = 'ExpectativasMercadoInflacao12Meses'
        KPIS = (
            'IGP-DI',
            'IGP-M',
            'INPC',
            'IPA-DI',
            'IPA-M',
            'IPCA',
            'IPCA-15',
            'IPC-FIPE'
        )
    elif expectativa in ('top5mensal', 'top5mensais'):
        expec = 'ExpectativasMercadoTop5Mensais'
        KPIS = (
            'IGP-DI',
            'IGP-M',
            'IPCA',
            'Meta para taxa over-selic',
            'Taxa de câmbio'
        )
    elif expectativa in ('top5anual', 'top5anuais'):
        expec = 'ExpectativasMercadoTop5Anuais'
        KPIS = (
            'IGP-DI',
            'IGP-M',
            'IPCA',
            'Meta para taxa over-selic',
            'Taxa de câmbio'
        )
    elif expectativa == 'instituicoes':
        expec = 'ExpectativasMercadoInstituicoes'
        KPIS = (
            'Balança Comercial',
            'Balanço de Pagamentos',
            'Fiscal',
            'IGP-DI',
            'IGP-M',
            'INPC',
            'IPA-DI',
            'IPA-M',
            'IPCA',
            'IPCA-15',
            'IPC-FIPE',
            'Preços administrados por contrato e monitorados',
            'Produção industrial',
            'PIB Agropecuária',
            'PIB Industrial', 'PIB Serviços',
            'PIB Total',
            'Meta para taxa over-selic',
            'Taxa de câmbio'
        )
    else:
        raise ValueError('''Valor inválido para o argumento `expectativa`. Insira um dos seguintes valores:
            - 'mensal' ou 'mensais';
            - 'trimestral' ou 'trimestrais';
            - 'anual' ou 'anuais';
            - 'inflacao' ou 'inflacao12meses';
            - 'top5mensal' ou 'top5mensais',
            - 'top5anual' ou 'top5anuais',
            - 'instituicoes'.''')

    if indicador is None:
        kpi = ''
    elif indicador in KPIS:
        kpi = f"&%24filter=Indicador%20eq%20'{indicador}'"
    else:
        raise ValueError(f''''{indicador}' é um indicador inválido para expectativa '{expectativa.title()}'. Insira um dos seguintes valores:
        - {", ".join(KPIS)}.''')

    path = f'{expec}?%24format=json{orderby}{kpi}{topn}'
    data = get_data(URL, path=path)
    return pd.DataFrame(data['value'])

Expectativas de mercado para os principais indicadores macroeconômicos.

Parameters
  • expectativa (str): Tipo ou periodicidade da expectativa.
    • 'mensal' ou 'mensais';
    • 'trimestral' ou 'trimestrais';
    • 'anual' ou 'anuais';
    • 'inflacao' ou 'inflacao12meses';
    • 'top5mensal' ou 'top5mensais',
    • 'top5anual' ou 'top5anuais',
    • 'instituicoes'.
  • indicador (str, optional): Capturar apenas o indicador desejado. Deve ser um dos seguintes indicadores, desde que esteja de acordo com a expectativa escolhida:
    • 'Balança Comercial';
    • 'Balanço de Pagamentos';
    • 'Fiscal';
    • 'IGP-DI';
    • 'IGP-M';
    • 'INPC';
    • 'IPA-DI';
    • 'IPA-M';
    • 'IPC-FIPE';
    • 'IPC-FIPEPreços administrados por contrato e monitorados';
    • 'IPCA';
    • 'IPCA-15';
    • 'Meta para taxa over-selic';
    • 'PIB Agropecuária';
    • 'PIB Industrial';
    • 'PIB Serviços';
    • 'PIB Total';
    • 'PIB TotalMeta para taxa over-selic';
    • 'Preços administrados por contrato e monitorados';
    • 'Produção industrial';
    • 'Taxa de câmbio'. Caso o valor seja None, retorna todos os indicadores disponíveis.
  • top (int, optional): Número máximo de registros que será retornado.
  • ordenar_por (str, default='Data'): Por qual coluna da tabela os registros serão ordenados.
  • asc (bool, default=False):
    • Se True, ordena os registros pela coluna selecionada no argumento ordenar_por em ordem crescente (A-Z ou 0-9);
    • Se False, ordena em ordem descrescente (Z-A ou 9-0).
Returns
  • pandas.core.frame.DataFrame: Tabela contendo uma breve estatística descritiva da expectativa de mercado de cada indicador poe período de referência.
Raises
  • ValueError: Em caso de parâmetros inválidos.
Examples
>>> bacen.expectativa(expectativa='mensal', indicador='IGP-M')
      Indicador        Data DataReferencia  Media  Mediana  DesvioPadrao  ...
0         IGP-M  2021-06-25        07/2022   0.31     0.30          0.21  ...
1         IGP-M  2021-06-25        07/2021   0.64     0.61          0.42  ...
2         IGP-M  2021-06-25        06/2021   1.25     1.10          0.58  ...
3         IGP-M  2021-06-25        11/2022   0.47     0.47          0.16  ...
4         IGP-M  2021-06-25        11/2021   0.50     0.50          0.24  ...
..          ...         ...            ...    ...      ...           ...  ...
>>> bacen.expectativa(
...     expectativa = 'trimestral',
...     indicador = 'PIB Total',
...     top = 3,
...     ordenar_por = 'Media',
...     asc = True
... )
   Indicador        Data DataReferencia  Media  Mediana  DesvioPadrao  ...
0  PIB Total  2020-06-02         2/2020 -14.00    -14.0          3.92  ...
1  PIB Total  2020-06-09         2/2020 -14.00    -13.4          3.55  ...
2  PIB Total  2020-06-01         2/2020 -13.99    -14.0          3.91  ...