Newcastle Coal Price API: COAL_NEWCASTLE as JSON

Newcastle Coal Price API: COAL_NEWCASTLE as JSON

You need a reliable way to load the latest Newcastle coal price into your application, as JSON, and keep it current with minimal glue code. By the end of this article you’ll be able to fetch COAL_NEWCASTLE from Energy-API, understand the payload you get back, and ship production-safe handling for monthly updates, missing values, and caching.

What you’ll build

You will:

  • Call Energy-API’s coal/latest endpoint and read COAL_NEWCASTLE from JSON.
  • Persist the value safely, handling success=false and missing keys.
  • Work with a monthly data cadence (IMF via FRED), including caching and update scheduling.
  • Know where to register, get an API key, and move to production quickly.

Scope note: This article is about the Newcastle coal benchmark (COAL_NEWCASTLE). It is not about Brent or TTF. The dataset for Newcastle is monthly and sourced via IMF through FRED.

The endpoint for Newcastle coal

Energy-API exposes Newcastle coal on a single latest endpoint:

  • HTTP method: GET
  • Path: /api/v1/coal/latest
  • Symbol you will read from the response: COAL_NEWCASTLE

In practice, your integration will query the latest endpoint and read the COAL_NEWCASTLE field from the rates object in the response. If present, store it. If not present, keep your previous stored value and retry later.

Get started in minutes

  1. Register — the Starter plan is $19.99/mo and includes a 7‑day trial with 50 calls.
  2. Copy your api_key from the dashboard after signing in.
  3. Call GET /api/v1/coal/latest.
  4. Store rates.COAL_NEWCASTLE when present.

One-line request and live sample

Here is the official request for this integration and a live printout of the response. Note that the response print is dated 2026-07-01 (it is not “today”).

Request:

curl "https://energy-api.com/api/v1/coal/latest?api_key=YOUR_API_KEY"

Response (live Energy-API coal/latest, dated 2026-07-01):

{
  "success": true,
  "date": "2026-07-01",
  "base": "USD",
  "rates": {"COAL_NEWCASTLE": 140.396786},
  "dates": {"COAL_NEWCASTLE": "2026-07-01"},
  "currencies": {"COAL_NEWCASTLE": "USD"},
  "coverage_note": "COAL_ROTTERDAM (API 2) may be absent when the Nasdaq/ICE feed is unavailable; COAL_NEWCASTLE is sourced from IMF via FRED."
}

What the JSON means (and what to store)

The response contains a boolean success indicator and a rates object keyed by commodity codes. Your code should:

  • Check success. If success=false, do not overwrite previously stored values; log and retry.
  • Read rates.COAL_NEWCASTLE. If the key exists, store it atomically alongside the date you fetched it and the response’s date field if present.
  • If COAL_NEWCASTLE is missing, keep your last good value and schedule a retry.

Units and base currency: Coal benchmarks are typically quoted in currency per ton, but do not assume units or currency. Refer to the Documentation for the definitive unit and currency semantics for COAL_NEWCASTLE. Treat the numeric you store as the authoritative published value for that period.

Date and time: The live response shown above is printed with the date 2026-07-01. Store the response date field as given (do not coerce timezones), and keep a separate “ingested_at” timestamp from your system clock for observability.

Production-grade curl you can paste

Replace YOUR_API_KEY with your real key from the dashboard. The api_key is passed as a query parameter.

curl -sS "https://energy-api.com/api/v1/coal/latest?api_key=YOUR_API_KEY"

Python example: fetch and persist COAL_NEWCASTLE

This example calls the same endpoint, validates success, and reads rates.COAL_NEWCASTLE. It demonstrates safe handling for missing values and for success=false.

import os
import sys
import json
import time
from urllib.parse import urlencode
import urllib.request

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

def fetch_latest():
    url = f"{BASE_URL}?{urlencode({'api_key': API_KEY})}"
    req = urllib.request.Request(url, method="GET")
    with urllib.request.urlopen(req, timeout=15) as resp:
        body = resp.read().decode("utf-8")
        return json.loads(body)

def persist(value, as_of=None):
    # Replace with your database write. For demo, we print JSON to stdout.
    record = {"symbol": "COAL_NEWCASTLE", "value": value, "as_of": as_of, "ingested_at": int(time.time())}
    print(json.dumps(record))

