Home
Blog
Fetch High Grade Copper Oct 2025 (HGV25) Historical Prices for data visualization using this API

Fetch High Grade Copper Oct 2025 (HGV25) Historical Prices for data visualization using this API

Fetch High Grade Copper Oct 2025 (HGV25) Historical Prices for data visualization using this API

Building a copper price dashboard or backfilling a chart for High Grade Copper Oct 2025 (HGV25) historical prices? This guide shows how to fetch and visualize copper history using Metals-API’s historical and time-series data, with practical steps to approximate the HGV25 term structure via spot copper (XCU) and exchange-grade reference data. You’ll learn how to query, normalize, and cache data; interpret timestamps and units (troy ounce vs pound); and handle edge cases like weekends and market closures. We’ll also cover adjacent workflows with gold (XAU) to illustrate interchangeable techniques. If you’re new to the service, start with the high-level documentation and obtain a key here: Metals-API Website.

Goal: Visualize HGV25 historical behavior with robust API data

Concrete use case: You need a historical series to power a copper (HGV25) chart from, say, June through October 2025, suitable for dashboards, research, and model inputs. The challenge is that futures contracts like HGV25 (the October 2025 High Grade Copper on COMEX) roll and expire, whereas Metals-API provides a stable set of spot-like symbols (e.g., XCU) and historical exchange benchmarks via dedicated historical endpoints. The solution is to use Metals-API’s time-series and historical endpoints to retrieve daily copper (XCU) USD-denominated data and, when applicable, augment with historical LME references via the historical LME endpoint. You can then align/normalize your series to visualize HGV25 behavior and compute spreads, basis, or synthetic back-adjusted curves.

Important note on symbols

  • Metals-API offers metals like copper under the symbol XCU. See the complete and up-to-date list: Metals-API Supported Symbols.
  • Futures-venue-specific symbols like “HGV25” may not be directly available as an API symbol. Use XCU for copper spot-like rates, and consult the Supported Symbols directory to confirm exchange-specific listings you can retrieve through the Historical LME endpoint (which supports LME symbols back to 2008).
  • If you need exact COMEX futures settlement records, pair Metals-API copper (XCU) with your exchange data license and compute a spread/basis; Metals-API provides the high-quality spot-like reference, time series, and OHLC context you need for robust visualization and analytics.

How Metals-API fits copper visualization and analytics

Metals-API delivers real-time and historical prices for precious and industrial metals via a simple JSON REST interface. That means developers and quants can:

  • Pull daily historical rates and build reliable charts.
  • Compute volatility, returns, and spreads vs futures contracts or currency legs.
  • Visualize intraday behavior (when your plan includes intraday) and annotate charts with bid/ask spreads or OHLC candles.
  • Backfill dashboards consistently with the same unit base and timestamps.

For planning and parameter details, consult the official Metals-API Documentation and confirm symbol availability any time via the Supported Symbols catalog.

What you’ll implement

  • Fetch a daily time series of copper (XCU) rates across a date window leading into October 2025.
  • Normalize units and annotate charts with base currency and timestamps.
  • Optionally retrieve OHLC and Bid/Ask data for deeper visualization (candles, spreads).
  • Handle non-trading days, weekend gaps, and caching to stay efficient.

Understanding copper data in Metals-API

Metals-API responds with a base currency and rates keyed by symbol. By default, the base is USD, and “unit” indicates the metal unit (for metals, often “per troy ounce”). Copper (XCU) in the response is a “rate” that represents how many troy ounces of copper you can buy for one unit of the base currency (USD) unless you change the base. If you need currency conversions (e.g., to EUR) or conversions to or from metals, the Convert endpoint provides a dedicated workflow.

