Pular para conteúdo

BC Data

auctions(start=None, end=None, auction_type=None)

Recupera dados de leilões para um determinado período e tipo de leilão da API do BC.

Consultas de Período: - Para consultar dados de um intervalo, forneça as datas de start e end. Exemplo: auctions(start='2024-10-20', end='2024-10-27') - Se apenas start for fornecido, a API do BC retornará dados de leilão a partir da data de start até a data mais recente disponível. Exemplo: auctions(start='2024-10-20') - Se apenas end for fornecido, a API do BC retornará dados de leilão desde a data mais antiga disponível até a data de end. Exemplo: auctions(end='2024-10-27')

Série Histórica Completa: - Para recuperar a série histórica completa de leilões (desde 12/11/2012 até o último dia útil), chame a função sem fornecer os parâmetros start e end. Exemplo: auctions()

Busca dados de leilões da API do BC para as datas de início e fim especificadas, filtrando os resultados diretamente na API pelo tipo de leilão, se especificado. O comportamento da função em relação aos parâmetros start e end segue o padrão da API do Banco Central: - Se start for fornecido e end não, a função retorna dados de start até o fim. - Se end for fornecido e start não, a API retorna dados do início até end. - Se ambos start e end forem omitidos, a API retorna a série histórica completa.

Os dados podem ser filtrados pelo tipo de leilão especificado ("Sell" ou "Buy"). Leilões de "Sell" são aqueles em que o Tesouro Nacional vende títulos ao mercado. Leilões de "Buy" são aqueles em que o Tesouro Nacional compra títulos do mercado.

Parameters:

Name Type Description Default
start (DateScalar, opcional)

A data de início para a consulta dos leilões. Se start for fornecido e end for None, a API retornará dados de leilão a partir de start até a data mais recente disponível. Se start e end forem None, a série histórica completa será retornada. Padrão é None.

 None
end (DateScalar, opcional)

A data de fim para a consulta de dados de leilão. Se end for fornecido e start for None, a API retornará dados de leilão desde a data mais antiga disponível até a data de end. Se start e end forem None, a série histórica completa será retornada. Padrão é None.

 None
auction_type (Literal['sell', 'buy'], opcional)

O tipo de leilão para filtrar diretamente na API. Padrão é None (retorna todos os tipos de leilão).

 None

Returns:

Type Description
DataFrame

pd.DataFrame: Um DataFrame contendo dados de leilões para o período e tipo especificados. Em caso de erro ao buscar os dados, um DataFrame vazio é retornado e uma mensagem de erro é registrada no log.

Examples:

>>> import pandas as pd
>>> from pyield import bc
>>> df = bc.auctions(start="03-06-2025", end="03-06-2025")
>>> df
        Date Settlement AuctionType  ...      CutPrice   AvgRate   CutRate
0 2025-06-03 2025-06-04       Venda  ...  16653.010815  0.000589  0.000589
1 2025-06-03 2025-06-04       Venda  ...  16572.063672   0.00109   0.00109
2 2025-06-03 2025-06-04       Venda  ...   4314.142451   0.07569   0.07569
3 2025-06-03 2025-06-04       Venda  ...    4140.47255   0.07312   0.07312
4 2025-06-03 2025-06-04       Venda  ...   3960.619508   0.07157   0.07157
...
Notes

FR = First Round (Primeira Rodada)

SR = Second Round (Segunda Rodada)

DataFrame Columns
  • Date: Data do leilão.
  • Settlement: Data de liquidação do leilão.
  • AuctionType: Tipo de leilão (ex: "Sell" ou "Buy").
  • Ordinance: Edital normativo associado ao leilão.
  • Buyer: Categoria do comprador (ex: "TodoMercado", "SomenteDealerApto").
  • BondType: Categoria do título (ex: "LTN", "LFT", "NTN-B", "NTN-F").
  • SelicCode: Código do título no sistema Selic.
  • Maturity: Data de vencimento do título.
  • DV01: Valor do DV01 total do leilão em R$.
  • DV01FR: DV01 da Primeira Rodada (FR) em R$.
  • DV01SR: DV01 da Segunda Rodada (SR) em R$.
  • DV01USD: DV01 total do leilão em dólares (USD).
  • DV01FRUSD: DV01 da Primeira Rodada (FR) em dólares (USD).
  • DV01SRUSD: DV01 da Segunda Rodada (SR) em dólares (USD).
  • AvgMaturity: Maturidade média do título (em anos).
  • Value: Valor total do leilão em R$ (FR + SR).
  • ValueFR: Valor da primeira rodada (FR) do leilão em R$.
  • ValueSR: Valor da segunda rodada (SR) em R$.
  • OfferedQuantity: Quantidade total ofertada no leilão (FR + SR).
  • OfferedQuantityFR: Quantidade ofertada na primeira rodada (FR).
  • OfferedQuantitySR: Quantidade ofertada na segunda rodada (SR).
  • AcceptedQuantity: Quantidade total aceita no leilão (FR + SR).
  • AcceptedQuantityFR: Quantidade aceita na primeira rodada (FR).
  • AcceptedQuantitySR: Quantidade aceita na segunda rodada (SR).
  • AvgPrice: Preço médio no leilão.
  • CutPrice: Preço de corte.
  • AvgRate: Taxa de juros média.
  • CutRate: Taxa de corte.
  • BDToMat: Dias úteis entre a data de liquidação da 1R e a data de vencimento do título.
  • Duration: Duration (Duração) calculada com base na data de liquidação da 1R e na data de vencimento do título.
