Get Israeli New Sheqel (ILS) - N/A Historical Prices using this API (hourly time series)

Building an hourly time series of historical prices in Israeli New Sheqel (ILS) is a common requirement whether you are pricing jewelry parts in real time, powering alerts in a trading tool, feeding a P&L engine in a commodities desk, or backfilling a research notebook. In this guide, we focus on exactly that: how to retrieve ILS-denominated prices with Metals-API, stitch them into a reliable hourly time series, and productionize the workflow. We’ll cover API endpoints relevant to ILS pricing, show concrete curl and Python examples, explain the JSON you’ll receive, and detail best practices such as units, timestamps, caching, and handling non-trading hours. If you’re ready to implement, visit the Metals-API Website to get a free API key and follow along.

Why ILS-denominated historical prices matter for hourly time series

Developers and quants in fintech, commodities trading, manufacturing, and e-commerce often need prices denominated in their operational currency. For teams in Israel, that’s the Israeli New Sheqel (ILS). You might:

• Price a catalog of gold accessories in ILS, refreshing prices hourly to reflect market shifts.
• Backtest hedging strategies where metal exposure is funded or settled in ILS.
• Build dashboards for procurement teams showing ILS-denominated costs of inputs over time.
• Automate alerts in ILS when metals cross thresholds that impact margins.

Metals-API delivers a straightforward approach: request prices with ILS as the base so rates are expressed per troy ounce in ILS. Where intraday precision is needed, you can poll the latest endpoint on an hourly schedule and persist your own hourly series. For longer spans, use daily time series endpoints and OHLC data to provide daily structure and analytics that complement your hourly aggregates.

What you’ll build: an ILS hourly historical time series

We’ll walk through a practical design that consists of:

1. Fetching ILS-denominated rates for the metals you care about (e.g., XAU, XAG, etc.) using the Latest and Historical endpoints.
2. Constructing a durable hourly time series by polling on a cron schedule and persisting records with timestamps.
3. Supplementing with daily Time-series and OHLC endpoints for clean day-level aggregates and analytics.
4. Handling units, timestamps, market closures, and missing data responsibly.

To explore other symbols or confirm ILS support, consult the Metals-API Supported Symbols. For the full parameter set and coverage, keep the Metals-API Documentation handy.

Quick orientation: precision, units, base currency, and timestamps

• Units: Metals-API returns metals values “per troy ounce.” If you must quote grams or kilograms, convert accordingly (1 troy ounce ≈ 31.1034768 grams).
• Base currency: Responses include a base field. Set it to ILS to request prices in Israeli New Sheqel. If you don’t specify, the default is USD.
• Timestamps & timezones: Responses include a Unix timestamp (seconds) and an ISO date. Treat timestamps as UTC. Always store the raw timestamp and normalize timezones in your app.
• Market hours: Metals trade continuously across venues but liquidity varies by region and session. Don’t assume equal quality across all hours. Expect quieter weekends and holidays.

Endpoints used in this guide

We will focus on three endpoints relevant to building an ILS hourly time series:

• Latest Rates endpoint: for hourly polling and near-real-time refresh.
• Historical Rates endpoint: for point-in-time ILS-denominated prices on a specific date.
• Time-series endpoint: for daily historical spans to backfill or reconcile long periods.

We will also consult the OHLC endpoint for day-level analytics (open, high, low, close) that complement hourly storage. For additional endpoints such as bid/ask or fluctuation, see the official Metals-API Documentation.

Authentication and request basics

Every call requires an API key via the access_key parameter. Keep your key secret—store it in a secure vault or environment variable and never commit it to source control. Use HTTPS only.

• Base URL: Refer to the documentation for the production HTTPS base endpoint.
• Query parameters used here:
  • access_key: your API key
  • base: set to ILS to get ILS-denominated values
  • symbols: a comma-separated list of metal symbols (e.g., XAU,XAG) when needed
  • date, start_date, end_date: for historical/time-series calls

Complete curl request: latest ILS-denominated prices for selected metals

This request retrieves the latest rates with ILS as the base. Use it for an hourly cron job to build your intraday time series.

curl -s "https://metals-api.com/api/latest?access_key=YOUR_ACCESS_KEY&base=ILS&symbols=XAU,XAG,XPT"

Example JSON response (structure and field names you will receive):

{
"success": true,
"timestamp": 1789863123,
"base": "ILS",
"date": "2026-09-20",
"rates": {
"XAU": 0.000482,
"XAG": 0.03815,
"XPT": 0.000912
},
"unit": "per troy ounce"
}

How to use these fields

