bolt Energy API
Docs Symbols MCP Pricing Blog
Log in Get API Key

Rotterdam Coal Spot Price

Rotterdam Coal Spot Price

You need to pull the Rotterdam Coal spot price into a finance workflow, cache and display it reliably, and handle cases when the symbol is unavailable. By the end of this guide, you will be able to query the Energy API for Rotterdam Coal using PHP, interpret the response fields for finance use-cases (units, base currency, timestamps), handle error envelopes safely, and ship production-ready integrations.

What you are integrating: Rotterdam Coal for finance

Rotterdam Coal is a benchmark coal price used by risk, treasury, and analytics teams to value exposures, back-test strategies, and power dashboards. In the Energy API catalog, it appears as a symbol with fixed units and a deterministic currency so it can be joined with your broader price store.

Illustration: Rotterdam Coal Spot Price
  • Symbol name: Rotterdam Coal
  • Symbol code: COAL_ROTTERDAM
  • Unit: USD/tonne
  • Authentication: api_key query parameter (use YOUR_API_KEY in examples)
  • Plans: Starter $19.99/mo, trial 7 days / 50 calls

You will call a single endpoint, read a few well-defined fields, and wrap them with robust error handling suitable for finance systems.

Endpoint, parameters, and authentication

The latest prices are available via a GET to the latest endpoint. You pass symbols as a comma-separated list and authenticate with an api_key query parameter.

  • HTTP method: GET
  • Endpoint: https://energy-api.com/api/v1/latest
  • Required parameters:
    • symbols=COAL_ROTTERDAM
    • api_key=YOUR_API_KEY
  • Response fields to read:
    • rates.COAL_ROTTERDAM
    • dates.COAL_ROTTERDAM
    • currencies.COAL_ROTTERDAM
    • base may be MIXED

Important: Do not add a base=USD parameter when your portfolio call also needs TTF_GAS or EUA_CO2. For this single-symbol Rotterdam Coal call, you do not need any base parameter.

Refer to the official Documentation for broader catalog guidance and symbol discovery.

Quick verification with curl

Use this exact command to verify connectivity and request formatting. It targets the latest endpoint and requests the Rotterdam symbol.

curl -G "https://energy-api.com/api/v1/latest" --data-urlencode "symbols=COAL_ROTTERDAM" --data-urlencode "api_key=YOUR_API_KEY"

If the symbol is temporarily unavailable in the live catalog, the API responds with a clear error envelope (see the “Handling unavailability” section). When successful, you will read values under rates.COAL_ROTTERDAM, dates.COAL_ROTTERDAM, and currencies.COAL_ROTTERDAM.

Official sample response shape and field semantics

The following successful response is the official sample format for the latest endpoint. Note that the sample shows a different symbol (OMIE_ES_DA) but the structure, fields, and parsing approach are the same for COAL_ROTTERDAM.

{
"success": true,
"date": "2026-11-12",
"base": "EUR",
"rates": {
"OMIE_ES_DA": 116.1602
},
"dates": {
"OMIE_ES_DA": "2026-11-12"
},
"currencies": {
"OMIE_ES_DA": "EUR"
},
"base_filter_note": null,
"missing_symbols": null
}

Fields you will actually use for Rotterdam Coal:

  • success: Boolean flag for request outcome. Always check this first.
  • rates.COAL_ROTTERDAM: The latest Rotterdam Coal spot price value.
  • dates.COAL_ROTTERDAM: The valuation date for that rate.
  • currencies.COAL_ROTTERDAM: Expected to be USD for this symbol, paired with the “USD/tonne” unit.
  • base: May be MIXED for portfolio calls; do not rely on base when reading per-symbol currency fields.

Handling unavailability for COAL_ROTTERDAM (real error envelope)

When the live catalog does not include a requested symbol, the API returns a structured error. The following is the real response envelope for COAL_ROTTERDAM at the time of writing. Use it to implement defensive parsing and fallback behaviors.

{"success":false,"error":"Symbol COAL_ROTTERDAM is not currently available. See \/api\/v1\/symbols for the current catalog."}

What this means for your integration:

  • Do not attempt to read rates, dates, or currencies when success=false.
  • Log the error string for observability, and display a user-friendly message in your finance UI.
  • Optionally, call the symbols listing endpoint to confirm current availability before retrying.

PHP: production-grade GET for Rotterdam Coal with parsing and caching

This section shows a PHP implementation that queries the endpoint, validates the envelope, and extracts the Rotterdam Coal price fields for downstream finance systems. It also includes simple file-based caching so non-trading days or transient outages don’t break dashboards.

PHP request and parse

<?php
declare(strict_types=1);