Source code in pyield/bc/auction.py 
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
def auctions(
    start: DateScalar | None = None,
    end: DateScalar | None = None,
    auction_type: Literal["sell", "buy"] | None = None,
) -> pd.DataFrame:
    """
    Recupera dados de leilões para um determinado período e tipo de leilão da API do BC.

    **Consultas de Período:**
    - Para consultar dados de um intervalo, forneça as datas de `start` e `end`.
      Exemplo: `auctions(start='2024-10-20', end='2024-10-27')`
    - Se apenas `start` for fornecido, a API do BC retornará dados de leilão a partir
      da data de `start` **até a data mais recente disponível**.
      Exemplo: `auctions(start='2024-10-20')`
    - Se apenas `end` for fornecido, a API do BC retornará dados de leilão **desde a
      data mais antiga disponível até a data de `end`**.
      Exemplo: `auctions(end='2024-10-27')`

    **Série Histórica Completa:**
    - Para recuperar a série histórica completa de leilões (desde 12/11/2012 até o
      último dia útil), chame a função sem fornecer os parâmetros `start` e `end`.
      Exemplo: `auctions()`

    Busca dados de leilões da API do BC para as datas de início e fim especificadas,
    filtrando os resultados diretamente na API pelo tipo de leilão, se especificado.
    O comportamento da função em relação aos parâmetros `start` e `end` segue o padrão
    da API do Banco Central:
    - Se `start` for fornecido e `end` não, a função retorna dados de `start` até o fim.
    - Se `end` for fornecido e `start` não, a API retorna dados do início até `end`.
    - Se ambos `start` e `end` forem omitidos, a API retorna a série histórica completa.

    Os dados podem ser filtrados pelo tipo de leilão especificado ("Sell" ou "Buy").
    Leilões de "Sell" são aqueles em que o Tesouro Nacional vende títulos ao mercado.
    Leilões de "Buy" são aqueles em que o Tesouro Nacional compra títulos do mercado.

    Args:
        start (DateScalar, opcional): A data de início para a consulta dos leilões.
            Se `start` for fornecido e `end` for `None`, a API retornará dados de
            leilão a partir de `start` até a data mais recente disponível.
            Se `start` e `end` forem `None`, a série histórica completa será retornada.
            Padrão é `None`.
        end (DateScalar, opcional): A data de fim para a consulta de dados de leilão.
            Se `end` for fornecido e `start` for `None`, a API retornará dados de
            leilão desde a data mais antiga disponível até a data de `end`.
            Se `start` e `end` forem `None`, a série histórica completa será retornada.
            Padrão é `None`.
        auction_type (Literal["sell", "buy"], opcional): O tipo de leilão para filtrar
            diretamente na API. Padrão é `None` (retorna todos os tipos de leilão).

    Returns:
        pd.DataFrame: Um DataFrame contendo dados de leilões para o período e tipo
            especificados. Em caso de erro ao buscar os dados, um DataFrame vazio
            é retornado e uma mensagem de erro é registrada no log.

    Examples:
        >>> import pandas as pd
        >>> from pyield import bc
        >>> df = bc.auctions(start="03-06-2025", end="03-06-2025")
        >>> df
                Date Settlement AuctionType  ...      CutPrice   AvgRate   CutRate
        0 2025-06-03 2025-06-04       Venda  ...  16653.010815  0.000589  0.000589
        1 2025-06-03 2025-06-04       Venda  ...  16572.063672   0.00109   0.00109
        2 2025-06-03 2025-06-04       Venda  ...   4314.142451   0.07569   0.07569
        3 2025-06-03 2025-06-04       Venda  ...    4140.47255   0.07312   0.07312
        4 2025-06-03 2025-06-04       Venda  ...   3960.619508   0.07157   0.07157
        ...

    Notes:
        FR = First Round (Primeira Rodada)

        SR = Second Round (Segunda Rodada)

    DataFrame Columns:
        - Date: Data do leilão.
        - Settlement: Data de liquidação do leilão.
        - AuctionType: Tipo de leilão (ex: "Sell" ou "Buy").
        - Ordinance: Edital normativo associado ao leilão.
        - Buyer: Categoria do comprador (ex: "TodoMercado", "SomenteDealerApto").
        - BondType: Categoria do título (ex: "LTN", "LFT", "NTN-B", "NTN-F").
        - SelicCode: Código do título no sistema Selic.
        - Maturity: Data de vencimento do título.
        - DV01: Valor do DV01 total do leilão em R$.
        - DV01FR: DV01 da Primeira Rodada (FR) em R$.
        - DV01SR: DV01 da Segunda Rodada (SR) em R$.
        - DV01USD: DV01 total do leilão em dólares (USD).
        - DV01FRUSD: DV01 da Primeira Rodada (FR) em dólares (USD).
        - DV01SRUSD: DV01 da Segunda Rodada (SR) em dólares (USD).
        - AvgMaturity: Maturidade média do título (em anos).
        - Value: Valor total do leilão em R$ (FR + SR).
        - ValueFR: Valor da primeira rodada (FR) do leilão em R$.
        - ValueSR: Valor da segunda rodada (SR) em R$.
        - OfferedQuantity: Quantidade total ofertada no leilão (FR + SR).
        - OfferedQuantityFR: Quantidade ofertada na primeira rodada (FR).
        - OfferedQuantitySR: Quantidade ofertada na segunda rodada (SR).
        - AcceptedQuantity: Quantidade total aceita no leilão (FR + SR).
        - AcceptedQuantityFR: Quantidade aceita na primeira rodada (FR).
        - AcceptedQuantitySR: Quantidade aceita na segunda rodada (SR).
        - AvgPrice: Preço médio no leilão.
        - CutPrice: Preço de corte.
        - AvgRate: Taxa de juros média.
        - CutRate: Taxa de corte.
        - BDToMat: Dias úteis entre a data de liquidação da 1R e a data de
            vencimento do título.
        - Duration: Duration (Duração) calculada com base na data de
            liquidação da 1R e na data de vencimento do título.
    """
    url = BASE_API_URL
    if start:
        start = dc.convert_input_dates(start)
        start_str = start.strftime("%Y-%m-%d")
        url += f"@dataMovimentoInicio='{start_str}'"

    if end:
        end = dc.convert_input_dates(end)
        end_str = end.strftime("%Y-%m-%d")
        url += f"&@dataMovimentoFim='{end_str}'"

    # Mapeamento do auction_type para o valor esperado pela API
    auction_type_mapping = {"sell": "Venda", "buy": "Compra"}
    if auction_type:
        auction_type = str(auction_type).lower()
        auction_type_api_value = auction_type_mapping[auction_type]
        # Adiciona o parâmetro tipoOferta à URL se auction_type for fornecido
        url += f"&@tipoOferta='{auction_type_api_value}'"

    url += "&$format=text/csv"  # Adiciona o formato CSV ao final

    return _fetch_df_from_url(url)

di_over(date, annualized=True)

Fetches the DI Over rate value for a specific date.

This is a convenience function that returns only the value (not the DataFrame) for the specified date.

Parameters:

Name Type Description Default
date DateScalar

The reference date to fetch the DI Over rate for.

 required
annualized bool

If True, returns the annualized rate (252 trading days per year), otherwise returns the daily rate.

 True

Returns:

Type Description
float

The DI Over rate as a float.

Examples:

>>> from pyield import bc
>>> bc.di_over("31-05-2024")
0.104