• success: Boolean; always check it before trusting data.
• timestamp: Unix epoch in seconds; store it as your primary key for time series indexes.
• base: "ILS" tells you all rates are per ILS.
• date: ISO date useful for day-level grouping; always rely on timestamp for exact time.
• rates: Object mapping symbols to numeric values. For ILS base, the numeric represents “troy ounces per ILS” (i.e., how much metal 1 ILS buys). If you prefer price per ounce in ILS, invert it: ILS_per_oz = 1 / rate.
• unit: Always “per troy ounce” for metals symbols.

Converting to “ILS per ounce”

Metals-API expresses metal in terms of the base currency. Typical financial displays show price per ounce in the base currency. If base=ILS, then price_per_oz_ils = 1 / rates[metal]. For example, if XAU = 0.000482 ounces per ILS, then 1 / 0.000482 ≈ 2074.27 ILS per ounce. Apply this consistently in your data pipeline.

Backfilling a single past day in ILS: Historical Rates endpoint

When you need a point-in-time ILS price for a past date (e.g., to correct a missing hour or snapshot P&L as of month-end), use the Historical Rates endpoint by appending the date.

curl -s "https://metals-api.com/api/2026-09-19?access_key=YOUR_ACCESS_KEY&base=ILS&symbols=XAU,XAG,XPT"

Example JSON response:

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

Field-by-field and usage considerations

• timestamp and date: The timestamp resolves the specific moment the historical snapshot represents. Always persist it even when you primarily think in dates.
• rates: As with latest, invert the rate for ILS per ounce if needed.
• Reconciliation: Compare the historical day’s latest with your hourly series to detect gaps and trigger patching.

Daily ILS spans: Time-series endpoint

For longer periods, request the daily time series with base=ILS. This is perfect for backfills or plotting a historical chart where daily granularity is sufficient. You can also use it to reconcile your hourly series: for each date, your hourly range should remain within the OHLC or encompass similar variation.

curl -s "https://metals-api.com/api/timeseries?access_key=YOUR_ACCESS_KEY&base=ILS&start_date=2026-09-13&end_date=2026-09-20&symbols=XAU,XAG,XPT"

Example JSON response:

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

Interpreting and using time series data

• rates: Object keyed by date; each contains symbol-to-rate mappings for that date.
• Sparse dates: You may not see entries for all dates if the market is closed or the plan’s date range limit filters results. Handle missing keys appropriately.
• Backfilling: Use the daily values to populate chart baselines. For a hybrid intraday + daily approach, align each hourly group with the corresponding daily entry.

Day-level analytics in ILS: OHLC endpoint

To provide analytics in ILS at the day level—such as percent change or volatility proxies—use OHLC with base=ILS. Even if your primary goal is hourly storage, daily OHLC improves context (e.g., ensuring your hourly extremes do not exceed the daily high/low absent large after-hours moves).

curl -s "https://metals-api.com/api/open-high-low-close/2026-09-20?access_key=YOUR_ACCESS_KEY&base=ILS&symbols=XAU,XAG,XPT"

Example JSON response:

{
"success": true,
"timestamp": 1789863123,
"base": "ILS",
"date": "2026-09-20",
"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"
}

Practical uses of OHLC

• Quality control: Ensure your stored hourly highs and lows sit within or close to OHLC day-level bounds.
• Analytics: Compute day-over-day changes using close vs. prior close in ILS.
• Displays: Many charts and business dashboards expect OHLC arrays; you can serve these in ILS directly.

ILS hourly time series pattern: poll latest and persist

Since an “hourly” historical series implies intraday points, the standard implementation is to poll the Latest endpoint on a timer (cron, serverless schedule, or job runner). Store each response with its timestamp and base=ILS. Over time, you will accumulate a robust hourly series suitable for analytics, monitoring, and pricing.

Reference Python snippet for hourly polling and persistence

Here is an example that fetches XAU and XAG in ILS and stores both the raw rates and inverted “ILS per ounce” values. Replace YOUR_ACCESS_KEY with your key from the Metals-API Website.

import os
import time
import json
import urllib.request

ACCESS_KEY = os.getenv("METALS_API_KEY", "YOUR_ACCESS_KEY")
URL = "https://metals-api.com/api/latest?access_key={}&base=ILS&symbols=XAU,XAG"

def fetch_latest_ils():
with urllib.request.urlopen(URL.format(ACCESS_KEY)) as resp:
data = json.loads(resp.read().decode())
if not data.get("success", False):
raise RuntimeError(f"API error: {data}")
return data

