Newcastle Coal OHLC API

You're building a finance workflow that needs reliable, machine-readable Newcastle Coal prices and OHLC candles. By the end of this guide, you will fetch the latest Newcastle Coal quote and understand how to request OHLC data for production use, including authentication, units, base currency, field names, and practical considerations for caching and downstream analytics.

What you’ll build and why Newcastle Coal matters in finance

This walkthrough focuses on programmatically accessing the Newcastle Coal benchmark via Energy’s pricing endpoints. You’ll pull the latest daily quote for the COAL_NEWCASTLE symbol, parse the fields you actually need, and prepare for OHLC retrieval with the official OHLC endpoint. The target audience is quantitative analysts, risk engineers, and portfolio developers using coal benchmarks in valuation, hedging, or macro factor models.

Everything here stays within finance: time series inputs for factor models, fuel cost assumptions in project finance, mark-to-market pipelines, and dashboards that compare fuel markets. The examples are limited to Newcastle Coal and Energy’s endpoints that provide finance-grade price data.

Symbols, units, and authentication

Energy’s catalog includes a standardized symbol for the Newcastle benchmark:

• Symbol name: Newcastle Coal
• Symbol code: COAL_NEWCASTLE
• Unit: USD/MT

Requests use an api_key query parameter for authentication. In all examples below, replace ONLY the value with YOUR_API_KEY when moving to production. Do not include HTTP headers for auth; use the query parameter as shown.

Pricing plans: there is a Starter plan at $19.99/mo with a 7-day trial that includes 50 calls. Use the trial to validate your pipeline before scaling.

The latest price endpoint for Newcastle Coal

To retrieve the latest price snapshot for Newcastle Coal, call the latest endpoint. This is the main entry point for a point-in-time quote (one or more symbols per request). For COAL_NEWCASTLE specifically, use the curl below and parse the rates, dates, and currencies maps keyed by the same symbol code.

Copy-pasteable curl example

The following is the canonical request for a latest quote on COAL_NEWCASTLE:

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

Real latest response (field-accurate example)

This real response shows exactly which fields you’ll read for finance workflows. Copy the field names and the structure exactly as-is when parsing in your code.