>>> bc.di_over("28-01-2025", annualized=False)
0.00045513
Source code in pyield/bc/bcdata.py 
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
def di_over(date: DateScalar, annualized: bool = True) -> float:
    """
    Fetches the DI Over rate value for a specific date.

    This is a convenience function that returns only the value (not the DataFrame)
    for the specified date.

    Args:
        date: The reference date to fetch the DI Over rate for.
        annualized: If True, returns the annualized rate (252 trading
            days per year), otherwise returns the daily rate.

    Returns:
        The DI Over rate as a float.

    Examples:
        >>> from pyield import bc
        >>> bc.di_over("31-05-2024")
        0.104

        >>> bc.di_over("28-01-2025", annualized=False)
        0.00045513
    """
    df = di_over_series(date, date, annualized)
    return float(df.at[0, "Value"])

di_over_series(start=None, end=None, annualized=True)

Fetches the DI (Interbank Deposit) rate from the Brazilian Central Bank.

The DI rate represents the average interest rate of interbank loans.

API URL Example

https://api.bcb.gov.br/dados/serie/bcdata.sgs.11/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024 https://api.bcb.gov.br/dados/serie/bcdata.sgs.11/dados?formato=csv&dataInicial=12/04/2024&dataFinal=12/04/2024

Parameters:

Name Type Description Default
start DateScalar | None

The start date for the data to fetch. If None, returns data from the earliest available date.

 None
end DateScalar | None

The end date for the data to fetch. If None, returns data up to the latest available date.

 None
annualized bool

If True, returns the annualized rate (252 trading days per year), otherwise returns the daily rate.

 True

Returns:

Type Description
DataFrame

DataFrame containing Date and Value columns with the DI rate,
DataFrame

or empty DataFrame if data is not available.

Examples:

>>> from pyield import bc
>>> bc.di_over_series("29-01-2025")
        Date   Value
0  2025-01-29  0.1215
1  2025-01-30  0.1315
2  2025-01-31  0.1315
3  2025-02-03  0.1315
...
Source code in pyield/bc/bcdata.py 
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
def di_over_series(
    start: DateScalar | None = None,
    end: DateScalar | None = None,
    annualized: bool = True,
) -> pd.DataFrame:
    """
    Fetches the DI (Interbank Deposit) rate from the Brazilian Central Bank.

    The DI rate represents the average interest rate of interbank loans.

    API URL Example:
        https://api.bcb.gov.br/dados/serie/bcdata.sgs.11/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024
        https://api.bcb.gov.br/dados/serie/bcdata.sgs.11/dados?formato=csv&dataInicial=12/04/2024&dataFinal=12/04/2024

    Args:
        start: The start date for the data to fetch. If None, returns data from
              the earliest available date.
        end: The end date for the data to fetch. If None, returns data up to
             the latest available date.
        annualized: If True, returns the annualized rate (252 trading
            days per year), otherwise returns the daily rate.

    Returns:
        DataFrame containing Date and Value columns with the DI rate,
        or empty DataFrame if data is not available.

    Examples:
        >>> from pyield import bc
        >>> bc.di_over_series("29-01-2025")
                Date   Value
        0  2025-01-29  0.1215
        1  2025-01-30  0.1315
        2  2025-01-31  0.1315
        3  2025-02-03  0.1315
        ...

    """
    df = _fetch_data_from_url(BCSerie.DI_OVER, start, end)
    if annualized:
        df["Value"] = (df["Value"] + 1) ** 252 - 1
        df["Value"] = df["Value"].round(DECIMAL_PLACES_ANNUALIZED)
    else:
        df["Value"] = df["Value"].round(DECIMAL_PLACES_DAILY)
    return df

fpd_intraday_trades()

Fetches real-time secondary trading data for domestic Federal Public Debt (FPD) from the Central Bank of Brazil (BCB).

This function checks if the SELIC market is currently open based on Brazil/Sao_Paulo timezone business days and trading hours (defined by REALTIME_START_TIME and REALTIME_END_TIME). If the market is closed, or if no data is available from the source, or if an error occurs during fetching or processing, an empty DataFrame is returned. Otherwise, it retrieves, cleans, and processes the intraday trade data provided by BCB for Brazilian government bonds.

Returns:

Type Description
DataFrame

pd.DataFrame: A DataFrame containing the latest intraday trades for FPD securities. Returns an empty DataFrame if the market is closed, no data is found, or an error occurs. The DataFrame includes the following columns:

  • SettlementDate: The reference date for the spot market trading activity reported in this dataset (the current business day). Forward trades listed have future settlement dates not specified here.
  • BondType: Abbreviation/ticker for the bond type (e.g., LFT, LTN, NTN-B).
  • SelicCode: The unique SELIC code identifying the specific bond issue.
  • MaturityDate: The maturity date of the bond.

Spot Market Data: * MinPrice: Minimum traded price. * AvgPrice: Average traded price. * MaxPrice: Maximum traded price. * LastPrice: Last traded price. * MinRate: Minimum traded yield/rate (as a decimal, e.g., 0.11 for 11%). * AvgRate: Average traded yield/rate (as a decimal). * MaxRate: Maximum traded yield/rate (as a decimal). * LastRate: Last traded yield/rate (as a decimal). * Trades: Total number of trades settled. * Quantity: Total number of bonds traded (quantity). * Volume: Total financial volume traded (in BRL). * BrokeredTrades: Number of brokered trades settled. * BrokeredQuantity: Quantity of bonds traded via brokers.

