python-bcb

https://github.com/wilsonfreitas/python-bcb
Admin
python-bcb é uma interface em Python estruturada para obter informações da API de dados abertos do...
Tokens:41,968
Snippets:371
Trust Score:9.5
License:MIT
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install uv and Project Dependencies

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/CLAUDE.md

Install the 'uv' package manager and then synchronize project dependencies. Use the 'test' group for testing-specific dependencies.

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh  # install uv
uv sync                           # install all dependency groups
uv sync --group test              # install with test dependencies only
```

--------------------------------

### Describing MercadoImobiliario Endpoints

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata examples.ipynb

This example shows how to use the `describe` method to get information about available entity sets and their properties within the MercadoImobiliario service.

```APIDOC
## Describe MercadoImobiliario Service

### Description
Provides metadata about the MercadoImobiliario OData service, listing available entity sets and their respective properties and types.

### Method
GET (Implicit via client library)

### Endpoint
N/A (Service introspection)

### Parameters
#### Query Parameters
- **service_name** (string) - Optional - The name of the specific service to describe. If omitted, lists all available services.

### Request Example
```python
from bcb import MercadoImobiliario

mi = MercadoImobiliario()
mi.describe()
mi.describe('mercadoimobiliario')
```

### Response
#### Success Response
Returns a description of the entity sets and their properties. For a specific service, it details the structure of that service's entity sets.

#### Response Example
```
EntitySets:
  mercadoimobiliario

EntitySet (Endpoint): mercadoimobiliario
EntityType: br.gov.bcb.olinda.servico.MercadoImobiliario.TipoCreditoImobiliario
Properties: Data<str>, Info<str>, Valor<float>
```
```

--------------------------------

### Install Python BCB

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/currency PTAX.ipynb

Install the Python BCB library using pip. This is the first step before using any of its functionalities.

```bash
pip install python-bcb
```

--------------------------------

### OData Query Building Example

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/CLAUDE.md

Demonstrates how to query OData services by retrieving an endpoint and executing a query with filtering and limit.

```python
api.get_endpoint("EntityName")
.get(Property >= value, limit=100)
or
.query()
```

--------------------------------

### Initialize PTAX

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/currency PTAX.ipynb

Instantiate the PTAX class to start interacting with the API.

```APIDOC
## Initialize PTAX

### Description
Instantiate the PTAX class to begin fetching currency data.

### Code
```python
from bcb import PTAX

ptax = PTAX()
```
```

--------------------------------

### SQL Query Example

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/docs/odata.md

Illustrates a SQL-like structure for querying OData, specifying columns, filters, ordering, and limits.

```sql
select Data, Media
from PIX
where Data >= "2023-01-01"
order by Media desc
limit 10
```

--------------------------------

### Querying ParametrosConsulta

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata examples.ipynb

This example shows how to retrieve parameters for interest rate queries, limiting the results to 10.

```APIDOC
## GET /ParametrosConsulta

### Description
Retrieves parameters for interest rate queries.

### Method
GET

### Endpoint
/ParametrosConsulta

### Query Parameters
- **limit** (int) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- **codigoSegmento** (str) - Code for the segment.
- **segmento** (str) - Name of the segment.
- **codigoModalidade** (str) - Code for the modality.
- **modalidade** (str) - Name of the modality.
- **tipoModalidade** (str) - Type of the modality.

### Response Example
{
  "example": "codigoSegmento,segmento,codigoModalidade,modalidade,tipoModalidade\n1,Pessoa Física,204101,Cartão de crédito - rotativo total - Pré-fixado,D\n2,Pessoa Jurídica,210101,Capital de giro com prazo até 365 dias - Pré-fixado,D"
}
```

--------------------------------

### Querying TaxasJurosMensalPorMes

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata examples.ipynb

This example demonstrates how to query monthly interest rates for a specific month, limiting the results to 10.

```APIDOC
## GET /TaxasJurosMensalPorMes

### Description
Retrieves monthly interest rates for a given month.

### Method
GET

### Endpoint
/TaxasJurosMensalPorMes

### Query Parameters
- **Mes** (str) - Required - The month to query (e.g., 'Jan-2020').
- **limit** (int) - Optional - The maximum number of results to return.

### Response
#### Success Response (200)
- **Mes** (str) - The month of the interest rate.
- **Modalidade** (str) - The modality of the interest rate.
- **Posicao** (int) - The position of the interest rate.
- **InstituicaoFinanceira** (str) - The financial institution.
- **TaxaJurosAoMes** (float) - The interest rate per month.
- **TaxaJurosAoAno** (float) - The interest rate per year.
- **cnpj8** (str) - The 8-digit CNPJ of the institution.
- **anoMes** (str) - The year and month in YYYY-MM format.