{"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}

What you’ll actually use:

• rates.COAL_NEWCASTLE → the numeric price for Newcastle Coal (unit: USD per metric ton).
• dates.COAL_NEWCASTLE → the effective market date of that price. Treat it as the data’s observation date for your model’s daily bars.
• currencies.COAL_NEWCASTLE → confirms the quote currency for the symbol (USD here). This is essential when comparing to other instruments in mixed-currency portfolios.
• base → overall base currency for the response. It can be USD or MIXED depending on the request set; do not assume it will always be USD.

Finance-grade parsing details and pitfalls to avoid

When pulling energy benchmarks into finance models, small mistakes lead to basis drift. These are the gotchas to check once and keep in your pipeline forever:

• Unit checks: rates.COAL_NEWCASTLE is in USD/MT. Keep a single source of truth for units across your codebase and alert on any mismatch.
• Date handling: dates.COAL_NEWCASTLE is a trading/observation date string. Align your downstream resampling or index alignment (e.g., daily bars) to this date.
• Base currency: base may be USD or MIXED. If you request only COAL_NEWCASTLE, base may show USD. If you mix symbols with different quote currencies, base may be MIXED. Always use currencies.COAL_NEWCASTLE for currency-aware math.
• Cross-symbol requests: If you also need TTF_GAS or EUA_CO2 in the same call, do not pass base=USD. Respect the source currencies; convert after retrieval if needed using your own FX layer.
• Caching and retries: Cache read-only responses by date and symbol. If you see transient network failures, retry idempotently and fall back to a cached previous value with an audit log marker in your PnL pipeline.

One extra official call: OHLC endpoint for Newcastle Coal

For bar construction, backtesting, and charting, you will want daily or periodic candles rather than a single latest price. Energy provides an OHLC endpoint specifically for this purpose:

• HTTP method and path: GET /api/v1/ohlc
• Symbol: COAL_NEWCASTLE
• Auth: api_key query parameter

Use GET /api/v1/ohlc to retrieve open, high, low, and close data for COAL_NEWCASTLE. Consult the official docs for the exact query parameters (date ranges, intervals) and the response schema. Do not fabricate candles or fields—pull the OHLC series directly from this endpoint when you need structured bars for analytics or charts.

Reference for parameters and schema: Documentation.

Python example: latest Newcastle Coal price pipeline

The snippet below calls the latest endpoint for COAL_NEWCASTLE, validates the base and currency, and prints a normalized record suitable for writing into a warehouse table (symbol, date, price, currency, unit).

import os
import sys
import json
from urllib.parse import urlencode
from urllib.request import urlopen, Request

API_URL = "https://energy-api.com/api/v1/latest"
API_KEY = os.getenv("ENERGY_API_KEY", "YOUR_API_KEY")
SYMBOL = "COAL_NEWCASTLE"

def fetch_latest(symbol):
params = {
"symbols": symbol,
"api_key": API_KEY
}
url = f"{API_URL}?{urlencode(params)}"
req = Request(url, headers={"Accept": "application/json"})
with urlopen(req, timeout=10) as resp:
body = resp.read().decode("utf-8")
data = json.loads(body)
if not data.get("success", False):
raise RuntimeError("API returned success=false")
# Read the documented fields
rates = data.get("rates", {})
dates = data.get("dates", {})
currencies = data.get("currencies", {})
price = rates.get(symbol)
obs_date = dates.get(symbol)
currency = currencies.get(symbol)
base = data.get("base")
if price is None or obs_date is None or currency is None:
raise KeyError("Missing expected fields in response")
if base == "MIXED":
# For single-symbol requests this is unlikely, but handle it generically.
pass
# Unit is USD/MT for COAL_NEWCASTLE per catalog; store explicitly with the record
return {
"symbol": symbol,
"date": obs_date,
"price": float(price),
"currency": currency,
"unit": "USD/MT",
"base": base
}

if __name__ == "__main__":
try:
record = fetch_latest(SYMBOL)
print(json.dumps(record, separators=(",", ":"), sort_keys=True))
except Exception as e:
print(f"error: {e}", file=sys.stderr)
sys.exit(1)

Integration notes:

• Timeouts: 10 seconds is a practical default for server-side environments. Tune as needed.
• Idempotence: This is a read-only GET. You can safely retry on network issues.
• Warehousing: Store symbol, date, price, currency, base, and unit together to avoid ambiguity later.

Building a robust finance ingestion and OHLC workflow

Once you can fetch the latest price for COAL_NEWCASTLE, extend the ingestion job to run daily and persist both the latest snapshot and OHLC bars. The OHLC series is critical for analytics: rolling volatility, drawdowns, percentile bands, and backtests of hedging rules.

Implementation steps you can follow:

1. Start with a scheduler that fetches the latest quote once per day after your chosen fix time. Persist the price and the dates.COAL_NEWCASTLE field.
2. Add a second job that calls GET /api/v1/ohlc for COAL_NEWCASTLE and writes full candles into a history table with unique keys (symbol, date).
3. Build a sanity checker: if the latest close diverges materially from your rolling median, flag for review. Use currencies.COAL_NEWCASTLE and unit metadata in all validations.
4. For dashboards, display both the latest price and the previous n-day OHLC series. Always label currency and unit as USD/MT.

Handling mixed-currency responses correctly

Energy responses can have base equal to MIXED when you request multiple symbols with different currencies. If your portfolio aggregation needs a single currency, convert downstream using your FX rates. Do not request base=USD in the same call when you also need TTF_GAS or EUA_CO2—keep source currencies intact and convert consistently in your finance layer.

Practical strategy:

• Keep a currency column per row in your warehouse. For COAL_NEWCASTLE this will be USD.
• Use a deterministic FX source and a dated conversion table keyed by observation date for cross-asset comparability.
• Audit logs: for every conversion, record source currency, target currency, rate, and timestamp of conversion to make reconciliations simpler.

Production hygiene: dates, non-trading days, and caching

Energy data has a daily cadence for many benchmarks. Some days may have no new price (e.g., holidays or non-trading days). Handle repeats gracefully: if today’s date equals the previous business day’s date, don’t double-insert; upsert against the unique (symbol, date) key.

Caching tips:

• Key caches by URL and query string. Store the full JSON for reproducibility, not just the price.
• Use a short TTL for the latest endpoint during market hours and a long TTL after the day’s finalization window.
• If a request fails and your last cached observation is recent, serve the cached value with a flag in your app indicating fallback mode.

Error handling, data completeness, and monitoring

Monitor the fields you rely on. If rates.COAL_NEWCASTLE, dates.COAL_NEWCASTLE, or currencies.COAL_NEWCASTLE are missing, raise alerts and hold downstream calculations that depend on them. Because finance pipelines feed PnL and risk, it’s better to be late than wrong.

Logging suggestions:

• Record every API URL requested and the HTTP status code.
• Persist the success flag and base value for auditing.
• Hash the response body and store the hash alongside the observation to detect silent changes.

Testing your integration without risking production keys

Use the Starter trial (7 days / 50 calls) to ensure your code handles authentication, network timeouts, and the expected response schema. Point staging to the same endpoints with a separate environment variable for the key. For unit tests, mock the exact JSON structure shown above to avoid coupling to the network.

End-to-end example workflow

Here’s how a daily process might run in practice:

1. At a defined cutover time, call the latest endpoint for COAL_NEWCASTLE and parse rates, dates, currencies.
2. Upsert into warehouse: symbol=COAL_NEWCASTLE, date=dates.COAL_NEWCASTLE, price=rates.COAL_NEWCASTLE, currency=currencies.COAL_NEWCASTLE, unit=USD/MT, base=base.
3. Call GET /api/v1/ohlc for COAL_NEWCASTLE and upsert candle rows keyed by date.
4. Run validations comparing the latest close to the candle’s close for the same date. If mismatched, queue for review.
5. Generate downstream analytics: moving averages, daily returns, and VaR estimates for coal-linked exposures.

Quick reference: what to store for long-term analytics

• Symbol code: COAL_NEWCASTLE
• Unit: USD/MT
• Latest fields: date, price (from rates), currency (from currencies), base
• OHLC fields: open, high, low, close (from GET /api/v1/ohlc as documented)
• Lineage: API URL, request timestamp, response hash, and api_key alias (not the key itself)

Security and key management

Never hardcode api_key values. Use environment variables or a secrets manager. Pass the key via the api_key query parameter, as required. In logs, scrub sensitive values and keep only a redacted or reference version for support tickets.

Troubleshooting common issues

Authentication errors typically resolve by confirming the api_key is present and spelled correctly in the query string. If you receive unexpected currencies or base equals MIXED when you don’t expect it, make sure you requested only COAL_NEWCASTLE. If your numeric parsers throw errors, confirm you are reading rates.COAL_NEWCASTLE as a float and not as a string.

FAQ

Q: Which symbol should I use for Newcastle Coal?
A: Use COAL_NEWCASTLE. It is quoted in USD per metric ton (USD/MT).

Q: How do I authenticate my requests?
A: Include api_key as a query parameter. Use YOUR_API_KEY in examples, and store the real key securely in your environment or a secrets manager.

Q: Can I fetch OHLC candles for Newcastle Coal?
A: Yes. Use GET /api/v1/ohlc with COAL_NEWCASTLE. Refer to the Documentation for the exact parameters and response schema.

Q: What should I do if I also need TTF_GAS or EUA_CO2?
A: Do not pass base=USD in a mixed request. Retrieve symbols in their source currencies and handle currency conversion downstream.

Q: How do I handle non-trading days?
A: Check dates.COAL_NEWCASTLE. If the latest date has not advanced, keep a single row per (symbol, date) and avoid duplicates. Consider flagging unchanged days for visibility in analytics.

Get started

Create an account and make your first request in minutes. Use the trial to wire up latest and OHLC flows for COAL_NEWCASTLE, then promote to production once your checks pass. Register or explore the Documentation for parameter details and schema references.