API Reference

This section provides a detailed reference for the BCRA API Connector’s classes and methods.

API Reference

This section provides a detailed reference for the BCRA API Connector’s classes and methods, automatically generated from the source code.

BCRAConnector

BCRA API client implementation for accessing financial data from Argentina’s Central Bank. Provides interfaces for variables, checks, and currency exchange rate data endpoints. Handles rate limiting, retries, and error cases.

exception src.bcra_connector.bcra_connector.BCRAApiError[source]

Bases: Exception

Custom exception for BCRA API errors.

class src.bcra_connector.bcra_connector.BCRAConnector(language: str = 'es-AR', verify_ssl: bool = True, debug: bool = False, rate_limit: RateLimitConfig | None = None, timeout: TimeoutConfig | float | None = None)[source]

Bases: object

A connector for the BCRA (Banco Central de la República Argentina) APIs.

This class provides methods to interact with various BCRA APIs, including Principales Variables (Monetarias v4.0), Cheques, and Estadísticas Cambiarias.

BASE_URL = 'https://api.bcra.gob.ar'

MAX_RETRIES = 3

RETRY_DELAY = 1

DEFAULT_RATE_LIMIT = RateLimitConfig(calls=10, period=1.0, _burst=20)

DEFAULT_TIMEOUT = TimeoutConfig(connect=3.05, read=27.0)

get_principales_variables() → List[PrincipalesVariables][source]

Fetch the list of all monetary series and principal variables published by BCRA (API v4.0).

Returns:: A list of PrincipalesVariables objects with extended metadata
Raises:: BCRAApiError – If the API request fails or returns unexpected data

get_datos_variable(id_variable: int, desde: datetime | None = None, hasta: datetime | None = None, limit: int | None = None, offset: int | None = None) → DatosVariableResponse[source]

Fetch the list of values for a variable/series (API v4.0).

Uses pagination via limit and offset. If desde/hasta are omitted, API defaults apply.

Parameters:

id_variable – The ID of the desired variable. Case-sensitive {IdVariable} in URL path.
desde – The start date of the range to query (inclusive). Optional. YYYY-MM-DD format.
hasta – The end date of the range to query (inclusive). Optional. YYYY-MM-DD format.
limit – Maximum number of results (10-3000). Optional, API defaults to 1000.
offset – Number of results to skip for pagination. Optional, defaults to 0.

Returns:

A DatosVariableResponse object containing metadata and results.

Raises:

ValueError – If date range is invalid or limit/offset are out of bounds.
BCRAApiError – If the API request fails.

get_latest_value(id_variable: int) → DetalleMonetaria[source]

Fetch the latest value for a specific variable using API v4.0.

Parameters:: id_variable – The ID of the desired variable.
Returns:: The latest data point (DetalleMonetaria object) for the specified variable.
Raises:: BCRAApiError – If the API request fails or if no data is available.

get_entidades() → List[Entidad][source]

Fetch the list of all financial entities.

Returns:: A list of Entidad objects
Raises:: BCRAApiError – If the API request fails

get_cheque_denunciado(codigo_entidad: int, numero_cheque: int) → Cheque[source]

Fetch information about a reported check.

Parameters:

codigo_entidad – The code of the financial entity
numero_cheque – The check number

Returns:

A Cheque object with the check’s information

Raises:

BCRAApiError – If the API request fails or returns unexpected data

get_divisas() → List[Divisa][source]

Fetch the list of all currencies.

Returns:: A list of Divisa objects
Raises:: BCRAApiError – If the API request fails or returns unexpected data

get_cotizaciones(fecha: str | None = None) → CotizacionFecha[source]

Fetch currency quotations for a specific date.

Parameters:: fecha – The date for which to fetch quotations (format: YYYY-MM-DD), defaults to None (latest date)
Returns:: A CotizacionFecha object with the quotations
Raises:: BCRAApiError – If the API request fails or returns unexpected data

get_evolucion_moneda(moneda: str, fecha_desde: str | None = None, fecha_hasta: str | None = None, limit: int = 1000, offset: int = 0) → List[CotizacionFecha][source]

Fetch the evolution of a specific currency’s quotation.

Parameters:

moneda – The currency code (case-sensitive in URL path).
fecha_desde – Start date (format: YYYY-MM-DD), defaults to None.
fecha_hasta – End date (format: YYYY-MM-DD), defaults to None.
limit – Maximum number of results to return (10-1000), defaults to 1000.
offset – Number of results to skip, defaults to 0.

Returns:

A list of CotizacionFecha objects with the currency’s evolution data.

Raises:

BCRAApiError – If the API request fails or returns unexpected data.
ValueError – If the limit is out of range or offset is negative.

get_variable_by_name(variable_name: str) → PrincipalesVariables | None[source]

Find a principal variable or monetary series by its name (Uses Monetarias v3.0 API).

Parameters:: variable_name – The name of the variable/series to find (case-insensitive search).
Returns:: A PrincipalesVariables object if found, None otherwise.

get_variable_history(variable_name: str, days: int = 30, limit: int | None = None, offset: int | None = None) → List[DetalleMonetaria][source]

Get the historical data for a variable/series by name for the last n days (Uses Monetarias v4.0 API).

This method returns a flat list of data points for convenience.

Parameters:

variable_name – The name of the variable/series.
days – The number of days to look back, defaults to 30. Must be positive.
limit – Maximum number of results (10-3000). Optional.
offset – Number of results to skip for pagination. Optional.

Returns:

A list of DetalleMonetaria objects.

Raises:

ValueError – If the variable is not found or days/limit/offset are invalid.
BCRAApiError – If the API request fails.

get_currency_evolution(currency_code: str, days: int = 30, limit: int = 1000, offset: int = 0) → List[CotizacionFecha][source]

Get the evolution of a currency’s quotation for the last n days.

Parameters:

currency_code – The currency code (e.g., ‘USD’, ‘EUR’). Case-sensitive for URL.
days – The number of days to look back, defaults to 30. Must be positive.
limit – Maximum number of results (10-1000), defaults to 1000 for this specific API.
offset – Number of results to skip, defaults to 0.

Returns:

A list of CotizacionFecha objects.

Raises:

ValueError – If days/limit/offset are invalid.
BCRAApiError – If the API request fails.

check_denunciado(entity_name: str, check_number: int) → bool[source]

Check if a check is reported as stolen or lost.

Parameters:

entity_name – The name of the financial entity (case-insensitive search).
check_number – The check number. Must be positive.

Returns:

True if the check is reported, False otherwise.

Raises:

ValueError – If the entity is not found or check_number is invalid.
BCRAApiError – If the API request fails (other than a 404 for the check itself).

get_latest_quotations() → Dict[str, float][source]

Get the latest quotations (tipo_cotizacion) for all currencies.

Returns:: A dictionary with currency codes as keys and their latest quotations as values.
Raises:: BCRAApiError – If fetching quotations fails.

get_currency_pair_evolution(base_currency: str, quote_currency: str, days: int = 30) → List[Dict[str, Any]][source]

Get the evolution of a currency pair exchange rate for the last n days.

Calculates rate as (quote_currency_value / base_currency_value) using ARS as intermediary. Assumes both currencies are quoted against ARS by the API.

Parameters:

base_currency – The base currency code (e.g., ‘USD’). Case-sensitive for URL.
quote_currency – The quote currency code (e.g., ‘EUR’). Case-sensitive for URL.
days – The number of days to look back, defaults to 30. Must be positive.

Returns:

List of dictionaries with ‘fecha’ (ISO format) and ‘tasa’ (exchange rate).

Raises:

ValueError – If days is invalid.
BCRAApiError – If underlying API calls fail.

get_variable_correlation(variable_name1: str, variable_name2: str, days: int = 30) → float[source]

Calculate Pearson correlation between two variables/series over last n days (Monetarias v3.0).

Handles missing data by linear interpolation.

Parameters:

variable_name1 – Name of the first variable/series.
variable_name2 – Name of the second variable/series.
days – Number of days to look back (must be > 1).

Returns:

Correlation coefficient (-1 to 1), or NaN if not calculable.

Raises:

ValueError – If variables not found or days invalid.
BCRAApiError – If underlying API calls fail.

generate_variable_report(variable_name: str, days: int = 30) → Dict[str, Any][source]

Generate a comprehensive report for a given variable/series (Uses Monetarias v3.0 API).

Parameters:

variable_name – The name of the variable/series.
days – The number of days to look back, defaults to 30. Must be positive.

Returns:

A dictionary containing various statistics and information.

Raises:

ValueError – If the variable is not found or days is invalid.
BCRAApiError – If the API request fails.

get_deudas(identificacion: str) → Deudor[source]

Fetch current debts for a CUIT/CUIL/CDI from the Central de Deudores.

Parameters:

identificacion – The CUIT/CUIL/CDI (11 digits) to query.

Returns:

A Deudor object with current debt information.

Raises:

ValueError – If identificacion is not 11 digits.
BCRAApiError – If the API request fails.

get_deudas_historicas(identificacion: str) → Deudor[source]

Fetch historical debts (24 months) for a CUIT/CUIL/CDI.

Parameters:

identificacion – The CUIT/CUIL/CDI (11 digits) to query.

Returns:

A Deudor object with historical debt information.

Raises:

ValueError – If identificacion is not 11 digits.
BCRAApiError – If the API request fails.

get_cheques_rechazados(identificacion: str) → ChequesRechazados[source]

Fetch rejected checks for a CUIT/CUIL/CDI from the Central de Deudores.

Parameters:

identificacion – The CUIT/CUIL/CDI (11 digits) to query.

Returns:

A ChequesRechazados object with rejected check details.

Raises:

ValueError – If identificacion is not 11 digits.
BCRAApiError – If the API request fails.

Principales Variables (Monetarias v4.0)

Data models for BCRA’s Principal Variables API (Monetarias v4.0). Defines classes for handling economic indicators, their historical data, and API responses.

class src.bcra_connector.principales_variables.principales_variables.Resultset(count: int, offset: int, limit: int)[source]

Bases: object

Represents metadata about the result set for Monetarias API v4.0 data.

count: int

offset: int

limit: int

classmethod from_dict(data: Dict[str, Any]) → Resultset[source]: Create a Resultset instance from a dictionary.

to_dict() → Dict[str, Any][source]: Convert the Resultset instance to a dictionary.

class src.bcra_connector.principales_variables.principales_variables.Metadata(resultset: Resultset)[source]

Bases: object

Represents metadata about the response for Monetarias API v4.0 data.

resultset: Resultset

classmethod from_dict(data: Dict[str, Any]) → Metadata[source]: Create a Metadata instance from a dictionary.

class src.bcra_connector.principales_variables.principales_variables.PrincipalesVariables(idVariable: int, descripcion: str | None = None, categoria: str | None = None, tipoSerie: str | None = None, periodicidad: str | None = None, unidadExpresion: str | None = None, moneda: str | None = None, primerFechaInformada: date | None = None, ultFechaInformada: date | None = None, ultValorInformado: float | None = None)[source]

Bases: object

Represents a principal variable or monetary series from the BCRA API (v4.0).

Parameters:

idVariable – The ID of the variable/series.
descripcion – The description of the variable/series.
categoria – The category of the monetary series.
tipoSerie – The type of series.
periodicidad – The periodicity of the series.
unidadExpresion – The unit of expression.
moneda – The currency.
primerFechaInformada – The first date reported.
ultFechaInformada – The last date reported.
ultValorInformado – The last value reported.

idVariable: int

descripcion: str | None = None

categoria: str | None = None

tipoSerie: str | None = None

periodicidad: str | None = None

unidadExpresion: str | None = None

moneda: str | None = None

primerFechaInformada: date | None = None

ultFechaInformada: date | None = None

ultValorInformado: float | None = None

classmethod from_dict(data: Dict[str, Any]) → PrincipalesVariables[source]: Create a PrincipalesVariables instance from a dictionary (v4.0 format).

to_dict() → Dict[str, Any][source]: Convert the PrincipalesVariables instance to a dictionary (v4.0 format).

to_dataframe() → pd.DataFrame[source]

Convert the PrincipalesVariables instance to a pandas DataFrame.

Requires pandas to be installed: pip install bcra-connector[pandas]

Returns:: A single-row DataFrame with all variable attributes.
Raises:: ImportError – If pandas is not installed.

class src.bcra_connector.principales_variables.principales_variables.DetalleMonetaria(fecha: date, valor: float)[source]

Bases: object

Represents a single data point in the historical data for a variable/series (v4.0).

Parameters:

fecha – The date of the data point.
valor – The value of the variable/series on the given date.

fecha: date

valor: float

classmethod from_dict(data: Dict[str, Any]) → DetalleMonetaria[source]: Create a DetalleMonetaria instance from a dictionary.

to_dict() → Dict[str, Any][source]: Convert the DetalleMonetaria instance to a dictionary.

to_dataframe() → pd.DataFrame[source]

Convert the DetalleMonetaria instance to a pandas DataFrame.

Requires pandas: pip install bcra-connector[pandas]

Returns:: A single-row DataFrame with fecha and valor.
Raises:: ImportError – If pandas is not installed.

class src.bcra_connector.principales_variables.principales_variables.DatosVariable(idVariable: int, detalle: List[DetalleMonetaria])[source]

Bases: object

Represents historical data for a variable/series (v4.0 structure).

Parameters:

idVariable – The ID of the variable/series.
detalle – List of DetalleMonetaria objects with historical data points.

idVariable: int

detalle: List[DetalleMonetaria]

classmethod from_dict(data: Dict[str, Any]) → DatosVariable[source]: Create a DatosVariable instance from a dictionary.

to_dict() → Dict[str, Any][source]: Convert the DatosVariable instance to a dictionary.

to_dataframe() → pd.DataFrame[source]

Convert the historical data to a pandas DataFrame.

Returns a DataFrame with columns: idVariable, fecha, valor. Each row represents one data point from the detalle list.

Requires pandas: pip install bcra-connector[pandas]

Returns:: DataFrame with all historical data points.
Raises:: ImportError – If pandas is not installed.

class src.bcra_connector.principales_variables.principales_variables.DatosVariableResponse(status: int, metadata: Metadata, results: List[DatosVariable])[source]

Bases: object

Represents the full response for fetching historical data for a variable/series (v4.0).

Parameters:

status – HTTP status code.
metadata – Metadata object containing count, offset, and limit.
results – List of DatosVariable objects.

status: int

metadata: Metadata

results: List[DatosVariable]

classmethod from_dict(data: Dict[str, Any]) → DatosVariableResponse[source]: Create a DatosVariableResponse instance from a dictionary.

to_dict() → Dict[str, Any][source]: Convert the DatosVariableResponse instance to a dictionary.

Cheques

Data models and types for the BCRA Checks API. Defines classes for handling bank entities, check details, and API responses.

class src.bcra_connector.cheques.cheques.Entidad(codigo_entidad: int, denominacion: str)[source]

Bases: object

Represents a financial entity.

Parameters:

codigo_entidad – The entity’s code
denominacion – The entity’s name

codigo_entidad: int

denominacion: str

classmethod from_dict(data: Dict[str, Any]) → Entidad[source]: Create an Entidad instance from a dictionary.

to_dict() → Dict[str, Any][source]: Convert the instance to a dictionary.

to_dataframe() → pd.DataFrame[source]

Convert the Entidad instance to a pandas DataFrame.

Requires pandas: pip install bcra-connector[pandas]

Returns:: A single-row DataFrame with entity information.
Raises:: ImportError – If pandas is not installed.

class src.bcra_connector.cheques.cheques.ChequeDetalle(sucursal: int, numero_cuenta: int, causal: str)[source]

Bases: object

Represents details of a reported check.

Parameters:

sucursal – The branch number
numero_cuenta – The account number
causal – The reason for reporting

sucursal: int

numero_cuenta: int

causal: str

classmethod from_dict(data: Dict[str, Any]) → ChequeDetalle[source]: Create a ChequeDetalle instance from a dictionary.

to_dict() → Dict[str, Any][source]: Convert the instance to a dictionary.

class src.bcra_connector.cheques.cheques.Cheque(numero_cheque: int, denunciado: bool, fecha_procesamiento: date, denominacion_entidad: str, detalles: List[ChequeDetalle])[source]

Bases: object

Represents a reported check.

Parameters:

numero_cheque – The check number
denunciado – Whether the check is reported
fecha_procesamiento – The processing date
denominacion_entidad – The name of the entity
detalles – List of check details

numero_cheque: int

denunciado: bool

fecha_procesamiento: date

denominacion_entidad: str

detalles: List[ChequeDetalle]