def main():
    payload = fetch_latest()

    # 1) Check success flag
    if not isinstance(payload, dict) or not payload.get("success", False):
        print("Fetch failed or success=false; retaining previously stored value.", file=sys.stderr)
        sys.exit(1)

    # 2) Read the Newcastle rate if present
    rates = payload.get("rates", {}) or {}
    if "COAL_NEWCASTLE" not in rates or rates["COAL_NEWCASTLE"] is None:
        print("Missing rates.COAL_NEWCASTLE; not overwriting stored value.", file=sys.stderr)
        sys.exit(2)

    newcastle_value = rates["COAL_NEWCASTLE"]

    # 3) Optional: capture the response's date field if present
    # We don't assume a field name beyond what's returned; use .get() defensively.
    as_of = payload.get("date") or payload.get("as_of") or payload.get("timestamp")

    persist(newcastle_value, as_of=as_of)

if __name__ == "__main__":
    main()

Engineering details that will save you time

Monthly cadence (IMF via FRED)

  • COAL_NEWCASTLE updates on a monthly schedule. Do not poll this endpoint minutely expecting intraday changes.
  • Ideal fetch schedule: once per day with caching, plus a backfill run once a month when the new value posts.

Caching and cache busting

  • Since the series is monthly, cache the entire JSON for at least several hours to protect your quota and cut latency.
  • On your “new month” scheduler, bypass cache once to ingest the new print, then refresh the cache.

Handling success=false

  • If the API returns success=false, treat the payload as non-authoritative. Do not upsert “null” into your price table.
  • Retry with backoff. If repeated, alert but keep serving your last ingested value to downstream services.

Handling missing values

  • Check for the presence of rates.COAL_NEWCASTLE and that it is not null.
  • If missing, keep your prior stored value and log the full response for inspection.

Units and currency

  • Do not assume units or currency for COAL_NEWCASTLE. Use the authoritative definitions in the Documentation.
  • Store the raw numeric and defer any conversions until display time, with the unit clearly labeled.

Dates and timezones

  • The example response print is dated 2026-07-01. Treat the provided date as the period label for the monthly value.
  • Store both the response’s date field (period) and your ingestion timestamp. Avoid timezone arithmetic on the period label.

Pagination and throughput

  • /api/v1/coal/latest is a “latest” endpoint. There is no pagination to implement.
  • For batch systems, you can call it once and fan out the specific symbols you need from rates (e.g., COAL_NEWCASTLE). If you also track other coal series like COAL_ROTTERDAM, read that key from the same rates object when available. This page focuses on COAL_NEWCASTLE.

Idempotency and storage model

  • Use an upsert keyed by symbol and period date. Because the value is monthly, the key (COAL_NEWCASTLE, 2026‑07‑01) is stable for the month.
  • If your source-of-truth table requires unique rows, enforce a unique constraint on (symbol, period_date).

Monitoring

  • Alert if success=false persists beyond a few retries.
  • Alert if the period changes (new month) but rates.COAL_NEWCASTLE is missing for more than your tolerance window.

From sandbox to production

Energy-API’s Starter tier is designed to get you live quickly. You can try the endpoint with a 7‑day trial and 50 calls, then wire it into your pipeline once you’re satisfied with the payload and operational approach. The runbook looks like this:

  1. Register and copy your api_key.
  2. Call GET /api/v1/coal/latest from your job runner and log the full JSON until you are confident with parsing.
  3. Store rates.COAL_NEWCASTLE alongside the response’s date field (if present) and your ingested_at timestamp.
  4. Add checks for success=false and missing rates.COAL_NEWCASTLE; never overwrite good data with nulls.
  5. Schedule a monthly bypass-cache run to capture the new print (remember, Newcastle is monthly via IMF/FRED).

FAQ

Is this the right endpoint for Newcastle coal?
Yes. Read the COAL_NEWCASTLE value from GET /api/v1/coal/latest.

How often does COAL_NEWCASTLE update?
It’s a monthly series (IMF via FRED). Do not expect intraday or daily changes.

What do I do if success=false?
Treat the response as non-authoritative, preserve your last stored value, log and retry with backoff.

What if rates.COAL_NEWCASTLE is missing?
Skip writing, keep your prior value, and alert if the condition persists. Try again later.

Where do I find units and currency?
Refer to the official Documentation. Store the numeric as published and label units at display time.

Ready to load COAL_NEWCASTLE as JSON and move to production? Start your 7‑day trial now and get your key here: Register.

Ready to get started?

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

Get API Key