Key concepts you’ll use

  • Base currency: Typically USD. Change it when needed, but keep consistency across charts.
  • Units: Metals are often quoted “per troy ounce.” Copper futures are typically quoted “per pound.” You’ll likely convert ounces-to-pounds when overlaying with futures series. 1 troy ounce = 31.1034768 grams; 1 pound = 453.59237 grams.
  • Timestamps and timezone: The timestamp is a Unix epoch. Align to UTC for storage and API integration; convert in your charts as needed.
  • Market closures: Daily endpoints may skip weekends and holidays. Your charting code should account for missing days or fill-forward logic.

A quick tour of endpoints you’ll use together

To backfill HGV25-like visualizations, you’ll mainly use:

  • Time-Series Endpoint: Daily data between start and end dates.
  • Historical Rates Endpoint: Single-day snapshots for custom backfills.
  • OHLC: For open/high/low/close candles on a given date.
  • Bid/Ask: For spread-aware visualizations and microstructure overlays.
  • Historical LME Endpoint: For LME symbols dating back to 2008 (check exact LME symbol availability on the symbols list; if available to your plan, use this for exchange-grade historical benchmarks).

For a full capabilities overview, supported symbols, and plan-related features, visit the Metals-API Documentation and Metals-API Website. Get started now: sign up to get a free API key on the Metals-API Website.

Step-by-step: Fetch copper time series for a pre-HGV25 window

We’ll fetch copper (XCU) from 2025-06-01 through 2025-10-31 in USD for a daily chart. Then we’ll discuss transforming units for pound-denominated overlay and how to align to an HGV25 curve.

Sample curl request

curl "https://metals-api.com/api/timeseries?access_key=YOUR_API_KEY&base=USD&symbols=XCU&start_date=2025-06-01&end_date=2025-10-31"

Representative JSON response (time series)

{
"success": true,
"timeseries": true,
"start_date": "2026-09-08",
"end_date": "2026-09-15",
"base": "USD",
"rates": {
"2026-09-08": {
"XAU": 0.000485,
"XAG": 0.03825,
"XPT": 0.000915
},
"2026-09-10": {
"XAU": 0.000483,
"XAG": 0.0382,
"XPT": 0.000913
},
"2026-09-15": {
"XAU": 0.000482,
"XAG": 0.03815,
"XPT": 0.000912
}
},
"unit": "per troy ounce"
}

Explanation:

  • success: true indicates a valid response.
  • timeseries: true confirms you requested a date range.
  • start_date, end_date: The inclusive window Metals-API attempted to fulfill.
  • base: USD in this example. All rates in “rates” are relative to USD.
  • rates: A date-keyed dictionary. For your copper visualization, you’ll request symbols=XCU and read the XCU field per date.
  • unit: “per troy ounce” clarifies the unit. Metals rates are by troy ounce unless otherwise noted.

Note: The example above shows XAU/XAG/XPT for brevity. In your request with symbols=XCU, you’ll read rates[“YYYY-MM-DD”][“XCU”]. If you request multiple symbols, you’ll see multiple keys per date.

JavaScript example: fetch, normalize, and prepare for charting

async function fetchCopperSeries() {
const url = "https://metals-api.com/api/timeseries?access_key=YOUR_API_KEY&base=USD&symbols=XCU&start_date=2025-06-01&end_date=2025-10-31";
const res = await fetch(url);
if (!res.ok) throw new Error("Network error: " + res.status);
const json = await res.json();
if (!json.success) throw new Error("API error: " + JSON.stringify(json));

// Extract time series (USD per troy ounce equivalent rate form).
// Reminder: rates are "per USD" expressed as ounces per USD if base=USD.
// If you want USD per ounce, invert the value: priceUSDPerOunce = 1 / rate.
const data = [];
for (const [date, symbols] of Object.entries(json.rates)) {
const xcu = symbols["XCU"];
if (typeof xcu !== "number") continue;

// Convert from ounces per USD (rate) to USD per ounce:
const usdPerOunce = 1 / xcu;

// Optionally convert USD per ounce to USD per pound:
// 1 troy ounce = 31.1034768 grams; 1 pound = 453.59237 grams
// ounces per pound = 453.59237 / 31.1034768
const OUNCES_PER_POUND = 453.59237 / 31.1034768;
const usdPerPound = usdPerOunce * OUNCES_PER_POUND;

data.push({ date, usdPerOunce, usdPerPound });
}

// Sort by date to be safe
data.sort((a, b) => a.date.localeCompare(b.date));
return data;
}

