Usage

This guide provides an overview of how to use the BCRA API Connector for various tasks.

Initializing the Connector

To start using the BCRA API Connector, first import the necessary classes and create an instance of the BCRAConnector:

import os
import sys
import logging
from datetime import datetime, timedelta
from bcra_connector import BCRAConnector

# Initialize the connector (default language is Spanish)
connector = BCRAConnector()

# For English responses, use:
# connector = BCRAConnector(language="en-US")

Fetching Principal Variables

To retrieve all principal variables published by BCRA:

variables = connector.get_principales_variables()
for var in variables[:5]:  # Print first 5 for brevity
    print(f"{var.descripcion}: {var.ultValorInformado} ({var.ultFechaInformada})")

This will return a list of PrincipalesVariables objects, each containing information about a specific variable including metadata like tipoSerie, periodicidad, and moneda.

Retrieving Historical Data

To fetch historical data for a specific variable:

id_variable = 1  # e.g., Reservas Internacionales del BCRA
end_date = datetime.now()
start_date = end_date - timedelta(days=30)
response = connector.get_datos_variable(id_variable, desde=start_date, hasta=end_date)
for result in response.results:
    for detalle in result.detalle[-5:]:  # Print last 5 for brevity
        print(f"{detalle.fecha}: {detalle.valor}")

This returns a DatosVariableResponse object containing metadata and a list of DatosVariable results, each with a detalle list of DetalleMonetaria data points.

Getting the Latest Value

To retrieve the most recent value for a variable:

latest = connector.get_latest_value(id_variable)
print(f"Latest value for Variable {id_variable}: {latest.valor} ({latest.fecha})")

Using the Cheques Module

To fetch information about financial entities:

entities = connector.get_entidades()
for entity in entities[:5]:  # Print first 5 for brevity
    print(f"{entity.codigo_entidad}: {entity.denominacion}")

To check if a specific check is reported:

codigo_entidad = 11  # Example entity code
numero_cheque = 20377516  # Example check number
cheque = connector.get_cheque_denunciado(codigo_entidad, numero_cheque)
print(f"Check {cheque.numero_cheque} is {'reported' if cheque.denunciado else 'not reported'}")

Using the Estadísticas Cambiarias Module

To fetch the list of all currencies:

currencies = connector.get_divisas()
for currency in currencies[:5]:  # Print first 5 for brevity
    print(f"{currency.codigo}: {currency.denominacion}")

To get currency quotations for a specific date:

fecha = "2024-06-12"  # Example date
quotations = connector.get_cotizaciones(fecha)
for detail in quotations.detalle[:5]:  # Print first 5 for brevity
    print(f"{detail.codigo_moneda}: {detail.tipo_cotizacion}")

To fetch the evolution of a specific currency:

moneda = "USD"
fecha_desde = "2024-06-01"
fecha_hasta = "2024-06-30"
evolution = connector.get_evolucion_moneda(moneda, fecha_desde, fecha_hasta)
for quotation in evolution[:5]:  # Print first 5 for brevity
    print(f"{quotation.fecha}: {quotation.detalle[0].tipo_cotizacion}")

Using the Central de Deudores Module

To query debtor information, historical debts, and rejected checks by CUIT/CUIL:

identificacion = "20123456789"  # Example CUIT

# Get current debts
deudor = connector.get_deudas(identificacion)
print(f"Debtor: {deudor.denominacion}")
for periodo in deudor.periodos:
    for entidad in periodo.entidades:
        print(f"- {entidad.entidad}: Situación {entidad.situacion}, ${entidad.monto}k")

# Get historical debts (last 24 months)
historico = connector.get_deudas_historicas(identificacion)
print(f"Historical periods found: {len(historico.periodos)}")

# Get rejected checks
rejected = connector.get_cheques_rechazados(identificacion)
for causal in rejected.causales:
    print(f"Causal: {causal.causal}")
    for entidad in causal.entidades:
        print(f"  - Entity {entidad.entidad}: {len(entidad.detalle)} checks")

DataFrame Conversion

Most data models include a to_dataframe() method for easy integration with data analysis workflows. This requires pandas to be installed (pip install bcra-connector[pandas]).

# Convert Principal Variables to DataFrame
variables = connector.get_principales_variables()
df_vars = variables.to_dataframe()

# Convert Central de Deudores info to DataFrame
deudor = connector.get_deudas(identificacion)
df_deudas = deudor.to_dataframe()

# Convert Rejected Checks to DataFrame
rejected = connector.get_cheques_rechazados(identificacion)
df_checks = rejected.to_dataframe()

Error Handling

The connector uses custom exceptions to handle errors. Always wrap your code in try-except blocks to handle potential BCRAApiError exceptions:

import os
import sys
import logging
from typing import Callable, Type, Any
from datetime import datetime, timedelta
from bcra_connector import BCRAApiError, BCRAConnector

try:
    variables = connector.get_principales_variables()
except BCRAApiError as e:
    print(f"An error occurred: {str(e)}")

Advanced Usage

For more advanced usage examples, including error handling, different configurations, and data visualization, please refer to the Examples section.