def transform(data):
# Convert ounces-per-ILS to ILS-per-ounce (more intuitive for display)
rates = data["rates"]
ils_per_oz = { sym: (1.0 / rate) for sym, rate in rates.items() if rate > 0 }
return {
"timestamp": data["timestamp"],
"date": data["date"],
"base": data["base"],
"ils_per_oz": ils_per_oz,
"raw": rates,
"unit": data["unit"]
}

def store(record):
# Store to local file for demonstration; in production use DB or object storage
ts = record["timestamp"]
with open(f"ils_hourly_{ts}.json", "w") as f:
json.dump(record, f)

if __name__ == "__main__":
payload = fetch_latest_ils()
rec = transform(payload)
store(rec)
print(f"Stored hourly ILS snapshot at {rec['timestamp']} with symbols: {list(rec['raw'].keys())}")

Notes:

• Use your infra’s scheduler (e.g., cron @hourly, Cloud Scheduler, EventBridge) to invoke this on your plan’s update frequency.
• Add jitter (random delay) to avoid synchronized spikes.
• In production, insert into a durable store with indexes on timestamp and symbol.

Example: building an ILS chart with daily baseline and hourly overlays

Combining daily time series and your hourly snapshots yields a robust chart:

1. Fetch daily ILS time series for the last 90 days using the Time-series endpoint.
2. Overlay hourly ILS-per-oz from your store for the last 72 hours to show intraday dynamics.
3. Where a daily data point is missing (weekends, holidays), ensure your chart gracefully interpolates or marks gaps.

Additional sample responses for implementation and testing

Latest ILS with only one symbol (XAU) for focused workloads

{
"success": true,
"timestamp": 1789863123,
"base": "ILS",
"date": "2026-09-20",
"rates": {
"XAU": 0.000482
},
"unit": "per troy ounce"
}

Historical ILS with off-market date (expect valid data but unchanged across quiet periods)

{
"success": true,
"timestamp": 1789680000,
"base": "ILS",
"date": "2026-09-18",
"rates": {
"XAU": 0.000485,
"XAG": 0.03825
},
"unit": "per troy ounce"
}

Time-series with sparse days (weekend gaps)

{
"success": true,
"timeseries": true,
"start_date": "2026-09-16",
"end_date": "2026-09-20",
"base": "ILS",
"rates": {
"2026-09-16": { "XAU": 0.000484, "XAG": 0.03822 },
"2026-09-17": { "XAU": 0.000485, "XAG": 0.03825 },
"2026-09-20": { "XAU": 0.000482, "XAG": 0.03815 }
},
"unit": "per troy ounce"
}

OHLC ILS response emphasizing daily extremes

{
"success": true,
"timestamp": 1789863123,
"base": "ILS",
"date": "2026-09-20",
"rates": {
"XAU": {
"open": 0.000484,
"high": 0.000488,
"low": 0.000481,
"close": 0.000482
}
},
"unit": "per troy ounce"
}

Parameter guidance and valid inputs

Below are the core parameters we used in our ILS workflow. For the full catalog of parameters across all endpoints and plans, refer to the Metals-API Documentation.

• access_key: Required on all endpoints. Obtain yours from the Metals-API Website.
• base: Set to ILS to receive ILS-denominated rates. If omitted, the base defaults to USD.
• symbols: Comma-separated list of metals (e.g., XAU,XAG). Check the latest inventory on the Supported Symbols list.
• date: Historical endpoint path uses YYYY-MM-DD appended to the URL.
• start_date, end_date: Time-series endpoint parameters for daily spans.

Data modeling: ounces-per-ILS vs ILS-per-ounce

Because the API expresses values relative to the base, think clearly about operations on the rate:

• If base = ILS, then rates["XAU"] = ounces per ILS. Multiplying: ILS * rate yields ounces. To price an ounce in ILS, invert.
• Keep both the raw rate and the inverted price in storage for flexibility. Store at least 8-10 decimal places for intermediate steps to avoid rounding artifacts in analytics.
• If you later change base (e.g., to USD), your schema should still support clear transforms and labeling to prevent unit confusion.

Rational caching and throughput management

Polling latest every minute is rarely necessary for an “hourly” series. Instead:

• Align request cadence with your plan’s update frequency and your business requirement. For example, if updates are every 10 minutes, a 10- or 15-minute cadence is adequate and can be aggregated to hourly bars.
• Implement ETag or basic timestamp guards in your collector to avoid re-storing identical data within a narrow time window.
• Use an in-memory cache (Redis, Memcached) in downstream services to serve repeated read traffic from the same hour.
• Batch workloads: run one poller that persists data, then let internal services consume the store instead of each service calling the API directly.

Handling weekends, holidays, and partial sessions

Metal markets have 24x5 patterns with regional liquidity and periodic closures:

• You may encounter flat rates over weekends or minimal changes during thin liquidity periods.
• Time-series daily data may be sparse on certain dates. Your UI should handle missing keys by either skipping rendering or marking gaps.
• When computing volatility or percentage changes, normalize by trading day counts rather than calendar days to avoid overstating inactivity.

Error handling and recovery strategies

Robust systems anticipate network hiccups, quota limits, and malformed inputs:

• Always check success == true. On false, log the full body and your request ID for correlation.
• Retry transient failures with exponential backoff (e.g., 1s, 2s, 4s, 8s, capped), and add jitter.
• If a scheduled fetch fails, fill the gap later with the Historical endpoint for the missing day(s) and continue hourly polling forward.
• Validate fields: Ensure rates is an object, numeric values are positive, and unit == "per troy ounce" when you expect metals.

Security best practices

• Key management: Store access_key in a secrets manager or environment variable. Rotate keys periodically.
• Outbound controls: Restrict egress only to Metals-API domains and require TLS.
• Least privilege: If your environment supports scoped secrets per service, avoid sharing one key across unrelated apps.
• Observability: Log request timestamps, endpoint, and response hash (not payload) for audit without leaking sensitive data.

Performance and scaling

• Producer-consumer split: Run a single collector service to fetch ILS data and push to a message bus or database. Consumers subscribe for their needs (alerts, pricing, charts).
• Storage: Use a columnar store or time-series database (TSDB) when aggregating across years. Partition by symbol and month.
• Precompute: For dashboards, precompute inverted prices (ILS per ounce) and 1h/4h/day aggregates to minimize query latency.
• Compression: Store JSON payloads with gzip or use a compact row schema; track size vs. retrieval speed trade-offs.

Data analytics in ILS: practical KPIs

• Hourly return in ILS: r_t = (P_t - P_{t-1}) / P_{t-1}, where P is ILS per ounce.
• Rolling volatility: standard deviation of hourly returns over N hours, annualized if needed (remember to use trading hours count).
• Cost overlays: multiply ILS-per-gram by gram-weight of SKUs to yield current BOM cost curves.

Troubleshooting common pitfalls

• Misinterpreting units: If your price looks “too small,” you’re probably using ounces-per-ILS where you expect ILS-per-ounce. Invert the rate.
• Timezone drift: If your chart labels don’t align, confirm you’re converting timestamps (UTC) to local time zones consistently on the frontend.
• Weekend artifacts: Flat lines across weekends are normal; do not treat as data outages.
• Duplicate writes: Guard your writer by deduping on timestamp+symbol and hashing payloads to prevent storage bloat.

Validation checklist before going to production

• Base currency correctness: Verify base=ILS is applied consistently across endpoints.
• Precision: Ensure sufficient decimal places for rates and inverted prices.
• Monitoring: Alert on fetch failures, anomalous zero/negative rates, or missing fields.
• Backfill pipeline: Scripted procedures to fill gaps with Historical and Time-series endpoints.

End-to-end example flow

1. Hourly fetch: Call Latest with base=ILS and symbols=XAU,XAG.
2. Transform: Compute ILS-per-ounce by inversion; persist both raw and derived.
3. Daily baseline: Nightly, call Time-series for the last window (e.g., last 14 days) to reconcile daily aggregates.
4. Analytics: Compute hourly returns and day-over-day changes using OHLC close.
5. UI: Serve charts and price tiles in ILS with clear unit labels (“ILS/oz”).

Digital transformation themes with ILS-denominated metals

The shift to API-driven pricing in local currencies like ILS exemplifies broader trends:

• Smart integration: Embedding live ILS metals prices into ERP and e-commerce reduces manual updates and slippage.
• Data-driven insights: Hourly ILS series enables granular margin analytics, hedging decisions, and forecast accuracy improvements.
• Future-ready tooling: With streaming architectures, you can evolve from hourly to sub-hour windows as needs or plans change.

Governance, provenance, and audit

• Provenance: Store the original JSON response (or a hash) with your transformed records for traceability.
• Schema versioning: If you enrich records (e.g., add ils_per_oz), maintain a version to detect and migrate changes cleanly.
• Reproducibility: Given a timestamp, your system should re-derive the display price exactly; keep conversion constants (troy ounce to grams) in a centralized library.

Comparing symbols and base currency usage

Aspect	ILS as base	USD as base (contrast)
Rates meaning	Ounces per ILS; invert for ILS per ounce	Ounces per USD; invert for USD per ounce
Display to Israeli users	Native ILS; no extra FX step	Requires FX conversion to ILS downstream
Storage	Store raw and inverted for fast UI	Often store USD; convert on the fly