classmethod from_dict(data: Dict[str, Any]) → Cheque[source]: Create a Cheque instance from a dictionary.

to_dict() → Dict[str, Any][source]: Convert the instance to a dictionary.

to_dataframe() → pd.DataFrame[source]

Convert the Cheque instance to a pandas DataFrame.

Returns a DataFrame with check information and flattened details. Each row represents one detail entry from the detalles list.

Requires pandas: pip install bcra-connector[pandas]

Returns:: DataFrame with check data and details.
Raises:: ImportError – If pandas is not installed.

class src.bcra_connector.cheques.cheques.EntidadResponse(status: int, results: List[Entidad])[source]

Bases: object

Represents the response for the Entidades endpoint.

Parameters:

status – The HTTP status code
results – List of Entidad objects

status: int

results: List[Entidad]

classmethod from_dict(data: Dict[str, Any]) → EntidadResponse[source]: Create an EntidadResponse instance from a dictionary.

class src.bcra_connector.cheques.cheques.ChequeResponse(status: int, results: Cheque)[source]

Bases: object

Represents the response for the Cheques Denunciados endpoint.

Parameters:

status – The HTTP status code
results – A Cheque object

status: int

results: Cheque

classmethod from_dict(data: Dict[str, Any]) → ChequeResponse[source]: Create a ChequeResponse instance from a dictionary.

class src.bcra_connector.cheques.cheques.ErrorResponse(status: int, error_messages: List[str])[source]

Bases: object

Represents an error response from the API.

Parameters:

status – The HTTP status code
error_messages – List of error messages

status: int

error_messages: List[str]

classmethod from_dict(data: Dict[str, Any]) → ErrorResponse[source]: Create an ErrorResponse instance from a dictionary.

Estadísticas Cambiarias

Data models for the BCRA Currency Exchange Statistics API. Provides classes for currency quotations, historical data, and response handling.

class src.bcra_connector.estadisticas_cambiarias.estadisticas_cambiarias.Divisa(codigo: str, denominacion: str)[source]

Bases: object

Represents a currency.

Parameters:

codigo – The currency code (ISO)
denominacion – The currency name

codigo: str

denominacion: str

classmethod from_dict(data: Dict[str, Any]) → Divisa[source]: Create a Divisa instance from a dictionary.

class src.bcra_connector.estadisticas_cambiarias.estadisticas_cambiarias.CotizacionDetalle(codigo_moneda: str, descripcion: str, tipo_pase: float, tipo_cotizacion: float)[source]

Bases: object

Represents details of a currency quotation.

Parameters:

codigo_moneda – The currency code
descripcion – The currency description
tipo_pase – The exchange rate
tipo_cotizacion – The quotation type

codigo_moneda: str

descripcion: str

tipo_pase: float

tipo_cotizacion: float

classmethod from_dict(data: Dict[str, Any]) → CotizacionDetalle[source]: Create a CotizacionDetalle instance from a dictionary.

class src.bcra_connector.estadisticas_cambiarias.estadisticas_cambiarias.CotizacionFecha(fecha: date | None, detalle: List[CotizacionDetalle])[source]

Bases: object

Represents currency quotations for a specific date.

Parameters:

fecha – The date of the quotations
detalle – List of quotation details

fecha: date | None

detalle: List[CotizacionDetalle]

classmethod from_dict(data: Dict[str, Any]) → CotizacionFecha[source]: Create a CotizacionFecha instance from a dictionary.

to_dict() → Dict[str, Any][source]: Convert the CotizacionFecha instance to a dictionary.

to_dataframe() → pd.DataFrame[source]

Convert the CotizacionFecha instance to a pandas DataFrame.

Returns a DataFrame with exchange rate information for each currency. Columns: fecha, codigoMoneda, descripcion, tipoPase, tipoCotizacion.

Requires pandas: pip install bcra-connector[pandas]

Returns:: DataFrame with exchange rate data.
Raises:: ImportError – If pandas is not installed.

class src.bcra_connector.estadisticas_cambiarias.estadisticas_cambiarias.Resultset(count: int, offset: int, limit: int)[source]

Bases: object

Represents metadata about the result set.

Parameters:

count – The number of results
offset – The offset of the results
limit – The limit of the results

count: int

offset: int

limit: int

