Historical Newcastle Coal Prices

You need to chart, analyze, and alert on historical prices for Newcastle Coal without hand-entering numbers or scraping unreliable sources. By the end of this guide, you will be able to request a clean time series for Newcastle Coal (symbol COAL_NEWCASTLE), parse the response, verify the units and base, and plug the data into your analytics pipeline or dashboard.

What you will fetch: Newcastle Coal price series

This guide targets the Energy API’s timeseries endpoint for the symbol named in the title: Newcastle Coal (code COAL_NEWCASTLE). Values are quoted in USD per tonne. You will call a single HTTP GET endpoint with start, end, symbols, and your api_key and then read a compact response keyed by symbol.

The API returns:

• One base currency for the response (e.g., USD or EUR).
• A rates object where each symbol key has a numeric value for the date in scope.
• A dates object that maps each symbol to the effective date of the value.
• A currencies object that maps each symbol to its currency code.

Authentication uses an api_key query parameter (value must be YOUR_API_KEY in examples). The Starter plan is $19.99/mo with a 7-day trial that includes 50 calls. There is no MCP host to configure—use the endpoint shown below directly.

Endpoint and required parameters

Use this HTTP method and resource:

• Method: GET
• Path: /api/v1/timeseries
• Domain: https://energy-api.com

Required query parameters:

• start: Inclusive ISO date (YYYY-MM-DD) for the first day you want in the series.
• end: Inclusive ISO date (YYYY-MM-DD) for the last day you want in the series.
• symbols: Comma-separated list of symbols; use COAL_NEWCASTLE for Newcastle Coal.
• api_key: Your API key; use the literal YOUR_API_KEY only in examples.

Do not pass a base parameter alongside multiple symbols that have different native currencies (e.g., TTF_GAS or EUA_CO2). For this post, we stay with COAL_NEWCASTLE only, in its native USD/tonne.

cURL quickstart

Copy and paste this cURL to fetch a historical range for COAL_NEWCASTLE. Replace YOUR_API_KEY with your real key in your implementation.

curl -G "https://energy-api.com/api/v1/timeseries" --data-urlencode "start=2026-01-01" --data-urlencode "end=2026-03-31" --data-urlencode "symbols=COAL_NEWCASTLE" --data-urlencode "api_key=YOUR_API_KEY"

JSON response anatomy for Newcastle Coal

Below is a real response specific to COAL_NEWCASTLE. Copy the structure and field names exactly when you parse. Use the unit and base currency to label your charts and calculations correctly.

{"success":true,"date":"2026-07-01","base":"USD","rates":{"COAL_NEWCASTLE":140.396786},"dates":{"COAL_NEWCASTLE":"2026-07-01"},"currencies":{"COAL_NEWCASTLE":"USD"},"base_filter_note":null}

Field usage you will rely on:

• success: Boolean; verify true before using the payload.
• date: The canonical date for the returned observation.
• base: The base currency for the response; for COAL_NEWCASTLE this is USD.
• rates.COAL_NEWCASTLE: Numeric price for Newcastle Coal, in USD/tonne.
• dates.COAL_NEWCASTLE: The exact date associated with the rate (keep this as the x-axis key).
• currencies.COAL_NEWCASTLE: Currency code; use it to validate labeling and conversions.

Official sample response variant (field shape reference)

The following official sample shows the exact field names and structure you must handle. Note that the symbol and base currency differ from Newcastle Coal; you should still parse the same keys in your code.

{
"success": true,
"date": "2026-10-20",
"base": "EUR",
"rates": {
"OMIE_ES_DA": 195.5215
},
"dates": {
"OMIE_ES_DA": "2026-10-20"
},
"currencies": {
"OMIE_ES_DA": "EUR"
},
"base_filter_note": null
}

When you request COAL_NEWCASTLE, expect the same envelope and keys, but rates, dates, and currencies will be keyed by COAL_NEWCASTLE, and the base for that symbol is USD.

Python example: fetch, parse, and validate units

This Python sample calls the same endpoint, checks the base and currency, and safely reads the Newcastle Coal price and date for downstream processing. Replace YOUR_API_KEY in your own environment; do not hardcode real credentials in code shared publicly.