Forward Market Data: * ForwardMinPrice: Minimum traded price. * ForwardAvgPrice: Average traded price. * ForwardMaxPrice: Maximum traded price. * ForwardLastPrice: Last traded price. * ForwardMinRate: Minimum traded yield/rate (decimal). * ForwardAvgRate: Average traded yield/rate (decimal). * ForwardMaxRate: Maximum traded yield/rate (decimal). * ForwardLastRate: Last traded yield/rate (decimal). * ForwardTrades: Total number of trades contracted. * ForwardQuantity: Total number of bonds traded (quantity). * ForwardVolume: Total financial volume traded (in BRL). * ForwardBrokeredTrades: Number of brokered trades contracted. * ForwardBrokeredQuantity: Quantity of bonds traded via brokers.
Source code in pyield/bc/trades_intraday.py 
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
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
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
def fpd_intraday_trades() -> pd.DataFrame:
    """Fetches real-time secondary trading data for domestic Federal Public Debt (FPD)
    from the Central Bank of Brazil (BCB).

    This function checks if the SELIC market is currently open based on Brazil/Sao_Paulo
    timezone business days and trading hours (defined by REALTIME_START_TIME and
    REALTIME_END_TIME). If the market is closed, or if no data is available from the
    source, or if an error occurs during fetching or processing, an empty DataFrame
    is returned. Otherwise, it retrieves, cleans, and processes the intraday trade
    data provided by BCB for Brazilian government bonds.

    Returns:
        pd.DataFrame: A DataFrame containing the latest intraday trades for FPD
            securities. Returns an empty DataFrame if the market is closed, no data
            is found, or an error occurs. The DataFrame includes the following columns:

            *   `SettlementDate`: The reference date for the spot market
                trading activity reported in this dataset (the current
                business day). Forward trades listed have future settlement dates
                not specified here.
            *   `BondType`: Abbreviation/ticker for the bond type (e.g., LFT,
                LTN, NTN-B).
            *   `SelicCode`: The unique SELIC code identifying the specific bond issue.
            *   `MaturityDate`: The maturity date of the bond.

            **Spot Market Data:**
            *   `MinPrice`: Minimum traded price.
            *   `AvgPrice`: Average traded price.
            *   `MaxPrice`: Maximum traded price.
            *   `LastPrice`: Last traded price.
            *   `MinRate`: Minimum traded yield/rate (as a decimal, e.g., 0.11 for 11%).
            *   `AvgRate`: Average traded yield/rate (as a decimal).
            *   `MaxRate`: Maximum traded yield/rate (as a decimal).
            *   `LastRate`: Last traded yield/rate (as a decimal).
            *   `Trades`: Total number of trades settled.
            *   `Quantity`: Total number of bonds traded (quantity).
            *   `Volume`: Total financial volume traded (in BRL).
            *   `BrokeredTrades`: Number of brokered trades settled.
            *   `BrokeredQuantity`: Quantity of bonds traded via brokers.

            **Forward Market Data:**
            *   `ForwardMinPrice`: Minimum traded price.
            *   `ForwardAvgPrice`: Average traded price.
            *   `ForwardMaxPrice`: Maximum traded price.
            *   `ForwardLastPrice`: Last traded price.
            *   `ForwardMinRate`: Minimum traded yield/rate (decimal).
            *   `ForwardAvgRate`: Average traded yield/rate (decimal).
            *   `ForwardMaxRate`: Maximum traded yield/rate (decimal).
            *   `ForwardLastRate`: Last traded yield/rate (decimal).
            *   `ForwardTrades`: Total number of trades contracted.
            *   `ForwardQuantity`: Total number of bonds traded (quantity).
            *   `ForwardVolume`: Total financial volume traded (in BRL).
            *   `ForwardBrokeredTrades`: Number of brokered trades contracted.
            *   `ForwardBrokeredQuantity`: Quantity of bonds traded via brokers.
    """
    if not is_selic_open():
        logger.info("Market is closed. Returning empty DataFrame.")
        return pd.DataFrame()

    try:
        raw_text = _fetch_csv_from_url()
        # raw_text = test_file.read_text(encoding="iso-8859-15")
        cleaned_text = _clean_csv(raw_text)
        if not cleaned_text:
            logger.warning("No data found in the FPD intraday trades.")
            return pd.DataFrame()
        df = _convert_csv_to_df(cleaned_text)
        df = _process_df(df)
        df = _reorder_columns(df)
        volume = df["Volume"].sum() / 10**9
        logger.info(f"Fetched {volume:,.1f} billion BRL in FPD intraday trades.")
        return df
    except Exception:
        logger.exception("Error fetching data from BCB. Returning empty DataFrame.")
        return pd.DataFrame()

fpd_monthly_trades(target_date, extragroup=False)

Fetches monthly secondary trading data for the domestic 'Federal Public Debt' (FPD) registered in the Brazilian Central Bank (BCB) Selic system.

Downloads the monthly bond trading data from the Brazilian Central Bank (BCB) website for the month corresponding to the provided date. The data is downloaded as a ZIP file, extracted, and loaded into a Pandas DataFrame. The data contains all trades executed during the month, separated by each 'SettlementDate'.

Parameters:

Name Type Description Default
target_date DateScalar

The date for which the monthly trading data will be fetched. This date can be a string, datetime, or pandas Timestamp object. It will be converted to a pandas Timestamp object. Only the year and month of this date will be used to download the corresponding monthly file. extragroup (bool): If True, fetches only the trades that are considered 'extragroup' (between different economic groups)". If False, fetches all trades. Default is False. Extragroup trades are those where the transferring counterparty's conglomerate is different from the receiving counterparty's conglomerate, or when at least one of the counterparties does not belong to a conglomerate. In the case of funds, the conglomerate considered is that of the administrator.

 required

Returns:

Type Description
DataFrame

pd.DataFrame: A DataFrame containing the bond trading data for the specified month.
DataFrame columns
  • SettlementDate: Date when the trade settled
  • BondType: Security type abbreviation
  • SelicCode: Unique code in the SELIC system
  • ISIN: International Securities Identification Number
  • IssueDate: Date when the security was issued
  • MaturityDate: Security's maturity date
  • Trades: Number of trades executed
  • Quantity: Quantity traded
  • Volume: Total value traded
  • AvgPrice: Average price
  • AvgRate: Average rate And additional trading metrics like min/max prices and rates.

Examples:

>>> from pyield import bc
>>> df = bc.fpd_monthly_trades("07-01-2025")  # Returns all trades for Jan/2025
Source code in pyield/bc/trades_monthly.py 
 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
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
def fpd_monthly_trades(
    target_date: DateScalar, extragroup: bool = False
) -> pd.DataFrame:
    """Fetches monthly secondary trading data for the domestic 'Federal Public Debt'
    (FPD) registered in the Brazilian Central Bank (BCB) Selic system.

    Downloads the monthly bond trading data from the Brazilian Central Bank (BCB)
    website for the month corresponding to the provided date. The data is downloaded
    as a ZIP file, extracted, and loaded into a Pandas DataFrame. The data contains
    all trades executed during the month, separated by each 'SettlementDate'.

    Args:
        target_date (DateScalar): The date for which the monthly trading data will be
            fetched. This date can be a string, datetime, or pandas Timestamp object.
            It will be converted to a pandas Timestamp object. Only the year and month
            of this date will be used to download the corresponding monthly file.
            extragroup (bool): If True, fetches only the trades that are considered
            'extragroup' (between different economic groups)".
            If False, fetches all trades. Default is False.
            Extragroup trades are those where the transferring counterparty's
            conglomerate is different from the receiving counterparty's conglomerate, or
            when at least one of the counterparties does not belong to a conglomerate.
            In the case of funds, the conglomerate considered is that of the
            administrator.

    Returns:
        pd.DataFrame: A DataFrame containing the bond trading data for the specified
            month.

    DataFrame columns:
        - SettlementDate: Date when the trade settled
        - BondType: Security type abbreviation
        - SelicCode: Unique code in the SELIC system
        - ISIN: International Securities Identification Number
        - IssueDate: Date when the security was issued
        - MaturityDate: Security's maturity date
        - Trades: Number of trades executed
        - Quantity: Quantity traded
        - Volume: Total value traded
        - AvgPrice: Average price
        - AvgRate: Average rate
        And additional trading metrics like min/max prices and rates.

    Examples:
        >>> from pyield import bc
        >>> df = bc.fpd_monthly_trades("07-01-2025")  # Returns all trades for Jan/2025
    """
    filename = _build_filename(target_date, extragroup)
    logger.info(f"Fetching FPD trades for {target_date} from BCB")
    url = f"{BASE_URL}/{filename}"
    df = _fetch_data_from_url(url)
    df = df.rename(columns=COLUMN_MAPPING)
    # Volume are empty in the original BCB file, so we calculate it
    df["Volume"] = (df["Quantity"] * df["AvgPrice"]).round(2)
    sort_cols = ["SettlementDate", "BondType", "MaturityDate"]
    df = df.sort_values(by=sort_cols).reset_index(drop=True)
    return df