fetchCopperSeries()
.then(series => {
console.log("Prepared copper series for charting:", series.slice(0, 5));
})
.catch(err => console.error(err));

What you’ll use in charts:

  • date: x-axis label.
  • usdPerOunce or usdPerPound: y-axis price. Choose pounds for futures overlay; ounces for consistency with other metals.

Interpreting “rates” for copper (XCU)

Metals-API returns metal rates by default as “per USD” in units of troy ounces. For example, a rate of 0.294118 for XCU means one USD buys 0.294118 troy ounces of copper. To plot USD per troy ounce, invert the rate: 1 / 0.294118 ≈ 3.4 USD/oz (illustrative math only; do not treat this as real pricing). Always check “unit” in the response to confirm unit semantics. If you change the base currency, adjust your inversion logic appropriately.

Aligning XCU with futures like HGV25

  • Futures (e.g., HGV25) are quoted per pound on exchange venues. Convert USD/oz to USD/lb for overlay or basis analysis.
  • Compute a spread: HGV25 settlement – XCU-derived USD/lb. This visualizes the term structure and tells you how the October contract diverges from spot over time.
  • When backfilling far into the past, consult the Supported Symbols to see if an LME copper symbol is available via the Historical LME endpoint under your plan. Those historical LME series date back to 2008 and can complement your XCU curve for more exchange-linked context.

Fetching single-day snapshots for copper and gold

For a point-in-time overlay (e.g., “where did spot copper and spot gold settle on a specific date?”), use the Historical Rates endpoint by appending a date.

Representative JSON response (historical rates)

{
"success": true,
"timestamp": 1789347146,
"base": "USD",
"date": "2026-09-14",
"rates": {
"XAU": 0.000485,
"XAG": 0.03825,
"XPT": 0.000915
},
"unit": "per troy ounce"
}

Use cases:

  • Backfill a missing daily record for a particular date.
  • Compute returns between two discrete dates.
  • Sanity-check time-series edges (start/end) with one-off snapshots.

Fields you’ll use:

  • date and timestamp: Use timestamp for internal precision (UTC), date for display.
  • rates: Access specific symbols (e.g., XCU for copper, XAU for gold).
  • unit: Ensure your unit math is correct in charts and analytics.

Enriching charts with OHLC and Bid/Ask

When your visualization calls for candlesticks or microstructure context, Metals-API provides OHLC and Bid/Ask endpoints. These are particularly useful for professional UI dashboards, risk monitoring, and trader workflows.

OHLC example

{
"success": true,
"timestamp": 1789433546,
"base": "USD",
"date": "2026-09-15",
"rates": {
"XAU": {
"open": 0.000485,
"high": 0.000487,
"low": 0.000481,
"close": 0.000482
},
"XAG": {
"open": 0.03825,
"high": 0.0383,
"low": 0.0381,
"close": 0.03815
},
"XPT": {
"open": 0.000915,
"high": 0.000918,
"low": 0.00091,
"close": 0.000912
}
},
"unit": "per troy ounce"
}

How to use:

  • For XCU charts, request copper when supported under your plan. The fields open/high/low/close map directly to candle plotting.
  • If you display USD per ounce, invert each value before rendering (1/value).
  • Add overlays: day range (high–low), close–close returns, and gap markers.

Bid/Ask example

{
"success": true,
"timestamp": 1789433546,
"base": "USD",
"date": "2026-09-15",
"rates": {
"XAU": {
"bid": 0.000481,
"ask": 0.000483,
"spread": 2.0e-6
},
"XAG": {
"bid": 0.0381,
"ask": 0.0382,
"spread": 0.0001
},
"XPT": {
"bid": 0.000911,
"ask": 0.000913,
"spread": 2.0e-6
}
},
"unit": "per troy ounce"
}

