Response Structure

Detailed documentation of API response formats and data types

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:

1. A message field indicating the operation status
2. 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:

1. Maps each database record to a key-value pair
2. Uses the source field as the dynamic key
3. Creates an object with value and date fields
4. 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.

Next Steps

Get Current Rates

Learn about the current rates endpoint

Error Handling

Understand API error responses