ptax_series(start=None, end=None)

Cotações de Dólar PTAX (taxa de câmbio) - Fonte: Banco Central do Brasil (BCB) - Frequência: Diária - Unidade: R$

Documentação da API do BCB:

https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/documentacao

Exemplo de chamada à API:

https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)?@dataInicial='08-01-2025'&@dataFinalCotacao='08-05-2025'&$format=text/csv

Consultas de Período:

  • Para consultar dados de um intervalo, forneça as datas de start e end. Exemplo:

    `ptax_series(start='2024-10-20', end='2024-10-27')`

  • Se apenas start for fornecido, a API do BC retornará dados a partir da data de start até a data mais recente disponível. Exemplo:

    `ptax_series(start='2024-10-20')`

  • Se apenas end for fornecido, a API do BC retornará dados desde a data mais antiga disponível até a data de end. Exemplo:

    ptax_series(end='2024-10-27')

Série Histórica Completa:

  • Para recuperar a série histórica completa de leilões (desde 28.11.1984 até o último dia útil), chame a função sem fornecer os parâmetros start e end. Exemplo:
    `ptax_series()`

Busca dados de cotações de dólar PTAX (taxa de câmbio) para o período:

  • Se start for fornecido e end não, a função retorna dados de start até o fim.
  • Se end for fornecido e start não, a API retorna dados do início até end.
  • Se ambos start e end forem omitidos, a API retorna a série histórica completa.

Parameters:

Name Type Description Default
start (DateScalar, opcional)

A data de início para a consulta dos leilões. Se start for fornecido e end for None, a API retornará dados de leilão a partir de start até a data mais recente disponível. Se start e end forem None, a série histórica completa será retornada. Padrão é None.

 None
end (DateScalar, opcional)

A data de fim para a consulta de dados de leilão. Se end for fornecido e start for None, a API retornará dados de leilão desde a data mais antiga disponível até a data de end. Se start e end forem None, a série histórica completa será retornada. Padrão é None.

 None

Returns:

Type Description
DataFrame

pd.DataFrame: Um DataFrame contendo os dados de cotações de dólar PTAX.
DataFrame

Se não houver dados disponíveis para o período especificado, um DataFrame vazio
DataFrame

será retornado.

Examples:

>>> from pyield import bc
>>> df = yd.bc.ptax_series(start="01-01-2025", end="05-01-2025")
>>> selected_columns = ["Date", "BuyRate", "SellRate", "MidRate"]
>>> df[selected_columns]
        Date  BuyRate  SellRate  MidRate
0 2025-01-02    6.208    6.2086   6.2083
1 2025-01-03   6.1557    6.1563    6.156
Notes

Disponível desde 28.11.1984, refere-se às taxas administradas até março de 1990 e às taxas livres a partir de então (Resolução 1690, de 18.3.1990). As taxas administradas são aquelas fixadas pelo Banco Central; a partir de março de 1992, essa taxa recebeu a denominação de taxa PTAX (fechamento). Até 30 de junho de 2011, as taxas livres correspondiam à média das taxas efetivas de operações no mercado interbancário, ponderada pelo volume de transações do dia. A partir de 1 de julho de 2011 (Circular 3506, de 23.9.2010), a Ptax passou a corresponder à média aritmética das taxas obtidas em quatro consultas diárias aos dealers de câmbio e refletem a taxa negociada no momento de abertura da janela de consulta; o boletim de fechamento PTAX corresponde à média aritmética das taxas dos boletins do dia.

  • Primeira data disponível: 28.11.1984
  • Última data disponível: data atual

O DataFrame possui as seguintes colunas:

  • Date: Data da cotação.
  • Time: Hora da cotação.
  • DateTime: Data e hora da cotação.
  • BuyRate: Taxa de compra.
  • SellRate: Taxa de venda.
  • MidRate: Taxa média entre a taxa de compra e venda.