classmethod from_dict(data: Dict[str, Any]) → Resultset[source]: Create a Resultset instance from a dictionary.

class src.bcra_connector.estadisticas_cambiarias.estadisticas_cambiarias.Metadata(resultset: Resultset)[source]

Bases: object

Represents metadata about the response.

Parameters:: resultset – The resultset metadata

resultset: Resultset

classmethod from_dict(data: Dict[str, Any]) → Metadata[source]: Create a Metadata instance from a dictionary.

class src.bcra_connector.estadisticas_cambiarias.estadisticas_cambiarias.DivisaResponse(status: int, results: List[Divisa])[source]

Bases: object

Represents the response for the Divisas endpoint.

Parameters:

status – The HTTP status code
results – List of Divisa objects

status: int

results: List[Divisa]

classmethod from_dict(data: Dict[str, Any]) → DivisaResponse[source]: Create a DivisaResponse instance from a dictionary.

class src.bcra_connector.estadisticas_cambiarias.estadisticas_cambiarias.CotizacionResponse(status: int, results: CotizacionFecha)[source]

Bases: object

Represents the response for the Cotizaciones endpoint.

Parameters:

status – The HTTP status code
results – CotizacionFecha object

status: int

results: CotizacionFecha

classmethod from_dict(data: Dict[str, Any]) → CotizacionResponse[source]: Create a CotizacionResponse instance from a dictionary.

class src.bcra_connector.estadisticas_cambiarias.estadisticas_cambiarias.CotizacionesResponse(status: int, metadata: Metadata, results: List[CotizacionFecha])[source]

Bases: object

Represents the response for the Cotizaciones/{codMoneda} endpoint.

Parameters:

status – The HTTP status code
metadata – Metadata about the response
results – List of CotizacionFecha objects

status: int

metadata: Metadata

results: List[CotizacionFecha]

classmethod from_dict(data: Dict[str, Any]) → CotizacionesResponse[source]: Create a CotizacionesResponse instance from a dictionary.

class src.bcra_connector.estadisticas_cambiarias.estadisticas_cambiarias.ErrorResponse(status: int, error_messages: List[str])[source]

Bases: object

Represents an error response from the API.

Parameters:

status – The HTTP status code
error_messages – List of error messages

status: int

error_messages: List[str]

classmethod from_dict(data: Dict[str, Any]) → ErrorResponse[source]: Create an ErrorResponse instance from a dictionary.

Rate Limiter

Rate limiting functionality for API requests.

class src.bcra_connector.rate_limiter.RateLimitConfig(calls: int, period: float, _burst: int | None = None)[source]

Bases: object

Configuration for rate limiting.

Parameters:

calls – Number of calls allowed per period
period – Time period in seconds
_burst – Maximum number of calls allowed in burst (internal)

calls: int

period: float

property burst: int: Burst limit is always an int after initialization.

class src.bcra_connector.rate_limiter.RateLimiter(config: RateLimitConfig)[source]

Bases: object

Rate limiter using token bucket algorithm with sliding window.

acquire() → float[source]

Acquire permission to make a request.

Returns:: Time spent waiting (in seconds)

reset() → None[source]: Reset the rate limiter state.

property current_usage: int: Get the current number of requests in the window.

property is_limited: bool: Check if rate limit is currently being enforced.

remaining_calls() → int[source]

Get the number of remaining calls allowed in the current window.

Based on the base rate limit (calls), not the burst limit.

Timeout Config

class src.bcra_connector.timeout_config.TimeoutConfig(connect: float = 3.05, read: float = 27.0)[source]

Bases: object

Configuration for request timeouts.

Parameters:

connect – How long to wait for the connection to be established (seconds)
read – How long to wait for the server to send data (seconds)

connect: float = 3.05

read: float = 27.0

property as_tuple: Tuple[float, float]

Get timeout configuration as a tuple.

Returns:: Tuple of (connect_timeout, read_timeout)

classmethod from_total(total: float) → TimeoutConfig[source]

Create a TimeoutConfig from a total timeout value.

Parameters:: total – Total timeout in seconds, will be split between connect and read
Returns:: TimeoutConfig instance
Raises:: ValueError – If total timeout is less than or equal to 0

classmethod default() → TimeoutConfig[source]

Get the default timeout configuration.

Returns:: TimeoutConfig instance with default values