import requests
from urllib.parse import urlencode

BASE_URL = "https://energy-api.com/api/v1/timeseries"

params = {
"start": "2026-01-01",
"end": "2026-03-31",
"symbols": "COAL_NEWCASTLE",
"api_key": "YOUR_API_KEY"
}

resp = requests.get(BASE_URL, params=params, timeout=30)
resp.raise_for_status()
data = resp.json()

# Safety checks
if not data.get("success"):
raise RuntimeError("API reported success=false")

base = data.get("base")
if base != "USD":
# For Newcastle Coal we expect USD; if not, log and handle carefully
raise ValueError(f"Unexpected base currency: {base}")

rates = data.get("rates", {})
dates = data.get("dates", {})
currs = data.get("currencies", {})

# Extract the symbol-specific fields
symbol = "COAL_NEWCASTLE"
if symbol not in rates or symbol not in dates or symbol not in currs:
raise KeyError(f"Missing fields for {symbol}")

price = rates[symbol] # float
price_date = dates[symbol] # 'YYYY-MM-DD'
unit_currency = currs[symbol] # 'USD'

if unit_currency != "USD":
raise ValueError(f"Unexpected currency for {symbol}: {unit_currency}")

# Now you can store or chart: price is USD/tonne for price_date
print({
"symbol": symbol,
"date": price_date,
"price": price,
"unit": "USD/tonne",
"base": base
})

Choosing time windows and interpreting dates

For historical series, choose an ISO date window that covers your analysis horizon (e.g., start=2026-01-01 to end=2026-03-31). The API responds with a date per symbol in the dates object and a matching numeric value in rates. When you aggregate multiple days, store each returned date alongside its rate to avoid off-by-one errors.

Energy markets can have non-trading days or publication gaps. In these cases, some dates may not produce a new print; read the dates object for the effective date of the rate you received instead of assuming every calendar day will have a distinct value.

Caching and call budgeting

Cache responses keyed by the exact query string (start, end, symbols). For app-level caching, a short TTL (e.g., a few hours) reduces duplicate requests during dashboard refreshes. Since the trial offers 50 calls over 7 days, batching date ranges and avoiding repeated queries in hot paths preserves quota.

If you run scheduled batch jobs, align the job cadence with when you actually consume the values. For example, if you roll up daily closing values, fetch once per day at a consistent time and cache persistently for that date’s window.

Validation and consistency checks

Always verify:

• success is true before parsing.
• base is USD when working with COAL_NEWCASTLE.
• currencies.COAL_NEWCASTLE equals USD to match units of USD/tonne.
• dates.COAL_NEWCASTLE matches the observation you intend to chart or store.

If you later request multiple symbols, do not pass base=USD in the same query when you also need symbols like TTF_GAS or EUA_CO2. For this guide we keep a single symbol (COAL_NEWCASTLE) and default base handling, which simplifies validation.

Robust error handling and retries

Implement retries with exponential backoff for transient network failures only. Avoid retrying non-2xx responses indefinitely; inspect HTTP status and success field to decide whether to stop or adjust parameters. Log the full URL with query parameters (mask YOUR_API_KEY) to reproduce issues quickly.

On parsing errors, dump the response JSON for inspection and confirm that the expected keys exist for the requested symbol. Because field names are fixed, missing keys usually indicate a mismatch in the symbols parameter or a date window that yielded no observation.

Additional JSON examples for testing parsers

Use the following examples to unit test your JSON parser for exact keys and value types. The first and second blocks mirror the real and official samples; the third and fourth repeat the real example to help test idempotent parsing across identical payloads.

Real Newcastle Coal example (use-as-is)

{"success":true,"date":"2026-07-01","base":"USD","rates":{"COAL_NEWCASTLE":140.396786},"dates":{"COAL_NEWCASTLE":"2026-07-01"},"currencies":{"COAL_NEWCASTLE":"USD"},"base_filter_note":null}

Official sample structure (different symbol/base)