Source code in pyield/bc/ptax.py 
 81
 82
 83
 84
 85
 86
 87
 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
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
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
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
def ptax_series(
    start: DateScalar | None = None,
    end: DateScalar | None = None,
) -> pd.DataFrame:
    """Cotações de Dólar PTAX (taxa de câmbio)
    - Fonte: Banco Central do Brasil (BCB)
    - Frequência: Diária
    - Unidade: R$

    Documentação da API do BCB:

        https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/documentacao

    Exemplo de chamada à API:

        https://olinda.bcb.gov.br/olinda/servico/PTAX/versao/v1/odata/CotacaoDolarPeriodo(dataInicial=@dataInicial,dataFinalCotacao=@dataFinalCotacao)?@dataInicial='08-01-2025'&@dataFinalCotacao='08-05-2025'&$format=text/csv

    Consultas de Período:

    - Para consultar dados de um intervalo, forneça as datas de `start` e `end`.
    Exemplo:

            `ptax_series(start='2024-10-20', end='2024-10-27')`

    - Se apenas `start` for fornecido, a API do BC retornará dados a partir
    da data de `start` até a data mais recente disponível. Exemplo:

            `ptax_series(start='2024-10-20')`

    - Se apenas `end` for fornecido, a API do BC retornará dados desde a data mais
    antiga disponível até a data de `end`. Exemplo:

        `ptax_series(end='2024-10-27')`

    Série Histórica Completa:

    - Para recuperar a série histórica completa de leilões (desde 28.11.1984
    até o último dia útil), chame a função sem fornecer os parâmetros `start` e `end`.
    Exemplo:

            `ptax_series()`

    Busca dados de cotações de dólar PTAX (taxa de câmbio) para o período:

    - Se `start` for fornecido e `end` não, a função retorna dados de `start` até o fim.
    - Se `end` for fornecido e `start` não, a API retorna dados do início até `end`.
    - Se ambos `start` e `end` forem omitidos, a API retorna a série histórica completa.

    Args:
        start (DateScalar, opcional): A data de início para a consulta dos leilões.
            Se `start` for fornecido e `end` for `None`, a API retornará dados de
            leilão a partir de `start` até a data mais recente disponível.
            Se `start` e `end` forem `None`, a série histórica completa será retornada.
            Padrão é `None`.
        end (DateScalar, opcional): A data de fim para a consulta de dados de leilão.
            Se `end` for fornecido e `start` for `None`, a API retornará dados de
            leilão desde a data mais antiga disponível até a data de `end`.
            Se `start` e `end` forem `None`, a série histórica completa será retornada.
            Padrão é `None`.

    Returns:
        pd.DataFrame: Um DataFrame contendo os dados de cotações de dólar PTAX.
        Se não houver dados disponíveis para o período especificado, um DataFrame vazio
        será retornado.

    Examples:
        >>> from pyield import bc
        >>> df = yd.bc.ptax_series(start="01-01-2025", end="05-01-2025")
        >>> selected_columns = ["Date", "BuyRate", "SellRate", "MidRate"]
        >>> df[selected_columns]
                Date  BuyRate  SellRate  MidRate
        0 2025-01-02    6.208    6.2086   6.2083
        1 2025-01-03   6.1557    6.1563    6.156

    Notes:
        Disponível desde 28.11.1984, refere-se às taxas administradas até março de 1990
        e às taxas livres a partir de então (Resolução 1690, de 18.3.1990). As taxas
        administradas são aquelas fixadas pelo Banco Central; a partir de março de 1992,
        essa taxa recebeu a denominação de taxa PTAX (fechamento). Até 30 de junho de
        2011, as taxas livres correspondiam à média das taxas efetivas de operações no
        mercado interbancário, ponderada pelo volume de transações do dia. A partir de
        1 de julho de 2011 (Circular 3506, de 23.9.2010), a Ptax passou a corresponder
        à média aritmética das taxas obtidas em quatro consultas diárias aos dealers de
        câmbio e refletem a taxa negociada no momento de abertura da janela de consulta;
        o boletim de fechamento PTAX corresponde à média aritmética das taxas dos
        boletins do dia.

        - Primeira data disponível: 28.11.1984
        - Última data disponível: data atual

        O DataFrame possui as seguintes colunas:

        - Date: Data da cotação.
        - Time: Hora da cotação.
        - DateTime: Data e hora da cotação.
        - BuyRate: Taxa de compra.
        - SellRate: Taxa de venda.
        - MidRate: Taxa média entre a taxa de compra e venda.


    """
    if start:
        start = dc.convert_input_dates(start)
    else:
        start = pd.Timestamp("1984-11-28")

    if end:
        end = dc.convert_input_dates(end)
    else:
        end = dt.datetime.now(TIMEZONE_BZ).date()

    start_str = start.strftime("%m-%d-%Y")
    end_str = end.strftime("%m-%d-%Y")

    # Monta a URL da API com as datas de início e fim
    url = PTAX_API_URL
    url += f"@dataInicial='{start_str}'"
    url += f"&@dataFinalCotacao='{end_str}'"
    url += "&$format=text/csv"  # Adiciona o formato CSV ao final

    return _fetch_df_from_url(url)

repos(start=None, end=None)

Recupera dados de leilões para um determinado período e tipo de leilão da API do BC.

Consultas de Período: - Para consultar dados de um intervalo, forneça as datas de start e end. Exemplo: auctions(start='2024-10-20', end='2024-10-27') - Se apenas start for fornecido, a API do BC retornará dados de leilão a partir da data de start até a data mais recente disponível. Exemplo: auctions(start='2024-10-20') - Se apenas end for fornecido, a API do BC retornará dados de leilão desde a data mais antiga disponível até a data de end. Exemplo: auctions(end='2024-10-27')

Série Histórica Completa: - Para recuperar a série histórica completa de leilões (desde 12/11/2012 até o último dia útil), chame a função sem fornecer os parâmetros start e end. Exemplo: auctions()

Busca dados de leilões da API do BC para as datas de início e fim especificadas, filtrando os resultados diretamente na API pelo tipo de leilão, se especificado. O comportamento da função em relação aos parâmetros start e end segue o padrão da API do Banco Central: - Se start for fornecido e end não, a função retorna dados de start até o fim. - Se end for fornecido e start não, a API retorna dados do início até end. - Se ambos start e end forem omitidos, a API retorna a série histórica completa.

Os dados podem ser filtrados pelo tipo de leilão especificado ("Sell" ou "Buy"). Leilões de "Sell" são aqueles em que o Tesouro Nacional vende títulos ao mercado. Leilões de "Buy" são aqueles em que o Tesouro Nacional compra títulos do mercado.

Parameters:

Name Type Description Default
start (DateScalar, opcional)

A data de início para a consulta dos leilões. Se start for fornecido e end for None, a API retornará dados de leilão a partir de start até a data mais recente disponível. Se start e end forem None, a série histórica completa será retornada. Padrão é None.

 None
end (DateScalar, opcional)

A data de fim para a consulta de dados de leilão. Se end for fornecido e start for None, a API retornará dados de leilão desde a data mais antiga disponível até a data de end. Se start e end forem None, a série histórica completa será retornada. Padrão é None.

 None

Returns:

Type Description
DataFrame

pd.DataFrame: Um DataFrame contendo dados de leilões para o período e tipo especificados. Em caso de erro ao buscar os dados, um DataFrame vazio é retornado e uma mensagem de erro é registrada no log.
Notes

O DataFrame possui as seguintes colunas: - Date: Data do leilão. - Settlement: Data de liquidação do leilão. - Maturity: Data de retorno do leilão. - CDToMat: Prazo em dias corridos até o vencimento. - BDtoMat: Prazo em dias úteis até o vencimento. - StartTime: Hora de início do leilão. - AllowedParticipants: Participantes permitidos no leilão. - CommunicationNumber: Número do comunicado. - OfferType: Tipo de oferta do leilão. - AcceptedVolume: Volume aceito no leilão (em R$). - CutRate: Taxa de corte do leilão. - CutPct: Percentual de corte do leilão.