function fetch_rotterdam_coal_latest(string $apiKey): array {
$endpoint = 'https://energy-api.com/api/v1/latest';
$params = http_build_query([
'symbols' => 'COAL_ROTTERDAM',
'api_key' => $apiKey,
]);

$url = $endpoint . '?' . $params;

$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 10,
]);

$raw = curl_exec($ch);
$curlErr = curl_error($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($raw === false) {
throw new RuntimeException('HTTP transport error: ' . $curlErr);
}

$json = json_decode($raw, true);
if (!is_array($json)) {
throw new RuntimeException('Malformed JSON (HTTP ' . $httpCode . '): ' . substr($raw, 0, 200));
}

if (isset($json['success']) && $json['success'] === false) {
// Mirrors the real error envelope for COAL_ROTTERDAM unavailability
$msg = isset($json['error']) ? $json['error'] : 'Unknown API error.';
throw new RuntimeException('Energy API error: ' . $msg);
}

// Expect per-symbol fields under rates, dates, currencies
$symbol = 'COAL_ROTTERDAM';
$rate = $json['rates'][$symbol] ?? null;
$date = $json['dates'][$symbol] ?? null;
$ccy = $json['currencies'][$symbol] ?? null;

if ($rate === null || $date === null || $ccy === null) {
throw new RuntimeException('Missing fields for ' . $symbol . ' in response.');
}

return [
'symbol' => $symbol,
'price' => $rate, // numeric, Unit: USD/tonne
'date' => $date, // ISO 8601 date string
'ccy' => $ccy, // expected "USD" for COAL_ROTTERDAM
'base' => $json['base'] ?? null, // may be MIXED for multi-symbol calls
];
}

// Simple local cache for resilience (e.g., 30 minutes)
function get_rotterdam_coal_with_cache(string $apiKey, int $ttlSeconds = 1800): array {
$cacheFile = sys_get_temp_dir() . '/coal_rotterdam_latest.json';
$now = time();

if (file_exists($cacheFile)) {
$stat = stat($cacheFile);
if ($stat && ($now - $stat['mtime']) < $ttlSeconds) {
$cached = json_decode(file_get_contents($cacheFile), true);
if (is_array($cached)) {
return $cached;
}
}
}

try {
$data = fetch_rotterdam_coal_latest('YOUR_API_KEY');
file_put_contents($cacheFile, json_encode($data, JSON_UNESCAPED_SLASHES));
return $data;
} catch (Throwable $e) {
// If API fails, serve stale cache if present
if (file_exists($cacheFile)) {
$cached = json_decode(file_get_contents($cacheFile), true);
if (is_array($cached)) {
// Optionally attach a warning
$cached['warning'] = 'Served from cache due to upstream error: ' . $e->getMessage();
return $cached;
}
}
// No cache, escalate
throw $e;
}
}

// Example usage
try {
$latest = get_rotterdam_coal_with_cache('YOUR_API_KEY');
// e.g., persist to DB or send to a dashboard
echo 'Rotterdam Coal: ' . $latest['price'] . ' ' . $latest['ccy'] . '/tonne on ' . $latest['date'] . PHP_EOL;
} catch (Throwable $e) {
error_log($e->getMessage());
http_response_code(502);
echo 'Upstream error. Try again later.';
}

Notes:

  • The unit is USD/tonne; do not apply your own unit conversion unless you explicitly need a different unit for reporting.
  • Base can be MIXED; for per-symbol finance logic, always prefer currencies.COAL_ROTTERDAM.
  • Cache conservatively during weekends and regional holidays when updates may be static.

JavaScript example: fetch and field extraction

If you prefer JavaScript for prototyping or serverless jobs, this snippet uses fetch, validates the envelope, and extracts the fields used in finance workflows.

async function getRotterdamCoal() {
const url = new URL('https://energy-api.com/api/v1/latest');
url.searchParams.set('symbols', 'COAL_ROTTERDAM');
url.searchParams.set('api_key', 'YOUR_API_KEY');

const res = await fetch(url.toString(), { method: 'GET' });
const body = await res.json();

if (body && body.success === false) {
// Realistic error envelope from the live call
// {"success":false,"error":"Symbol COAL_ROTTERDAM is not currently available. See /api/v1/symbols for the current catalog."}
throw new Error(body.error || 'Energy API error');
}

const symbol = 'COAL_ROTTERDAM';
const price = body.rates?.[symbol];
const date = body.dates?.[symbol];
const ccy = body.currencies?.[symbol];

if (price == null || !date || !ccy) {
throw new Error('Missing fields for ' + symbol);
}

return {
symbol,
price, // numeric
date, // ISO date
currency: ccy, // expected USD
base: body.base ?? null, // may be MIXED
};
}