How to use in copper dashboards:

  • Plot bid, ask, and mid = (bid + ask)/2 to show spreads.
  • Alert on spread widening for liquidity-aware signals.
  • Convert to USD/lb if comparing to a futures tape or settlement feed.

Fluctuation analysis to highlight pre- and post-roll dynamics

As a contract like HGV25 approaches roll windows, spreads vs spot can change quickly. Use the Fluctuation endpoint to quantify day-to-day moves over configurable windows for copper and related metals. Integrate the figures into annotations and tooltips on your chart.

Fluctuation example

{
"success": true,
"fluctuation": true,
"start_date": "2026-09-08",
"end_date": "2026-09-15",
"base": "USD",
"rates": {
"XAU": {
"start_rate": 0.000485,
"end_rate": 0.000482,
"change": -3.0e-6,
"change_pct": -0.62
},
"XAG": {
"start_rate": 0.03825,
"end_rate": 0.03815,
"change": -0.0001,
"change_pct": -0.26
},
"XPT": {
"start_rate": 0.000915,
"end_rate": 0.000912,
"change": -3.0e-6,
"change_pct": -0.33
}
},
"unit": "per troy ounce"
}

Usage tips:

  • Use change_pct to colorize candles or annotate period-over-period moves.
  • For copper (XCU), invert start_rate and end_rate before computing USD-based spreads if you want change in USD/oz terms; or convert to USD/lb for COMEX-style overlays.

Latest endpoint to drive real-time charts and alerting

For live dashboards where you show the latest snapshot (e.g., to compare spot now vs most recent HGV25 movement on your futures feed), use the Latest endpoint. Depending on your plan, updates occur at different intervals.

Latest example

{
"success": true,
"timestamp": 1789433546,
"base": "USD",
"date": "2026-09-15",
"rates": {
"XAU": 0.000482,
"XAG": 0.03815,
"XPT": 0.000912,
"XPD": 0.000744,
"XCU": 0.294118,
"XAL": 0.434783,
"XNI": 0.142857,
"XZN": 0.344828
},
"unit": "per troy ounce"
}

Use cases:

  • Display copper spot next to a futures quote ladder (from your exchange-licensed feed).
  • Trigger alerts when XCU-derived USD/lb crosses a threshold relevant to your HGV25 basis model.

Currency conversion for multi-currency dashboards

Product catalogs, ERP systems, or cross-border dashboards may require EUR, GBP, JPY, etc. The Convert endpoint handles conversions between currencies and metals. For example, convert USD amounts to XAU or from USD to a fiat currency at the same timestamp context, then align with your XCU chart.

Convert example

{
"success": true,
"query": {
"from": "USD",
"to": "XAU",
"amount": 1000
},
"info": {
"timestamp": 1789433546,
"rate": 0.000482
},
"result": 0.482,
"unit": "troy ounces"
}

For copper dashboarding, consider:

  • Dynamic selector for base currency: e.g., convert USD-based copper to EUR-based price for localized charts.
  • Normalize endpoint timestamps for consistent cross-series alignment.

Historical LME endpoint for exchange-grade context

Metals-API provides a Historical LME endpoint with access to LME symbols dating back to 2008. Use this to complement XCU with exchange-grade historical context, subject to your plan and symbol availability. Because futures contracts like HGV25 are venue- and contract-specific, the LME endpoint is a powerful way to add depth to your visualization if you find the corresponding LME copper symbol available in the Supported Symbols. Confirm endpoint parameters and symbol support in the Metals-API Documentation.

Backfilling HGV25 charts: practical workflow

  1. Identify your target window (e.g., 2025-06-01 to 2025-10-31).
  2. Fetch copper (XCU) with the Time-Series endpoint over that window.
  3. Invert rates to USD/oz; convert USD/oz to USD/lb for futures overlay.
  4. Overlay exchange-settled HGV25 data from your futures source to compute basis and spreads. For additional context, add an LME series via the Historical LME endpoint if available.
  5. Enhance charts with OHLC candles for copper and, optionally, Bid/Ask to visualize spread dynamics.
  6. Handle gaps and weekends gracefully, using interpolation or step holds depending on your visualization rules.

