Get Historical Rates

Query exchange rates by date with optional bank filtering

GET /info/{date}/{source?}

Get Historical Rates

cURL

curl --request GET \
  --url https://api.example.com/info/{date}/{source?}

200

{
  "message": "<string>",
  "[source]": {
    "value": "<string>",
    "date": "<string>"
  }
}

Endpoint

GET /info/{date}/{source?}

Retrieves exchange rates for a specific date, with optional filtering by bank source.

Path Parameters

date · string · required

The date to query rates for. Accepts various date formats that can be parsed by Carbon.

• Format: YYYY-MM-DD (recommended) or any Carbon-parseable format
• Validation: Must be a valid date that is not in the future
• Example: 2026-03-04, 2026-03-01, 2026-02-28

Future dates are not allowed. The date must be less than or equal to today.

source · string

Optional bank source identifier to filter results. If omitted, returns data for all available banks.

Valid values:

• bcv - Banco Central de Venezuela
• banplus - Banplus Banco Universal
• bnc - Banco Nacional de Crédito
• bdv - Banco de Venezuela

This parameter is case-sensitive and must match exactly.

Response

message · string · required

Status message indicating the result of the query. Returns "Consulta exitosa" on success.

[source] · object

Dynamic key based on bank source(s) in the response. When no source filter is applied, all available banks are included.

Show properties

value · string

The exchange rate value as a decimal string with up to 4 decimal places.

date · string

The date of the rate in YYYY-MM-DD format.

Caching

This endpoint caches results for 1 hour (3600 seconds) based on the queried date. The cache key format is: tasas_bancos_{date}

The cache stores all bank data for a given date. If you request a specific source filter, the filtering happens after retrieving from cache.

Example Requests

Get All Banks for a Specific Date

cURL

curl -X GET https://your-domain.com/api/info/2026-03-01 \
  -H "Accept: application/json"

Get Specific Bank for a Date

cURL

curl -X GET https://your-domain.com/api/info/2026-03-01/bcv \
  -H "Accept: application/json"

Example Responses

All Banks Response

200 - All Banks

{
  "message": "Consulta exitosa",
  "bcv": {
    "value": "45.2500",
    "date": "2026-03-01"
  },
  "banplus": {
    "value": "45.3000",
    "date": "2026-03-01"
  },
  "bnc": {
    "value": "45.2800",
    "date": "2026-03-01"
  },
  "bdv": {
    "value": "45.2600",
    "date": "2026-03-01"
  }
}

Error Responses

400 - Invalid Date

{
  "message": "Fecha inválida"
}

Error Cases

400 Bad Request - Returned when the date parameter is invalid or in the future. This is validated in ScraperController.php:49-51.

The date validation fails if:

• The date string cannot be parsed by Carbon
• The date is in the future (greater than today)

404 Not Found - Returned when no exchange rates exist for the requested date/source combination. This happens in ScraperController.php:66-68.

The “No data found” error occurs when:

• No banks have scraped data for the specified date
• The specified source doesn’t have data for that date (when filtering by bank)

Response Status Codes

Status Code	Description
200	Success - Returns exchange rates for the requested date/source
400	Bad Request - Invalid date format or future date
404	Not Found - No data available for the specified parameters

Implementation Details

The endpoint is implemented in app/Http/Controllers/Api/ScraperController.php:43-84 and follows this logic:

1. Date Validation (lines 48-51): Validates the date parameter using Carbon
2. Cache Lookup (lines 56-58): Checks for cached data with key tasas_bancos_{date}
3. Source Filtering (lines 61-63): Optionally filters by bank source if provided
4. Data Transformation (lines 71-78): Maps database records to response format
5. Response Building (lines 80-83): Returns JSON with message and bank data

Date Validation Logic

The validateDate() method (lines 87-103) performs the following checks:

// Attempts to parse the date with Carbon
$dt = Carbon::parse($date);
$date = $dt->toDateString(); // Normalizes to YYYY-MM-DD

// Ensures date is not in the future
return $dt->lessThanOrEqualTo(now());

Usage Examples

Query Multiple Dates

const dates = ['2026-03-01', '2026-03-02', '2026-03-03'];

const fetchRates = async (date) => {
  const response = await fetch(`https://your-domain.com/api/info/${date}`);
  return response.json();
};

const allRates = await Promise.all(dates.map(fetchRates));
console.log(allRates);

Compare Rates Across Banks

import requests

date = "2026-03-01"
banks = ["bcv", "banplus", "bnc", "bdv"]

for bank in banks:
    url = f"https://your-domain.com/api/info/{date}/{bank}"
    response = requests.get(url)
    data = response.json()
    
    if response.status_code == 200:
        rate = data[bank]['value']
        print(f"{bank.upper()}: {rate}")

Next Steps

Response Structure

Detailed documentation of response formats

Error Handling

Complete guide to API errors