getRotterdamCoal()
.then(data => {
console.log(`Rotterdam Coal: ${data.price} ${data.currency}/tonne on ${data.date}`);
})
.catch(err => {
console.error('Failed to load Rotterdam Coal:', err.message);
});

JSON response examples you should test against

Use these complete examples to validate your parser and error handling. Copy them into fixtures for unit tests. The blocks are provided verbatim from official samples and real observed envelopes.

Example A — Successful structure (official sample format)

{
"success": true,
"date": "2026-11-12",
"base": "EUR",
"rates": {
"OMIE_ES_DA": 116.1602
},
"dates": {
"OMIE_ES_DA": "2026-11-12"
},
"currencies": {
"OMIE_ES_DA": "EUR"
},
"base_filter_note": null,
"missing_symbols": null
}

Example B — Real COAL_ROTTERDAM unavailability

{"success":false,"error":"Symbol COAL_ROTTERDAM is not currently available. See \/api\/v1\/symbols for the current catalog."}

Example C — Retried COAL_ROTTERDAM still unavailable

{"success":false,"error":"Symbol COAL_ROTTERDAM is not currently available. See \/api\/v1\/symbols for the current catalog."}

How to use the fields in finance workflows

Once you have a successful envelope, use these mappings to integrate into your finance stack:

  • Quote value: rates.COAL_ROTTERDAM (decimal). Store as numeric(18,6) or similar, avoid float for auditability.
  • Valuation date: dates.COAL_ROTTERDAM (ISO date). Use as the price date in your position valuation snapshots.
  • Currency: currencies.COAL_ROTTERDAM (expected USD). This governs P&L translation rules if your ledger runs in a different currency.
  • Unit: USD/tonne. Ensure your exposure quantity is in tonnes; otherwise, convert the quantity before multiplying by the price.
  • Base: ignore for single-symbol accounting. For multi-symbol portfolios, treat base=MIXED as a hint to always read per-symbol currency.

Operational tips:

  • Non-trading days: Expect flat quotes across weekends/holidays; your job should still run and cache the last published value.
  • Cron cadence: For spot use-cases, hourly polling with 30–60 minute cache is usually sufficient.
  • Backfilling: If you snapshot daily, run the job after your chosen market close cut-off, then freeze the day’s value in your warehouse.

Error handling and resilience patterns

Implement these patterns to avoid breaking dashboards and downstream processes:

  • Envelope-first checks: If success=false, do not read any rate fields; surface the error message and serve cached data if available.
  • Symbol discovery: If you see the real error for COAL_ROTTERDAM, refresh your catalog view from /api/v1/symbols before retrying.
  • Timeouts and retries: Use short timeouts (e.g., 10s) and a single retry to avoid job pileups.
  • Stale cache guardrail: If upstream is down and cache is older than your policy, mark outputs as stale and alert.

Testing checklist

  • Success path: Parser extracts price, date, and currency for COAL_ROTTERDAM and persists them with unit USD/tonne.
  • Error path: Given the exact error JSON, the job logs and exits gracefully while serving a cached value.
  • MIXED base: Multi-symbol calls should always read currencies.COAL_ROTTERDAM for currency, not base.
  • Serialization: Ensure numeric precision preservation when storing quote values.

FAQ

What unit is the Rotterdam Coal quote in?
USD per tonne (USD/tonne). Align your quantity units before multiplying by price.

Which fields should I store for audits?
Store symbol code (COAL_ROTTERDAM), price (rates.COAL_ROTTERDAM), currency (currencies.COAL_ROTTERDAM), valuation date (dates.COAL_ROTTERDAM), and the full raw JSON for traceability.

How do I handle mixed base currency?
Ignore base for single-symbol finance uses. For portfolios, rely on currencies.COAL_ROTTERDAM to determine the per-symbol currency and perform conversions in your treasury layer.

Should I pass base=USD?
Do not pass base=USD when your call also includes TTF_GAS or EUA_CO2. For a single COAL_ROTTERDAM request, a base parameter is unnecessary.

What do I do if COAL_ROTTERDAM is unavailable?
Honor the error envelope, serve the last cached value, and consult the symbols catalog endpoint to confirm current availability before retrying.

Next step

Create your API key and start your 7-day, 50-call trial. Then plug the PHP function above into your nightly price loader and wire it to your warehouse. Register or study the Documentation to extend your integration.

Keywords
Rotterdam Coal spot price Energy API integration PHP finance workflow coal price data retrieval API response handling

Ready to get started?

Get your API key and start querying energy commodity prices in minutes.

Get API Key