Gold (XAU) reference: same techniques, different metal

Although this article centers on copper for HGV25 visualization, the exact same mechanics apply to gold (XAU). Here’s a quick mapping:

  • Replace XCU with XAU in your Time-Series or Historical calls.
  • Gold is also in “per troy ounce” by default; often users keep USD/oz for gold, so inversion alone is sufficient, with no pound conversion needed.
  • OHLC and Bid/Ask workflows mirror copper’s; candle charts and spread overlays (e.g., XAU vs XAG) are straightforward.

Data modeling details developers should not skip

Units and conversions

  • Troy ounce vs avoirdupois pound: Always convert when comparing to COMEX copper data. Use: pounds = ounces / (453.59237 / 31.1034768) when converting troy ounces to pounds.
  • Precision: Keep double precision floats and round for display only.
  • Currency: If you switch base from USD to EUR, document it in your chart legend and update inversion logic accordingly.

Timezones and timestamps

  • Store the raw timestamp fields in UTC from the API.
  • Convert to user-local time only for display in the UI.
  • When aligning with exchange settlements, explicitly state your session cutoff and conversion rules.

Handling weekends, holidays, and closures

  • Expect missing calendar dates in time series.
  • Provide interpolation options for continuous lines, or render gaps explicitly to highlight closures.
  • If computing returns, decide whether to use business-day returns only or calendar-spaced returns.

Caching, retries, and request efficiency

  • Cache time-series results in your backend by date window and symbols. Add ETag/Last-Modified headers to your CDN where applicable.
  • Stagger updates by feature: OHLC less frequently than Bid/Ask; Latest per UI refresh needs.
  • Implement exponential backoff on transient network failures and respect your plan’s request cadence.

Deep-dive: response field breakdown you’ll actually use

  • success: Boolean used for quick sanity-check before parsing.
  • timestamp: Unix epoch (UTC). Use it to align or deduplicate updates.
  • date: Human-readable date; matches day key in time series responses.
  • base: String like “USD.” If you change this, all your math downstream changes; be explicit.
  • rates: Object. For time-series, nested by date; for single-day and latest, flat or nested by symbol. For OHLC/Bid-Ask, it’s a nested object with open/high/low/close or bid/ask/spread.
  • unit: String. Commonly “per troy ounce” for metals. Do not ignore this; it determines your conversions.

Security and reliability best practices

  • Protect your API key. Store it server-side. Do not ship keys in public front-end code.
  • Implement network timeouts and verify HTTPS certificates by default.
  • Validate all user-supplied parameters (dates, symbols) before building requests to the API.
  • Log and monitor: Record request IDs, timestamps, and error payloads for debugging and SLA tracking.

Error handling and recovery strategies

  • Check success: If false, parse the error object and decide whether to retry, degrade gracefully, or notify.
  • Empty results: Handle missing symbols or out-of-range dates by showing “no data” states; for charts, keep axes consistent.
  • Partial windows: Time-series may return fewer days than requested due to closures; compute your expectations accordingly.

Performance considerations and scaling

  • Batch symbols: Fetch multiple symbols in one request when building multi-metal dashboards.
  • Use time-series for backfills; avoid one-day-at-a-time loops.
  • Cache in your data layer and set client-side refresh intervals aligned with your plan’s update cadence.
  • Precompute derived series (USD/lb, returns) server-side to reduce client CPU and bandwidth.

Validation checklist before going live

  • Confirm XCU availability on the Supported Symbols page.
  • Ensure your time window matches your visualization needs (e.g., pre-roll to post-expiry for HGV25).
  • Document whether your chart is USD/oz or USD/lb to avoid confusion.
  • Verify weekend/holiday handling; test tooltips on missing dates.
  • Set up synthetic spreads and annotate major roll dates.