Source code in pyield/bc/repo.py 
116
117
118
119
120
121
122
123
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
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
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
def repos(
    start: DateScalar | None = None,
    end: DateScalar | None = None,
) -> pd.DataFrame:
    """
    Recupera dados de leilões para um determinado período e tipo de leilão da API do BC.

    **Consultas de Período:**
    - Para consultar dados de um intervalo, forneça as datas de `start` e `end`.
      Exemplo: `auctions(start='2024-10-20', end='2024-10-27')`
    - Se apenas `start` for fornecido, a API do BC retornará dados de leilão a partir
      da data de `start` **até a data mais recente disponível**.
      Exemplo: `auctions(start='2024-10-20')`
    - Se apenas `end` for fornecido, a API do BC retornará dados de leilão **desde a
      data mais antiga disponível até a data de `end`**.
      Exemplo: `auctions(end='2024-10-27')`

    **Série Histórica Completa:**
    - Para recuperar a série histórica completa de leilões (desde 12/11/2012 até o
      último dia útil), chame a função sem fornecer os parâmetros `start` e `end`.
      Exemplo: `auctions()`

    Busca dados de leilões da API do BC para as datas de início e fim especificadas,
    filtrando os resultados diretamente na API pelo tipo de leilão, se especificado.
    O comportamento da função em relação aos parâmetros `start` e `end` segue o padrão
    da API do Banco Central:
    - Se `start` for fornecido e `end` não, a função retorna dados de `start` até o fim.
    - Se `end` for fornecido e `start` não, a API retorna dados do início até `end`.
    - Se ambos `start` e `end` forem omitidos, a API retorna a série histórica completa.

    Os dados podem ser filtrados pelo tipo de leilão especificado ("Sell" ou "Buy").
    Leilões de "Sell" são aqueles em que o Tesouro Nacional vende títulos ao mercado.
    Leilões de "Buy" são aqueles em que o Tesouro Nacional compra títulos do mercado.

    Args:
        start (DateScalar, opcional): A data de início para a consulta dos leilões.
            Se `start` for fornecido e `end` for `None`, a API retornará dados de
            leilão a partir de `start` até a data mais recente disponível.
            Se `start` e `end` forem `None`, a série histórica completa será retornada.
            Padrão é `None`.
        end (DateScalar, opcional): A data de fim para a consulta de dados de leilão.
            Se `end` for fornecido e `start` for `None`, a API retornará dados de
            leilão desde a data mais antiga disponível até a data de `end`.
            Se `start` e `end` forem `None`, a série histórica completa será retornada.
            Padrão é `None`.

    Returns:
        pd.DataFrame: Um DataFrame contendo dados de leilões para o período e tipo
            especificados. Em caso de erro ao buscar os dados, um DataFrame vazio
            é retornado e uma mensagem de erro é registrada no log.

    Notes:
        O DataFrame possui as seguintes colunas:
            - Date: Data do leilão.
            - Settlement: Data de liquidação do leilão.
            - Maturity: Data de retorno do leilão.
            - CDToMat: Prazo em dias corridos até o vencimento.
            - BDtoMat: Prazo em dias úteis até o vencimento.
            - StartTime: Hora de início do leilão.
            - AllowedParticipants: Participantes permitidos no leilão.
            - CommunicationNumber: Número do comunicado.
            - OfferType: Tipo de oferta do leilão.
            - AcceptedVolume: Volume aceito no leilão (em R$).
            - CutRate: Taxa de corte do leilão.
            - CutPct: Percentual de corte do leilão.

    """
    url = BASE_API_URL
    if start:
        start = dc.convert_input_dates(start)
        start_str = start.strftime("%Y-%m-%d")
        url += f"@dataLancamentoInicio='{start_str}'"

    if end:
        end = dc.convert_input_dates(end)
        end_str = end.strftime("%Y-%m-%d")
        url += f"&@dataLancamentoFim='{end_str}'"

    url += "&$format=text/csv"  # Adiciona o formato CSV ao final

    return _fetch_df_from_url(url)

selic_over(date)

Fetches the SELIC Over rate value for a specific date.

This is a convenience function that returns only the value (not the DataFrame) for the specified date.

Parameters:

Name Type Description Default
date DateScalar

The reference date to fetch the SELIC Over rate for.

 required

Returns:

Type Description
float

The SELIC Over rate as a float.

Examples:

>>> from pyield import bc
>>> bc.selic_over("31-05-2024")
0.104
Source code in pyield/bc/bcdata.py 
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
def selic_over(date: DateScalar) -> float:
    """
    Fetches the SELIC Over rate value for a specific date.

    This is a convenience function that returns only the value (not the DataFrame)
    for the specified date.

    Args:
        date: The reference date to fetch the SELIC Over rate for.

    Returns:
        The SELIC Over rate as a float.

    Examples:
        >>> from pyield import bc
        >>> bc.selic_over("31-05-2024")
        0.104
    """
    df = selic_over_series(date, date)
    return float(df.at[0, "Value"])

selic_over_series(start=None, end=None)

Fetches the SELIC Over rate from the Brazilian Central Bank.

The SELIC Over rate is the daily average interest rate effectively practiced between banks in the interbank market, using public securities as collateral.

API URL Example

https://api.bcb.gov.br/dados/serie/bcdata.sgs.1178/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024

Parameters:

Name Type Description Default
start DateScalar | None

The start date for the data to fetch. If None, returns data from the earliest available date.

 None
end DateScalar | None

The end date for the data to fetch. If None, returns data up to the latest available date.

 None

Returns:

Type Description
DataFrame

DataFrame containing Date and Value columns with the SELIC Over rate,
DataFrame

or empty DataFrame if data is not available.

Examples:

>>> from pyield import bc
>>> # No data on 26-01-2025 (sunday). Rate changed due to Copom meeting.
>>> bc.selic_over_series("26-01-2025")  # Returns all data since 26-01-2025
        Date   Value