{
"success": true,
"date": "2026-10-20",
"base": "EUR",
"rates": {
"OMIE_ES_DA": 195.5215
},
"dates": {
"OMIE_ES_DA": "2026-10-20"
},
"currencies": {
"OMIE_ES_DA": "EUR"
},
"base_filter_note": null
}

Real Newcastle Coal example (duplicate for regression tests)

{"success":true,"date":"2026-07-01","base":"USD","rates":{"COAL_NEWCASTLE":140.396786},"dates":{"COAL_NEWCASTLE":"2026-07-01"},"currencies":{"COAL_NEWCASTLE":"USD"},"base_filter_note":null}

Real Newcastle Coal example (duplicate for cache validation)

{"success":true,"date":"2026-07-01","base":"USD","rates":{"COAL_NEWCASTLE":140.396786},"dates":{"COAL_NEWCASTLE":"2026-07-01"},"currencies":{"COAL_NEWCASTLE":"USD"},"base_filter_note":null}

Practical implementation details that save time

• Units: COAL_NEWCASTLE is in USD/tonne. Keep this consistent in UI and downstream metrics to avoid mixing with other units.
• Base currency: Use the base field to confirm which currency the numbers represent. For COAL_NEWCASTLE responses, expect USD.
• Timestamps: The API returns date values as YYYY-MM-DD. If your database uses datetime types, normalize to a date-only column or set time to 00:00:00 UTC.
• Idempotency: Repeating the same GET with identical parameters should return the same JSON for historical dates; leverage this for caching and reproducible analytics.
• Symbol isolation: When you only need Newcastle Coal, keep symbols to COAL_NEWCASTLE. Do not combine with gas or carbon symbols if you do not intend to reconcile cross-currency bases.

End-to-end workflow summary

1) Construct a GET request to /api/v1/timeseries with start, end, symbols=COAL_NEWCASTLE, and api_key. 2) Parse JSON and validate success, base=USD, currencies.COAL_NEWCASTLE=USD. 3) Read rates.COAL_NEWCASTLE and dates.COAL_NEWCASTLE and store both together. 4) Cache responses keyed by parameters to control API usage. 5) Feed the stored series into charts, alerts, or models annotated with USD/tonne.

Troubleshooting and edge cases

• Incorrect currency label: If your UI shows EUR for Newcastle Coal, you likely hardcoded a label. Read currencies.COAL_NEWCASTLE and base to label dynamically.
• Empty or unexpected rate: Confirm the symbol string is exactly COAL_NEWCASTLE and that your date range includes a published observation. Use the dates object to verify the effective date.
• Quota issues during trial: Batch your history pulls (wider date ranges in fewer calls) and cache the results. The 7-day trial includes 50 calls; plan accordingly.
• Data drift across services: Persist the full JSON per retrieval along with a hash of the response for auditability and to detect unintended transformation in your pipeline.

Where to go from here

If you plan to compare Newcastle Coal with other symbols later, keep each symbol in its own request until you design a consistent currency handling layer. When you do combine symbols, read currencies and base carefully and avoid forcing a base parameter if you also include symbols like TTF_GAS or EUA_CO2 that differ from USD.

FAQ

Q1: What is the exact symbol I should pass for Newcastle Coal?
A1: Use COAL_NEWCASTLE.

Q2: What are the units for Newcastle Coal in this API?
A2: USD per tonne. Validate with currencies.COAL_NEWCASTLE (USD) and label your charts as USD/tonne.

Q3: Which fields should I store to rebuild a chart later?
A3: Store dates.COAL_NEWCASTLE as the x-axis key and rates.COAL_NEWCASTLE as the value, along with base and currencies for audit and labeling.

Q4: Can I change the base currency in the request?
A4: This guide does not specify a base parameter. Do not add base=USD when combining with symbols like TTF_GAS or EUA_CO2. For COAL_NEWCASTLE-only requests, rely on the base and currencies returned.

Q5: How do I authenticate?
A5: Provide your key via the api_key query parameter. In examples, use YOUR_API_KEY as the placeholder.

Set up your key and start pulling Newcastle Coal history in minutes. Create your account on the 7-day trial and get your api_key here: Register. For parameter details and field references, see the Documentation.