Response Structure

Overview

All Mi API BCV responses follow a consistent JSON structure. This page documents the standard response format, field types, and data structures returned by the API.

Standard Success Response

Every successful API response includes:

A message field indicating the operation status
One or more bank-specific objects containing rate data

{
  "message": "Consulta exitosa",
  "bcv": { ... },
  "banplus": { ... },
  "bnc": { ... },
  "bdv": { ... }
}

Response Fields

Message Field

message

string

required

Status message indicating the result of the API request.Possible values:

"Consulta exitosa" - Successful query with data returned
"Tasas no disponibles aún" - Rates not yet available for the current date
"No se encontraron datos" - No data found for the specified parameters
"Fecha inválida" - Invalid date format provided

Bank Objects

Each bank in the response is represented by a dynamic key matching its source identifier. The API supports four banks:

bcv

object

Exchange rate data from Banco Central de Venezuela.

Show properties

value

string

required

The exchange rate value stored as a decimal string.

Database Type: DECIMAL(64, 4)
Precision: Up to 64 total digits with 4 decimal places
Format: String representation (e.g., "45.2500")
Example: "45.2500", "44.9800", "46.1234"

The value is returned as a string to preserve precision and avoid floating-point errors in client applications.

date

string

required

The date the exchange rate was recorded.

Format: YYYY-MM-DD (ISO 8601 date format)
Database Type: DATE
Example: "2026-03-04", "2026-03-01"

Dates are normalized to YYYY-MM-DD format regardless of the input format used in the request.

banplus

object

Exchange rate data from Banplus Banco Universal.

Show properties

value

string

required

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

date

string

required

The date in YYYY-MM-DD format.

bnc

object

Exchange rate data from Banco Nacional de Crédito.

Show properties

value

string

required

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

date

string

required

The date in YYYY-MM-DD format.

bdv

object

Exchange rate data from Banco de Venezuela.

Show properties

value

string

required

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

date

string

required

The date in YYYY-MM-DD format.

Response Examples

Complete Response (All Banks)

Returned by GET / or GET /info/{date} without source filtering:

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

Filtered Response (Single Bank)

Returned by GET /info/{date}/{source} with a specific bank:

{
  "message": "Consulta exitosa",
  "bcv": {
    "value": "45.2500",
    "date": "2026-03-04"
  }
}

Partial Response

If only some banks have data for a specific date:

{
  "message": "Consulta exitosa",
  "bcv": {
    "value": "45.2500",
    "date": "2026-03-04"
  },
  "banplus": {
    "value": "45.3000",
    "date": "2026-03-04"
  }
}

The presence of bank objects in the response is dynamic. Not all banks may be present in every response, depending on data availability.

Data Source: Database Schema

The response data comes from the reference_records table with the following structure:

Column	Type	Description
`id`	BIGINT	Primary key (auto-increment)
`source`	VARCHAR	Bank identifier (bcv, banplus, bnc, bdv)
`value`	DECIMAL(64,4)	Exchange rate value
`date`	DATE	Date of the rate
`created_at`	TIMESTAMP	Record creation timestamp
`updated_at`	TIMESTAMP	Record last update timestamp

The database schema is defined in database/migrations/2026_01_28_203351_create_reference_records_table.php

Response Transformation

The API transforms database records into the response format using Laravel collections:

// From ScraperController.php:71-78
$formattedData = $records->mapWithKeys(function ($item) {
    return [
        $item->source => [
            'value' => $item->value,
            'date'  => $item->date
        ]
    ];
});

This transformation:

Maps each database record to a key-value pair
Uses the source field as the dynamic key
Creates an object with value and date fields
Omits id, created_at, and updated_at from the response

Dynamic Response Structure

The response structure is dynamic. Bank objects only appear if data exists for them in the database for the requested date.

For example:

Early in the morning, no banks may have data yet → 404 error
Some banks may update faster than others → partial response
By midday, all banks typically have data → complete response

Working with Response Data

JavaScript Example

const response = await fetch('https://your-domain.com/api/');
const data = await response.json();

// Check if request was successful
if (data.message === 'Consulta exitosa') {
  // Access specific bank rate
  const bcvRate = parseFloat(data.bcv.value);
  const bcvDate = data.bcv.date;
  
  console.log(`BCV Rate: ${bcvRate} on ${bcvDate}`);
  
  // Iterate over all available banks
  const banks = ['bcv', 'banplus', 'bnc', 'bdv'];
  banks.forEach(bank => {
    if (data[bank]) {
      console.log(`${bank}: ${data[bank].value}`);
    }
  });
}

Python Example

import requests
from decimal import Decimal

response = requests.get('https://your-domain.com/api/')
data = response.json()

if data['message'] == 'Consulta exitosa':
    # Convert string values to Decimal for precise calculations
    bcv_rate = Decimal(data['bcv']['value'])
    banplus_rate = Decimal(data['banplus']['value'])
    
    # Calculate average rate
    rates = [Decimal(bank['value']) for bank in data.values() 
             if isinstance(bank, dict) and 'value' in bank]
    average = sum(rates) / len(rates)
    
    print(f"Average rate: {average}")

PHP Example

$response = file_get_contents('https://your-domain.com/api/');
$data = json_decode($response, true);

if ($data['message'] === 'Consulta exitosa') {
    // Access bank rates
    foreach (['bcv', 'banplus', 'bnc', 'bdv'] as $bank) {
        if (isset($data[$bank])) {
            $value = $data[$bank]['value'];
            $date = $data[$bank]['date'];
            echo "$bank: $value ($date)\n";
        }
    }
}

Best Practices

Parse Values as Decimals

Always convert the value field to a proper decimal/numeric type in your application to avoid floating-point precision issues.

Check Message Field

Verify the message field equals "Consulta exitosa" before processing bank data.

Handle Missing Banks

Not all banks may be present in every response. Check for existence before accessing.

Cache Responses

The API caches for 1 hour. Consider implementing client-side caching to match this TTL.

Endpoints

Response Format

Overview

Standard Success Response

Response Fields

Message Field

Bank Objects

Response Examples

Complete Response (All Banks)

Filtered Response (Single Bank)

Partial Response

Data Source: Database Schema

Response Transformation

Dynamic Response Structure

Working with Response Data

JavaScript Example

Python Example

PHP Example

Best Practices

Parse Values as Decimals

Check Message Field

Handle Missing Banks

Cache Responses

Next Steps

Get Current Rates

Error Handling

Build docs developers (and LLMs) love

Endpoints

Response Format

Documentation Index

​Overview

​Standard Success Response

​Response Fields

​Message Field

​Bank Objects

​Response Examples

​Complete Response (All Banks)

​Filtered Response (Single Bank)

​Partial Response

​Data Source: Database Schema

​Response Transformation

​Dynamic Response Structure

​Working with Response Data

​JavaScript Example

​Python Example

​PHP Example

​Best Practices

Parse Values as Decimals

Check Message Field

Handle Missing Banks

Cache Responses

​Next Steps

Get Current Rates

Error Handling

Build docs developers (and LLMs) love

Overview

Standard Success Response

Response Fields

Message Field

Bank Objects

Response Examples

Complete Response (All Banks)

Filtered Response (Single Bank)

Partial Response

Data Source: Database Schema

Response Transformation

Dynamic Response Structure

Working with Response Data

JavaScript Example

Python Example

PHP Example

Best Practices

Next Steps