### Response Example
{
  "example": "Mes,Modalidade,Posicao,InstituicaoFinanceira,TaxaJurosAoMes,TaxaJurosAoAno,cnpj8,anoMes\nJan-2020,FINANCIAMENTO IMOBILIÁRIO COM TAXAS DE MERCADO...,1,CAIXA ECONOMICA FEDERAL,0.39,4.75,00360305,2020-01"
}
```

--------------------------------

### Initialize TaxaJuros Client

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata taxas de juros cheque especial.ipynb

Instantiate the TaxaJuros client from the 'bcb' library to access interest rate data. Ensure the library is installed.

```python
from bcb import TaxaJuros

tj = TaxaJuros()
```

--------------------------------

### Initialize SPI Service and Select Fields

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata examples.ipynb

Initializes the SPI service and retrieves an endpoint for 'PixLiquidadosAtual'. It then starts building a query to select 'Data' and 'Media' fields.

```python
pix = SPI()

ep = pix.get_endpoint("PixLiquidadosAtual")
(ep.query()
   .select(ep.Data, ep.Media)
#    .filter(ep.Data >= datetime(2023, 1, 1))
```

--------------------------------

### Querying PixLiquidadosAtual with Limit

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata examples.ipynb

This example shows how to retrieve a limited number of records from the PixLiquidadosAtual endpoint, ordered by date.

```APIDOC
## Get PixLiquidadosAtual with Limit

### Description
Retrieves a specified number of records from the PixLiquidadosAtual entity set, ordered by the 'Data' property in ascending order.

### Method
GET (Implicit via client library)

### Endpoint
/PixLiquidadosAtual

### Parameters
#### Path Parameters
- **Data** (datetime) - Optional - The date to order by.

#### Query Parameters
- **limit** (int) - Required - The maximum number of records to return.
- **$orderby** (string) - Optional - Specifies the order of the results. Example: `Data asc`

### Request Example
```python
ep = spi.get_endpoint('PixLiquidadosAtual')
ep.get(ep.Data.asc(), limit=10)
```

### Response
#### Success Response (200)
Returns a DataFrame containing the first 'limit' records, ordered by 'Data' in ascending order.

#### Response Example
```
         Data  Quantidade      Total   Media
0  2020-11-03        2345     210.24   89.65
1  2020-11-04        2629     336.37  127.94
...
```
```

--------------------------------

### Initialize BCB Expectations Client

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/expectativas IPCA anual.ipynb

Imports necessary libraries and initializes the Expectativas client from the bcb library. Ensure the bcb library is installed and accessible.

```python
import sys
sys.path.insert(0, '..')
import pandas as pd
from bcb import Expectativas
```

--------------------------------

### Get Endpoint and Query Data (with category)

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/dinheiro em circulação.ipynb

Get the 'informacoes_diarias_com_categoria' endpoint and query the first 10 results.

```APIDOC
## Get Endpoint and Query Data (with category)

### Description
Retrieve the endpoint for 'informacoes_diarias_com_categoria' and fetch the first 10 records using `limit()` and `collect()`.

### Method
```python
ep = em.get_endpoint('informacoes_diarias_com_categoria')
df = (
    ep.query()
    .limit(10)
    .collect()
)
```

### Response Example (DataFrame)
```
         Data  Quantidade         Valor              Categoria Denominacao  \
0  1994-11-22   204914511  1.024573e+09  Cédulas - 1a. família        5.00   
1  2019-09-13  1200332884  1.200333e+07   Moedas - 2a. Família        0.01   
2  2019-09-13  5392981432  2.696491e+08   Moedas - 2a. Família        0.05   
3  2019-09-13  5681159148  5.681159e+08   Moedas - 2a. Família        0.10   
4  2019-09-13  2661509938  6.653775e+08   Moedas - 2a. Família        0.25   
5  2019-09-13  2567531046  1.283766e+09   Moedas - 2a. Família        0.50   
6  2019-09-13  3152225174  3.152225e+09   Moedas - 2a. Família        1.00   
7  2019-09-13     3508356  3.508356e+07  Cédulas - em polímero       10.00   
8  2019-09-13   148761504  1.487615e+08  Cédulas - 1a. família        1.00   
9  2019-09-13   151965810  3.039316e+08  Cédulas - 1a. família        2.00   

   Especie  
0  Cédulas  
1   Moedas  
2   Moedas  
3   Moedas  
4   Moedas  
5   Moedas  
6   Moedas  
7  Cédulas  
8  Cédulas  
9  Cédulas  
```
```

--------------------------------

### Querying MercadoImobiliario Endpoint

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata examples.ipynb

This example demonstrates how to retrieve data from the 'mercadoimobiliario' entity set with a limit on the number of results.

```APIDOC
## Get MercadoImobiliario Data

### Description
Retrieves data from the 'mercadoimobiliario' entity set, limiting the number of returned records to 20.

### Method
GET (Implicit via client library)

### Endpoint
/mercadoimobiliario

### Parameters
#### Query Parameters
- **limit** (int) - Optional - The maximum number of records to return. If not specified, all records may be returned (subject to server limits).

### Request Example
```python
mi.get_endpoint('mercadoimobiliario').get(limit=20)
```

### Response
#### Success Response (200)
Returns a DataFrame containing the requested data from the 'mercadoimobiliario' entity set, up to the specified limit.

#### Response Example
```
         Data                                               Info         Valor
0  2017-11-30         credito_estoque_carteira_credito_pj_sfh_ba  4.863160e+08
1  2015-06-30       credito_estoque_carteira_credito_pj_livre_pi  1.457705e+08
...
```
```

--------------------------------

### Querying PixLiquidadosAtual with Select, Filter, OrderBy, and Limit

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata examples.ipynb

This example demonstrates a more complex query on PixLiquidadosAtual, selecting specific properties, filtering by date, ordering by media, and limiting the results.

```APIDOC
## Advanced Query on PixLiquidadosAtual

### Description
Performs a query on the PixLiquidadosAtual entity set, selecting only 'Data' and 'Media' properties. It filters records where 'Data' is on or after January 1, 2023, orders them by 'Media' in descending order, and limits the results to 10.

### Method
GET (Implicit via client library)

### Endpoint
/PixLiquidadosAtual

### Parameters
#### Query Parameters
- **$select** (string) - Required - Specifies the properties to retrieve. Example: `Data,Media`
- **$filter** (string) - Required - Filters records based on the 'Data' property. Example: `Data ge 2023-01-01`
- **$orderby** (string) - Required - Orders the results by the 'Media' property in descending order. Example: `Media desc`
- **$limit** (int) - Required - Limits the number of returned records to 10.

### Request Example
```python
from datetime import datetime

ep.query().select(ep.Data, ep.Media).filter(ep.Data >= datetime(2023, 1, 1)).orderby(ep.Media.desc()).limit(10).collect()
```

### Response
#### Success Response (200)
Returns a DataFrame with 'Data' and 'Media' columns for the top 10 records matching the criteria.

#### Response Example
```
        Data   Media
0 2023-05-02  661.07
1 2023-04-10  661.04
...
```
```

--------------------------------

### Import necessary libraries

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/sgs get series with period index.ipynb

Imports the required libraries for interacting with the BCB system and handling data. Ensure these are installed.

```python
import sys
sys.path.insert(0, '..')
from datetime import datetime
import pandas as pd
from bcb import sgs
```

--------------------------------

### Querying PixLiquidadosAtual with OrderBy and Collect

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata examples.ipynb

This example demonstrates how to query the PixLiquidadosAtual endpoint, order the results by date in descending order, and collect them.

```APIDOC
## Query PixLiquidadosAtual

### Description
Queries the PixLiquidadosAtual entity set, orders the results by the 'Data' property in descending order, and collects the results.

### Method
GET (Implicit via client library)

### Endpoint
/PixLiquidadosAtual

### Parameters
#### Query Parameters
- **$orderby** (string) - Optional - Specifies the order of the results. Example: `Data desc`
- **$filter** (string) - Optional - Filters the results based on a condition.
- **$select** (string) - Optional - Specifies which properties to return.
- **$limit** (int) - Optional - Limits the number of results.
- **$skip** (int) - Optional - Skips a number of results.

### Request Example
```python
ep = spi.get_endpoint('PixLiquidadosAtual')
ep.query().orderby(ep.Data.desc()).collect()
```

### Response
#### Success Response (200)
Returns a DataFrame with the queried data. The columns depend on the properties selected or available.

#### Response Example
```
         Data  Quantidade        Total   Media
0  2023-07-10   116598174  69202307.13  593.51
1  2023-07-09    73589494  10131080.12  137.67
...
```
```

--------------------------------

### Install and Use uv for Python Commands

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/CLAUDE.md

Always use 'uv run' to execute Python commands. This ensures consistency with the project's environment management.

```bash
uv run python ...
uv run pytest ...
uv run ruff ...
```

--------------------------------

### Describe Specific Entity Set

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/bcb_Expectativas_da_SELIC_(nova_API).ipynb

Demonstrates how to get detailed information about a specific data entity set, including its properties.

```APIDOC
## Describe ExpectativasMercadoSelic Entity Set

### Description
Use `describe()` with an entity set name to view its details, including its `EntityType` and available `Properties`.

### Method
```python
em.describe('ExpectativasMercadoSelic')
```

### Response Example
```
EntitySet (Endpoint): ExpectativasMercadoSelic
EntityType: br.gov.bcb.olinda.servico.Expectativas.ExpectativaMercadoSelic
Properties: Indicador<str>, Data<str>, Reuniao<str>, Media<float>, Mediana<float>, DesvioPadrao<float>, Minimo<float>, Maximo<float>, numeroRespondentes<int>, baseCalculo<int>
```

## Describe ExpectativasMercadoTop5Selic Entity Set

### Description
Use `describe()` with the entity set name 'ExpectativasMercadoTop5Selic' to view its specific properties.

### Method
```python
em.describe('ExpectativasMercadoTop5Selic')
```

### Response Example
```
EntitySet (Endpoint): ExpectativasMercadoTop5Selic
EntityType: br.gov.bcb.olinda.servico.Expectativas.ExpectativasMercadoSelicTop5
Properties: indicador<str>, Data<str>, reuniao<str>, tipoCalculo<str>, media<float>, mediana<float>, desvioPadrao<float>, coeficienteVariacao<float>, minimo<float>, maximo<float>
```
```

--------------------------------

### Get list of available currencies

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/currency get with side.ipynb

Fetches a list of all supported currencies, including their codes, names, symbols, and associated country information.

```python
currency.get_currency_list()
```

--------------------------------

### Get ParametersConsulta Endpoint

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata taxas de juros cheque especial.ipynb

Initializes the OData API for 'ParametrosConsulta' and retrieves the first 10 entries. This is useful for understanding available parameters and their structure.

```python
api = tj.get_endpoint('ParametrosConsulta')
api.get(limit=10)
```

--------------------------------

### Get MercadoImobiliario Data with Limit

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata taxas de juros cheque especial.ipynb

Retrieves the first 20 records from the 'mercadoimobiliario' endpoint. This provides a sample of the real estate market data.

```python
mi.get_endpoint('mercadoimobiliario').get(limit=20)
```

--------------------------------

### Describe EntitySets

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/workspace.ipynb

This method describes the available EntitySets for a given service. It can be used to list all available datasets or to get details about a specific one.

```APIDOC
## describe()

### Description
Lists the available EntitySets or provides details for a specific EntitySet.

### Method
`describe()`

### Parameters
* **entity_set_name** (string) - Optional - The name of the EntitySet to describe.

### Example
```python
me.describe()
me.describe('ExpectativasMercadoTop5Anuais')
```
```

--------------------------------

### Describing TaxaJuros Endpoints

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata examples.ipynb

This snippet shows how to instantiate the `TaxaJuros` client and use the `describe` method to list and get details about available entity sets.

```APIDOC
## Describing TaxaJuros Endpoints

### Description
This example demonstrates how to initialize the `TaxaJuros` client and use its `describe` method to inspect available entity sets and their details.

### Method
N/A (SDK method)

### Endpoint
N/A (SDK method)

### Parameters
#### Method Parameters
- **endpoint_name** (str) - Optional - The name of the entity set to describe. If not provided, lists all available entity sets.

### Request Example
```python
from bcb import TaxaJuros

tj = TaxaJuros()
tj.describe()
tj.describe('ParametrosConsulta')
tj.describe('TaxasJurosMensalPorMes')
tj.describe('TaxasJurosDiariaPorInicioPeriodo')
tj.describe('ConsultaUnificada')
tj.describe('ConsultaDatas')
```

### Response
#### Success Response
- **EntitySets** (list of strings) - A list of available entity set names.
- **EntitySet (Endpoint)** (object) - Details about a specific entity set when an endpoint name is provided.

#### Response Example
```
EntitySets:
  TaxasJurosMensalPorMes
  ParametrosConsulta
  TaxasJurosDiariaPorInicioPeriodo
  ConsultaUnificada
  ConsultaDatas

EntitySet (Endpoint): ParametrosConsulta
```
```

--------------------------------

### Describe 'CotacaoMoedaPeriodo' Endpoint

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/currency PTAX.ipynb

Details the 'CotacaoMoedaPeriodo' function, outlining its parameters (currency, start date, end date), entity set, and available properties.

```python
ptax.describe('CotacaoMoedaPeriodo')
```

--------------------------------

### Get Specific Endpoint for Daily Interest Rates

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata taxas de juros cheque especial.ipynb

Retrieves a specific endpoint object for daily interest rates based on the start of the period. This endpoint will be used for subsequent queries.

```python
ep = service.get_endpoint('TaxasJurosDiariaPorInicioPeriodo')
```

--------------------------------

### Initialize TarifasBancarias Service and Describe

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata taxas de juros cheque especial.ipynb

Initializes the TarifasBancariasPorInstituicaoFinanceira service and displays its available entity sets and function imports. This provides an overview of the banking fees data available.

```python
from bcb import TarifasBancariasPorInstituicaoFinanceira
em = TarifasBancariasPorInstituicaoFinanceira()
em.describe()
```

--------------------------------

### Query PixLiquidadosAtual with Select, Filter, OrderBy, and Limit

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata taxas de juros cheque especial.ipynb

Retrieves specific data (Data and Media) for Pix liquidations starting from January 1, 2023, ordered by Media in descending order, with a limit of 10 results. Requires the 'spi' object and 'datetime' to be imported.

```python
from datetime import datetime


ep.query().select(ep.Data, ep.Media).filter(ep.Data >= datetime(2023, 1, 1)).orderby(ep.Media.desc()).limit(10).collect()
```

--------------------------------

### Get and query categorized endpoint

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/dinheiro em circulação.ipynb

Retrieves the 'informacoes_diarias_com_categoria' endpoint and fetches the first 10 records. This endpoint includes additional categorization of money in circulation.

```python
ep = em.get_endpoint('informacoes_diarias_com_categoria')
df = (
    ep.query()
    .limit(10)
    .collect()
)
```

--------------------------------

### Initialize and Describe Expectativas Client

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/bcb_Expectativas_da_SELIC_(nova_API).ipynb

Initialize the Expectativas client and call describe() to list all available entity sets for querying economic expectations.

```python
em = Expectativas()
em.describe()
```

--------------------------------

### Get Endpoint and Query Data

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/dinheiro em circulação.ipynb

Get a specific endpoint and query data with limit and collect.

```APIDOC
## Get Endpoint and Query Data

### Description
Retrieve a specific endpoint using `get_endpoint()` and then use the query builder to fetch data. The `limit()` method restricts the number of results, and `collect()` retrieves the data as a pandas DataFrame.

### Method
```python
ep = em.get_endpoint('informacoes_diarias')
df = (
    ep.query()
    .limit(10)
    .collect()
)
```

### Response Example (DataFrame)
```
         Data  Quantidade         Valor Denominacao  Especie
0  1994-10-03   692701959  6.927020e+06        0.01   Moedas
1  1994-10-03   462277579  2.311388e+07        0.05   Moedas
2  1994-10-03   404559065  4.045591e+07        0.10   Moedas
3  1994-10-03     1492870  3.732175e+05        0.25   Moedas
4  1994-10-03   278901842  1.394509e+08        0.50   Moedas
5  1994-10-03   267853898  2.678539e+08        1.00  Cédulas
6  1994-10-03   181609358  1.816094e+08        1.00   Moedas
7  1994-10-03   252922174  1.264611e+09        5.00  Cédulas
8  1994-10-03   273630983  2.736310e+09       10.00  Cédulas
9  1994-10-03    28945486  1.447274e+09       50.00  Cédulas
```
```

--------------------------------

### Build Project Documentation

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/CLAUDE.md

Generate HTML documentation for the project using Sphinx. Navigate to the 'docs' directory before running the build command.

```bash
cd docs && uv run sphinx-build -b html . _build/html
```

--------------------------------

### Get multiple currencies with side and groupby

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/currency get.ipynb

Retrieves data for multiple currencies (USD, EUR) with both 'ask' and 'bid' sides, grouped by 'side'. This provides a DataFrame with ask and bid prices for each currency.

```python
df = currency.get(['USD', 'EUR'], start='2000-01-01', end='2021-01-01', side='both', groupby='side')
```

--------------------------------

### Get Monthly Interest Rates with Limit

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/workspace.ipynb

Retrieves monthly interest rate data for a specific month, limiting the results to the top 10 entries. This is useful for quickly inspecting interest rate trends for a given month.

```python
tj.get_endpoint('TaxasJurosMensalPorMes').get(limit=10, Mes='Jan-2020')
```

--------------------------------

### Instantiate and Describe SPI API

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/docs/odata.md

Import and instantiate the SPI API class. Then, call the 'describe' method to view available endpoints.

```python
from bcb.odata.api import SPI

spi = SPI()
spi.describe()
```

--------------------------------

### Get Endpoint Data

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/workspace.ipynb

Retrieves data from a specified endpoint with optional filtering and limits.

```APIDOC
## get(filter, limit)

### Description
Retrieves data from an endpoint, allowing filtering and limiting the number of results.

### Method
`get(filter, limit)`

### Parameters
* **filter** - Optional - Criteria to filter the data.
* **limit** (integer) - Optional - The maximum number of results to return.

### Example
```python
api = ptax.get_endpoint('Moedas')
api.get(api.tipoMoeda == 'B', limit=10)
```
```

--------------------------------

### Initialize Expectativas and Describe Available Entities

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/bcb_Expectativas_da_SELIC_(nova_API).ipynb

This snippet shows how to initialize the `Expectativas` client and list all available data entities.

```APIDOC
## Initialize Expectativas Client

### Description
Instantiate the `Expectativas` client to interact with the BCB market expectations API.

### Method
```python
em = Expectativas()
```

## Describe Available Entities

### Description
Call the `describe()` method on the `Expectativas` client to get a list of all available entity sets (data endpoints).

### Method
```python
em.describe()
```

### Response Example
```
EntitySets:
  ExpectativasMercadoTop5Anuais
  ExpectativasMercadoInstituicoes
  ExpectativaMercadoMensais
  ExpectativasMercadoInflacao12Meses
  ExpectativasMercadoSelic
  ExpectativasMercadoTop5Selic
  ExpectativasMercadoTop5Mensais
  ExpectativasMercadoTrimestrais
  ExpectativasMercadoAnuais
```
```

--------------------------------

### Get PTAX Endpoint Data

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/workspace.ipynb

Retrieves PTAX data for a specified function import with parameters.

```APIDOC
## get(fields, limit, **kwargs)

### Description
Retrieves PTAX data for a specified function import, allowing selection of fields, limiting results, and providing function-specific parameters.

### Method
`get(fields, limit, **kwargs)`

### Parameters
* **fields** - The fields to retrieve.
* **limit** (integer) - The maximum number of results to return.
* **kwargs** - Function-specific parameters such as `moeda`, `dataInicial`, `dataFinalCotacao`.

### Example
```python
api = ptax.get_endpoint('CotacaoMoedaPeriodo')
api.get(
    api.dataHoraCotacao, api.cotacaoCompra, api.cotacaoVenda,
    limit=10,
    moeda='USD',
    dataInicial='01/01/2022',
    dataFinalCotacao='01/10/2022'
)
```
```

--------------------------------

### Consulta de Taxas de Juros Diárias por Período de Início

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata taxas de juros cheque especial.ipynb

Retrieve daily interest rates based on the start period of the interval. This endpoint allows filtering by various parameters.

```APIDOC
## GET TaxasJurosDiariaPorInicioPeriodo

### Description
Retrieves daily interest rates based on the start period.

### Method
GET

### Endpoint
/TaxasJurosDiariaPorInicioPeriodo

### Query Parameters
- **InicioPeriodo** (str) - Required - The start date of the period.
- **FimPeriodo** (str) - Optional - The end date of the period.
- **codigoSegmento** (str) - Optional - Filter by segment code.
- **Segmento** (str) - Optional - Filter by segment name.
- **codigoModalidade** (str) - Optional - Filter by modality code.
- **Modalidade** (str) - Optional - Filter by modality name.
- **Posicao** (int) - Optional - Filter by position.
- **InstituicaoFinanceira** (str) - Optional - Filter by financial institution.
- **cnpj8** (str) - Optional - Filter by institution's 8-digit CNPJ.

### Response
#### Success Response (200)
- **InicioPeriodo** (str) - The start date of the period.
- **FimPeriodo** (str) - The end date of the period.
- **codigoSegmento** (str) - Code for the segment.
- **Segmento** (str) - Name of the segment.
- **codigoModalidade** (str) - Code for the modality.
- **Modalidade** (str) - Name of the modality.
- **Posicao** (int) - The position or ranking of the rate.
- **InstituicaoFinanceira** (str) - The financial institution.
- **TaxaJurosAoMes** (float) - The interest rate per month.
- **TaxaJurosAoAno** (float) - The interest rate per year.
- **cnpj8** (str) - The 8-digit CNPJ of the institution.
```

--------------------------------

### Describe 'CotacaoMoedaDia' Function

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/currency PTAX.ipynb

Get detailed information about the 'CotacaoMoedaDia' function, including its parameters and properties.

```APIDOC
## Describe 'CotacaoMoedaDia' Function

### Description
Understand the parameters and output properties for fetching currency exchange rates for a single day.

### Code
```python
ptax.describe('CotacaoMoedaDia')
```

### Output Example
```
Function: CotacaoMoedaDia
Parameters: moeda <str>, dataCotacao <str>
EntitySet: _CotacaoMoedaDia
EntityType: br.gov.bcb.olinda.servico.PTAX.TipoCotacaoMoeda
Properties: paridadeCompra <float>, paridadeVenda <float>, cotacaoCompra <float>, cotacaoVenda <float>, dataHoraCotacao <str>, tipoBoletim <str>
```
```

--------------------------------

### Describe 'CotacaoMoedaPeriodo' Function

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/currency PTAX.ipynb

Get detailed information about the 'CotacaoMoedaPeriodo' function, including its parameters and properties.

```APIDOC
## Describe 'CotacaoMoedaPeriodo' Function

### Description
Understand the parameters and output properties for fetching currency exchange rates over a period.

### Code
```python
ptax.describe('CotacaoMoedaPeriodo')
```

### Output Example
```
Function: CotacaoMoedaPeriodo
Parameters: moeda <str>, dataInicial <str>, dataFinalCotacao <str>
EntitySet: _CotacaoMoedaPeriodo
EntityType: br.gov.bcb.olinda.servico.PTAX.TipoCotacaoMoeda
Properties: paridadeCompra <float>, paridadeVenda <float>, cotacaoCompra <float>, cotacaoVenda <float>, dataHoraCotacao <str>, tipoBoletim <str>
```
```

--------------------------------

### Describe 'CotacaoDolarDia' Function

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/currency PTAX.ipynb

Get detailed information about the 'CotacaoDolarDia' function, including its parameters and properties.

```APIDOC
## Describe 'CotacaoDolarDia' Function

### Description
Use `describe()` with a function name to understand its parameters and the structure of its output.

### Code
```python
ptax.describe('CotacaoDolarDia')
```

### Output Example
```
Function: CotacaoDolarDia
Parameters: dataCotacao <str>
EntitySet: _CotacaoDolarDia
EntityType: br.gov.bcb.olinda.servico.PTAX.TipoCotacaoDolar
Properties: cotacaoCompra <float>, cotacaoVenda <float>, dataHoraCotacao <str>
```
```

--------------------------------

### Get IFDATA Endpoint Data

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/workspace.ipynb

Retrieves data from the IFDATA service's 'ListaDeRelatorio' function import.

```APIDOC
## get(limit)

### Description
Retrieves a list of reports from the IFDATA service.

### Method
`get(limit)`

### Parameters
* **limit** (integer) - The maximum number of results to return.

### Example
```python
api = ifdata.get_endpoint('ListaDeRelatorio')
api.get(limit=10)
```
```

--------------------------------

### Accessing the TaxasJurosDiariaPorInicioPeriodo EntitySet

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata ODataAPI.ipynb

Demonstrates how to get an endpoint for 'TaxasJurosDiariaPorInicioPeriodo' data and retrieve a limited number of records.

```APIDOC
## GET /TaxasJurosDiariaPorInicioPeriodo

### Description
Retrieves daily interest rate data based on the start of the period.

### Method
GET

### Endpoint
/TaxasJurosDiariaPorInicioPeriodo

### Parameters
#### Query Parameters
- **$limit** (int) - Optional - Limits the number of records returned.

### Response
#### Success Response (200)
- **InicioPeriodo** (str) - The start date of the period.
- **FimPeriodo** (str) - The end date of the period.
- **Segmento** (str) - The segment (e.g., 'PESSOA JURÍDICA').
- **Modalidade** (str) - The type of operation or loan.
- **Posicao** (int) - The position or order.
- **InstituicaoFinanceira** (str) - The financial institution.
- **TaxaJurosAoMes** (float) - The monthly interest rate.
- **TaxaJurosAoAno** (float) - The annual interest rate.
- **cnpj8** (str) - The 8-digit CNPJ of the institution.

### Request Example
```python
ep = service.get_endpoint("TaxasJurosDiariaPorInicioPeriodo")
ep.query().limit(10).collect()
```

### Response Example
```json
{
  "InicioPeriodo": "2022-08-19",
  "FimPeriodo": "2022-08-25",
  "Segmento": "PESSOA JURÍDICA",
  "Modalidade": "ADIANTAMENTO SOBRE CONTRATOS DE CÂMBIO (ACC) - ...",
  "Posicao": 1,
  "InstituicaoFinanceira": "BCO SOCIETE GENERALE BRASIL",
  "TaxaJurosAoMes": 0.0,
  "TaxaJurosAoAno": 0.0,
  "cnpj8": "61533584"
}
```
```

--------------------------------

### Initialize and Describe Expectativas Service

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata examples.ipynb

Initializes the Expectativas service and calls the describe method to list available entity sets. This helps in understanding the available data.

```python
service = Expectativas()
service.describe()
```

--------------------------------

### Accessing the Selic EntitySet

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata ODataAPI.ipynb

Demonstrates how to get an endpoint for 'Selic' data and retrieve a limited number of records.

```APIDOC
## GET /Selic

### Description
Retrieves a list of Selic operations data.

### Method
GET

### Endpoint
/Selic

### Parameters
#### Query Parameters
- **$limit** (int) - Optional - Limits the number of records returned.

### Response
#### Success Response (200)
- **mes** (str) - The month of the operation.
- **valorOperacoes** (float) - The value of the operations.
- **quantidadeOperacoes** (float) - The quantity of operations.

### Request Example
```python
ep = service.get_endpoint('Selic')
ep.query().limit(10).collect()
```

### Response Example
```json
{
  "mes": "abr/2002",
  "valorOperacoes": 77697.0,
  "quantidadeOperacoes": 1794.0
}
```
```

--------------------------------

### Query and Collect Data

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/bcb_Expectativas_da_SELIC_(nova_API).ipynb

Shows how to get a specific endpoint, apply filters, and collect the resulting data.

```APIDOC
## Query and Collect Data from ExpectativasMercadoSelic

### Description
This example demonstrates how to obtain a specific endpoint object, apply filters based on properties like `baseCalculo` and `Data`, and then collect the filtered data.

### Method
```python
ep = em.get_endpoint('ExpectativasMercadoSelic')
ep.query().filter(ep.baseCalculo == 0, ep.Data == '2022-03-18').collect()
```

### Parameters
#### Query Parameters
- **baseCalculo** (int) - Filter for a specific base calculation value.
- **Data** (str) - Filter for a specific date in 'YYYY-MM-DD' format.

### Response Example (Success)
```
   Indicador        Data  Reuniao    Media  Mediana  DesvioPadrao  Minimo  \
0      Selic  2022-03-18  R2/2024   8.5648     8.50        0.7776    7.00   
1      Selic  2022-03-18  R1/2024   8.6306     8.50        1.0661    5.50   
2      Selic  2022-03-18  R8/2023   9.0146     9.00        1.0108    5.50   
3      Selic  2022-03-18  R7/2023   9.4193     9.25        1.0872    6.00   
4      Selic  2022-03-18  R6/2023   9.8478     9.75        1.0863    6.50   
5      Selic  2022-03-18  R5/2023  10.3791    10.50        1.0903    7.00   
6      Selic  2022-03-18  R4/2023  11.0104    11.00        1.0200    8.00   
7      Selic  2022-03-18  R3/2023  11.6004    11.75        0.9589    9.00   
8      Selic  2022-03-18  R2/2023  12.1835    12.25        0.7984   10.00   
9      Selic  2022-03-18  R1/2023  12.5931    12.75        0.6619   10.00   
10     Selic  2022-03-18  R8/2022  12.8805    13.00        0.4228   11.50   
11     Selic  2022-03-18  R7/2022  12.9238    13.00        0.3948   11.00   
12     Selic  2022-03-18  R6/2022  12.9422    13.00        0.3569   11.50   
13     Selic  2022-03-18  R5/2022  12.9441    13.00        0.3374   12.00   
14     Selic  2022-03-18  R4/2022  12.9294    13.00        0.3413   11.75   
15     Selic  2022-03-18  R3/2022  12.6177    12.75        0.2215   11.75   

    Maximo  numeroRespondentes  baseCalculo  
0    10.75                  27            0  
1    12.75                  94            0  
2    13.00                 117            0  
3    13.25                 115            0  
4    13.25                 115            0  
5    13.25                 115            0  
6    13.25                 115            0  
7    13.25                 115            0  
8    13.50                 115            0  
9    13.50                 117            0  
10   13.50                 125            0  
11   13.50                 123            0  
12   13.50                 123            0  
13   13.50                 123            0  
14   13.50                 123            0  
15   13.00                 123            0  
```
```

--------------------------------

### Initialize and Describe PTAX Service

Source: https://github.com/wilsonfreitas/python-bcb/blob/main/notebooks/odata taxas de juros cheque especial.ipynb

Initializes the PTAX service and describes its available EntitySets and FunctionImports.

```python
from bcb import PTAX

ptax = PTAX()
ptax.describe()
```
Tokens:
Raw