Security and privacy in distributed teams

• Rotate keys on contributor turnover; enforce clean handoffs via a secrets manager.
• Do not expose the access_key in client-side code; route requests through your backend.
• Rate-limit internal consumers to prevent accidental loops that exhaust quotas.

Operational dashboards and SLOs

• Uptime SLO: “Data freshness within 15 minutes for 99.9% of hours” is a practical target for hourly pricing.
• Alerting: Alert when latest timestamp is older than 2x your intended cadence.
• Cost guardrails: Monitor API call counts and set budgets; cache and batch to contain usage.

Advanced techniques

• Composite indices in ILS: Build a weighted metals basket and track it hourly for internal KPIs.
• Regime detection: Use hourly ILS returns to detect volatility regimes that trigger hedging rules.
• Anomaly scoring: Flag outliers where hourly ILS price deviates beyond daily OHLC bounds without news catalysts.

Testing strategies

• Contract tests: Validate JSON fields and types across Latest, Historical, Time-series, and OHLC.
• Replay tests: Record known-good responses and replay them to test transforms (inversion, grams conversion) deterministically.
• Performance tests: Simulate backfills over long ranges and profile storage/query times.

Change management

• Feature flags: Roll out ILS base usage behind a flag; fallback to USD per ounce if needed.
• Observability: Track conversion errors and unit mismatches during rollout.
• Documentation: Embed unit notes (“per troy ounce”) in UI tooltips and internal runbooks.

Integrating with other systems

• ERP: Schedule nightly syncs to update ILS denominated BOM costs with latest metals prices.
• E-commerce: Cache ILS per ounce prices and compute SKU-level price adjustments hourly.
• Risk engines: Ingest hourly ILS time series to run VaR or stress tests on local-currency exposure.

Comparing endpoints used in this article

Endpoint	Primary use	Pros	Cons
Latest	Hourly/intraday polling	Simple, up-to-date	Requires your own persistence for history
Historical (by date)	Point-in-time correction/backfill	Deterministic date snapshot	One day per request
Time-series	Daily spans for charts/backfill	Range-based retrieval	Daily granularity only
OHLC	Daily analytics in ILS	Open, high, low, close context	Requires integration with intraday for hourly workflows

Compliance, audits, and reproducibility

• Keep raw snapshots: Save unmodified JSON and your transforms; this facilitates audits.
• Deterministic transforms: Centralize inversion and unit conversions in versioned libraries.
• Immutable logs: Log timestamps and checksums to verify historical accuracy.

From prototype to production

1. Prototype: Hardcode symbols, fetch with base=ILS, invert rates, plot a small dashboard.
2. Staging: Add cron, data store, and monitoring; reconcile against Time-series daily values.
3. Production: Scale storage, add OHLC context, implement retries and alerts, and secure your key.

Call to action: get your key and build your ILS series

To start streaming ILS-denominated prices into your app, get a free API key on the Metals-API Website, confirm supported metals and currencies on the Metals-API Supported Symbols page, and reference the Metals-API Documentation for full endpoint details. With a few lines of code and a simple hourly scheduler, you can stand up a robust ILS historical time series tailored to your business.

FAQ

Do I get ILS prices directly from the API?

Yes. Set base=ILS and the API returns rates for metals relative to ILS. Invert the rate to obtain “ILS per ounce.”

How do I create an hourly historical series?

Poll the Latest endpoint on your desired cadence (e.g., hourly), store the timestamp and rates, and invert to ILS per ounce if needed. Use Historical and Time-series endpoints to backfill and reconcile.

What units are used?

Metals are quoted per troy ounce. If you need grams or kilograms, convert using 1 troy ounce ≈ 31.1034768 grams.

How do I handle weekends or market closures?

Expect flat or missing updates on some dates. Time-series results may be sparse; your app should handle gaps gracefully and avoid treating them as errors.

Can I cache results to reduce calls?

Yes. Cache and reuse results within the same hour or according to your plan’s update interval. Use a shared data store so multiple services don’t duplicate API traffic.

Where can I find all symbols and endpoint details?

See the Supported Symbols and the API Documentation for comprehensive details.

Is it safe to call the API from the browser?

No. Keep your access_key on your server. Exposing it client-side risks abuse and quota exhaustion.

How do I reconcile hourly data with daily OHLC?

Use OHLC as a daily context and quality check. Your hourly extrema should be consistent with daily highs/lows unless you have after-hours effects; investigate significant discrepancies.

How do I get started?

Sign up on the Metals-API Website for an API key, request Latest with base=ILS, store the hourly snapshots, and iterate from there.