0 2025-01-27  0.1215
1 2025-01-28  0.1215
2 2025-01-29  0.1215
3 2025-01-30  0.1315
4 2025-01-31  0.1315
...
Source code in pyield/bc/bcdata.py 
135
136
137
138
139
140
141
142
143
144
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
def selic_over_series(
    start: DateScalar | None = None, end: DateScalar | None = None
) -> pd.DataFrame:
    """
    Fetches the SELIC Over rate from the Brazilian Central Bank.

    The SELIC Over rate is the daily average interest rate effectively practiced
    between banks in the interbank market, using public securities as collateral.

    API URL Example:
        https://api.bcb.gov.br/dados/serie/bcdata.sgs.1178/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024

    Args:
        start: The start date for the data to fetch. If None, returns data from
              the earliest available date.
        end: The end date for the data to fetch. If None, returns data up to
             the latest available date.

    Returns:
        DataFrame containing Date and Value columns with the SELIC Over rate,
        or empty DataFrame if data is not available.

    Examples:
        >>> from pyield import bc
        >>> # No data on 26-01-2025 (sunday). Rate changed due to Copom meeting.
        >>> bc.selic_over_series("26-01-2025")  # Returns all data since 26-01-2025
                Date   Value
        0 2025-01-27  0.1215
        1 2025-01-28  0.1215
        2 2025-01-29  0.1215
        3 2025-01-30  0.1315
        4 2025-01-31  0.1315
        ...

    """
    df = _fetch_data_from_url(BCSerie.SELIC_OVER, start, end)
    df["Value"] = df["Value"].round(DECIMAL_PLACES_ANNUALIZED)
    return df

selic_target(date)

Fetches the SELIC Target rate value for a specific date.

This is a convenience function that returns only the value (not the DataFrame) for the specified date.

Parameters:

Name Type Description Default
date DateScalar

The reference date to fetch the SELIC Target rate for.

 required

Returns:

Type Description
float

The SELIC Target rate as a float.

Examples:

>>> from pyield import bc
>>> bc.selic_target("31-05-2024")
0.105
Source code in pyield/bc/bcdata.py 
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
def selic_target(date: DateScalar) -> float:
    """
    Fetches the SELIC Target rate value for a specific date.

    This is a convenience function that returns only the value (not the DataFrame)
    for the specified date.

    Args:
        date: The reference date to fetch the SELIC Target rate for.

    Returns:
        The SELIC Target rate as a float.

    Examples:
        >>> from pyield import bc
        >>> bc.selic_target("31-05-2024")
        0.105
    """
    df = selic_target_series(date, date)
    return float(df.at[0, "Value"])

selic_target_series(start=None, end=None)

Fetches the SELIC Target rate from the Brazilian Central Bank.

The SELIC Target rate is the official interest rate set by the Central Bank of Brazil's Monetary Policy Committee (COPOM).

API URL Example

https://api.bcb.gov.br/dados/serie/bcdata.sgs.432/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024

Parameters:

Name Type Description Default
start DateScalar | None

The start date for the data to fetch. If None, returns data from the earliest available date.

 None
end DateScalar | None

The end date for the data to fetch. If None, returns data up to the latest available date.

 None

Returns:

Type Description
DataFrame

DataFrame containing Date and Value columns with the SELIC Target rate,
DataFrame

or empty DataFrame if data is not available

Examples:

>>> from pyield import bc
>>> bc.selic_target_series("31-05-2024", "31-05-2024")
        Date  Value
0 2024-05-31  0.105
Source code in pyield/bc/bcdata.py 
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
def selic_target_series(
    start: DateScalar | None = None, end: DateScalar | None = None
) -> pd.DataFrame:
    """
    Fetches the SELIC Target rate from the Brazilian Central Bank.

    The SELIC Target rate is the official interest rate set by the
    Central Bank of Brazil's Monetary Policy Committee (COPOM).

    API URL Example:
        https://api.bcb.gov.br/dados/serie/bcdata.sgs.432/dados?formato=json&dataInicial=12/04/2024&dataFinal=12/04/2024

    Args:
        start: The start date for the data to fetch. If None, returns data from
              the earliest available date.
        end: The end date for the data to fetch. If None, returns data up to
             the latest available date.

    Returns:
        DataFrame containing Date and Value columns with the SELIC Target rate,
        or empty DataFrame if data is not available

    Examples:
        >>> from pyield import bc
        >>> bc.selic_target_series("31-05-2024", "31-05-2024")
                Date  Value
        0 2024-05-31  0.105
    """
    df = _fetch_data_from_url(BCSerie.SELIC_TARGET, start, end)
    df["Value"] = df["Value"].round(DECIMAL_PLACES_ANNUALIZED)
    return df

vna_lft(date)

Retrieves the VNA (Valor Nominal Atualizado) from the BCB for a given date.

This function fetches daily data from the BCB website, extracts the VNA value from a specific table within the downloaded content, and returns this value.

Parameters:

Name Type Description Default
date DateScalar

The date for which to retrieve the VNA value. This argument accepts various date formats, including string and datetime objects, which are then standardized using the convert_input_dates function.

 required

Returns:

Name Type Description
float float

The VNA (Valor Nominal Atualizado) value for the specified date.

Examples:

>>> from pyield import bc
>>> bc.vna_lft("31-05-2024")
14903.01148

Raises:

Type Description
ValueError

If the extracted VNA values from the BCB website are inconsistent (i.e., not all extracted values are identical), suggesting potential data discrepancies on the source website. The error message includes a link to the BCB website for manual verification.
HTTPError

If the HTTP request to the BCB website fails. This could be due to network issues, website unavailability, or the requested data not being found for the given date.
Source code in pyield/bc/vna.py 
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
def vna_lft(date: DateScalar) -> float:
    """Retrieves the VNA (Valor Nominal Atualizado) from the BCB for a given date.

    This function fetches daily data from the BCB website, extracts the
    VNA value from a specific table within the downloaded content, and
    returns this value.

    Args:
        date (DateScalar): The date for which to retrieve the VNA value.
            This argument accepts various date formats, including string and
            datetime objects, which are then standardized using the
            `convert_input_dates` function.

    Returns:
        float: The VNA (Valor Nominal Atualizado) value for the specified date.

    Examples:
        >>> from pyield import bc
        >>> bc.vna_lft("31-05-2024")
        14903.01148

    Raises:
        ValueError: If the extracted VNA values from the BCB website are
            inconsistent (i.e., not all extracted values are identical),
            suggesting potential data discrepancies on the source website.
            The error message includes a link to the BCB website for manual
            verification.
        requests.exceptions.HTTPError: If the HTTP request to the BCB website
            fails. This could be due to network issues, website unavailability,
            or the requested data not being found for the given date.
    """
    text = _get_text(date)
    table_text = _extract_vna_table_text(text)
    table_lines = _parse_vna_table_lines(table_text)
    vnas = _extract_vna_values_from_lines(table_lines)
    vna_value = _validate_vna_values(vnas)
    return vna_value