Putting copper and gold together: cross-metal dashboards

It’s common to build a combined commodities dashboard: copper (XCU), gold (XAU), silver (XAG), and aluminum (XAL). With Metals-API you can request multiple symbols in the same time-series call to build synchronized multi-axis charts. Keep a single base currency and unit conversion strategy throughout to allow apples-to-apples comparisons. If you run quant screens, compute normalized returns, volatilities, and correlations on top of the synchronized datasets.

Practical gotchas developers encounter

  • Forgetting to invert: The default “per USD” representation requires inversion for “USD per ounce” charts.
  • Unit drift: Using USD/oz for copper next to USD/lb from futures creates misleading visuals. Always convert.
  • Silent weekends: A flat line may hide the fact there are no entries. Better: render distinct gaps or use hover tips to show missing data.
  • Mixing timestamps across endpoints: Align on timestamp or date. For derived series, resample to a consistent cadence.

Carrying lessons to gold (XAU) historical pricing

Everything above translates directly to gold. Use Time-Series for XAU, invert for USD/oz, and use OHLC for candle plots. If you’re building an executive dashboard, you can add copper vs gold ratios (XCU/XAU or USD/lb to USD/oz normalized) and annotate macro events. Many ERP and treasury teams start with gold historical pricing to anchor product price indexes, then expand to copper for manufacturing inputs.

End-to-end workflow summary

  1. Get your key from the Metals-API Website and scan the Metals-API Documentation.
  2. Confirm symbol availability on Metals-API Supported Symbols; plan your XCU queries and, if applicable, historical LME queries.
  3. Fetch copper time series for your HGV25 visualization window with the Time-Series endpoint.
  4. Invert rates and convert to USD/lb for futures overlay; add OHLC and Bid/Ask layers if needed.
  5. Cache responses, handle closures, and test performance under load.
  6. Ship with explicit unit/legend labels and robust error states.

Additional resources

Conclusion

To fetch High Grade Copper Oct 2025 (HGV25) historical prices for data visualization using this API, your best-practice path is to query copper (XCU) through Metals-API’s Time-Series and Historical endpoints, convert units to match futures conventions (USD/lb), and overlay with exchange futures where licensed to compute spreads and basis. Enrich your dashboards with OHLC/Bid-Ask to unlock advanced visuals and analytics, and leverage Historical LME when available under your plan to deepen exchange-grade context. By following the techniques here—careful unit management, timestamp alignment, caching, and robust error handling—you’ll build a reliable, scalable copper visualization pipeline. Start integrating now: visit the Metals-API Website and the Metals-API Documentation to get your free API key and implement your first query.

FAQ

  • Can I request HGV25 directly as a symbol? Check the Supported Symbols. If that specific futures contract code isn’t listed, use XCU for spot-like copper and, if eligible, leverage LME historical symbols via the Historical LME endpoint as contextual benchmarks. For exact COMEX contract settlements, combine Metals-API with your licensed exchange data.
  • What unit does copper (XCU) use? Metals-API commonly returns metals “per troy ounce” with base USD. Invert to get USD/oz; convert to USD/lb if comparing to COMEX futures.
  • How do I handle weekend gaps? Expect missing calendar dates. Show gaps or forward-fill depending on your business rules; annotate that markets were closed.
  • What timezone is the data in? Use the numeric timestamp (Unix epoch, UTC) for precise alignment and convert for display as needed.
  • Can I cache results? Yes. Cache time-series and historical responses by symbol and date window to reduce calls and improve performance.
  • How do I change the currency? Use the Convert endpoint to transform values to another fiat currency. Be consistent across your dashboard and document the base currency visibly.
  • Where can I see all available metals? Browse the live catalog at Metals-API Supported Symbols.
  • How do I get started? Visit Metals-API Website to create an account and obtain your API key. Then read the Metals-API Documentation for endpoint parameters and examples.

Ready to use Metals-API?

Try it now!

Search

Related Posts

Recent Posts