The Easiest Way to Get Honduran Lempira (HNL) - N/A Historical Rates in JSON via REST API

You need Honduran Lempira (HNL) historical rates you can drop straight into a spreadsheet, model, or pricing engine. By the end of this guide, you’ll pull a clean daily HNL history in JSON via REST from Metals-API, parse it, and save it as a CSV you can feed into dashboards, backtests, or ERP jobs.

What you’ll build: a daily HNL history table you can ship

We’ll assemble a reliable day-by-day Lempira rate history directly from the API. You’ll:

• Query a single past date (spot check or backfill)
• Query a date range and get a compact JSON time series
• Write the result to CSV with a few lines of Python

If you don’t have an API key yet, grab one from the Metals-API Website. Keep the Metals-API Documentation open for reference and verify that HNL is listed in Metals-API Supported Symbols.

The endpoints you’ll use

To keep this practical and focused on historical data for HNL, we’ll use exactly two endpoints:

• Historical Rates (single date)
• Time-Series (date range)

Both endpoints return JSON that includes a base currency and a rates map keyed by symbol. We’ll request HNL relative to USD in the examples below. If you need a different base (e.g., EUR), you can change it with a query parameter as shown.

Query a single historical HNL rate (spot check and backfill)

Use this when you need “the HNL rate on YYYY-MM-DD.” This is ideal for data audits and backfilling a sparse history one date at a time.

curl example: one historical day

curl "https://metals-api.com/api/2024-08-31?access_key=YOUR_API_KEY&symbols=HNL&base=USD"

Illustrative JSON response (field names follow the documented format; values below are examples):

{
"success": true,
"timestamp": 1725062400,
"base": "USD",
"date": "2024-08-31",
"rates": {
"HNL": 24.65
}
}

What you’ll actually use from this response:

• date: the business date you requested
• base: the reference currency for the quote (USD here)
• rates.HNL: how many HNL per 1 USD on that date
• timestamp: a Unix epoch (UTC) you can use for ordering or audit logs

Notes:

• The API’s base is USD by default. You can change it using a query parameter (see the time-series example below for a pattern).
• If the requested date is a weekend or holiday, the API will return the most recent available business-day rate for that date field. Plan to de-duplicate or forward-fill depending on your downstream logic.

Get a full daily HNL time series (range query)

When you need a history you can drop into a chart or regression, use the time-series endpoint. It returns a compact JSON structure with a date map under rates.

curl example: date range for HNL

curl "https://metals-api.com/api/timeseries?access_key=YOUR_API_KEY&start_date=2024-08-01&end_date=2024-08-07&symbols=HNL&base=USD"

Illustrative JSON response (values are examples; structure matches the documented format):

{
"success": true,
"timeseries": true,
"start_date": "2024-08-01",
"end_date": "2024-08-07",
"base": "USD",
"rates": {
"2024-08-01": { "HNL": 24.67 },
"2024-08-02": { "HNL": 24.66 },
"2024-08-05": { "HNL": 24.66 },
"2024-08-06": { "HNL": 24.65 },
"2024-08-07": { "HNL": 24.65 }
}
}

What matters in this response:

• timeseries: true confirms you requested a range
• start_date and end_date: echo back your range
• rates: a dictionary keyed by ISO date, each containing an HNL quote
• rates[YYYY-MM-DD].HNL: HNL per 1 USD on that day

Weekend and holiday behavior:

• FX markets have thinner or no settlement on weekends. The time series may skip dates or repeat the last available rate depending on the calendar. Your downstream code should be ready for missing calendar days.

If you aren’t sure whether HNL is supported for your plan, cross-check the symbol and availability on the Metals-API Supported Symbols page. For all query parameters and edge cases, see the Metals-API Documentation.

Python sample: write the HNL time series to CSV

This snippet fetches a date range for HNL and writes a two-column CSV: date,hnl_per_usd. Adjust the dates and the base if you need a different reference currency.

import csv
import os
import sys
import urllib.parse
import urllib.request
import json

API_KEY = os.getenv("METALS_API_KEY", "YOUR_API_KEY")

params = {
"access_key": API_KEY,
"start_date": "2024-08-01",
"end_date": "2024-08-07",
"symbols": "HNL",
"base": "USD"
}

url = "https://metals-api.com/api/timeseries?" + urllib.parse.urlencode(params)

try:
with urllib.request.urlopen(url, timeout=20) as resp:
data = json.loads(resp.read().decode("utf-8"))
except Exception as e:
sys.stderr.write(f"HTTP error: {e}\n")
sys.exit(1)

if not data.get("success"):
sys.stderr.write(f"API error: {data}\n")
sys.exit(1)

rates = data.get("rates", {})
rows = []

# Normalize into sorted rows: date, hnl_per_usd
for day, quote in rates.items():
hnl = quote.get("HNL")
if hnl is not None:
rows.append((day, hnl))

rows.sort(key=lambda r: r[0])

out_path = "hnl_history.csv"
with open(out_path, "w", newline="") as f:
writer = csv.writer(f)
writer.writerow(["date", "hnl_per_usd"])
writer.writerows(rows)

print(f"Wrote {len(rows)} rows to {out_path}")

What this code does:

• Builds the /timeseries URL with access_key, start_date, end_date, symbols=HNL, base=USD
• Parses JSON and validates success
• Walks the nested rates map and extracts the HNL rate for each day
• Writes a stable, sorted CSV: date, hnl_per_usd

How the JSON is structured (and how to parse it safely)

You’ll typically see the following top-level fields:

• success: boolean indicating if the query succeeded
• timestamp: Unix epoch (UTC) aligned to the data payload
• base: the reference currency (USD by default)
• date: for single-date endpoints; the business date for the rate
• timeseries: true for range queries
• start_date, end_date: echo your requested date bounds
• rates: a map that either:
  • Contains currency symbols directly for single-date queries, e.g., rates.HNL
  • Contains a dictionary keyed by date for time series, e.g., rates["YYYY-MM-DD"].HNL

Guardrails when parsing:

• Check success before you read rates. If false, inspect the payload for an error object and retry or log.
• For time series, don’t assume every calendar day is present. Iterate the returned keys, not your calendar.
• Normalize the base. If your analytics assume HNL per USD, confirm base is USD or invert accordingly.

Units, base currency, timestamps, and non-trading days

Here are practical details that save time in integration:

• Units: For fiat currencies like HNL, the rate is “units of HNL per 1 unit of the base currency.” In our examples, base=USD, so rates.HNL means HNL per USD.
• Base currency: If you need HNL per EUR, request base=EUR. If you already fetched HNL per USD but need USD per HNL, invert (1 / hnl_per_usd) carefully, and propagate precision correctly.
• Timestamps: The timestamp field is a Unix epoch in UTC. Use it for logging, cache keys, and synchronization between services.
• Date format: All dates are ISO 8601 (YYYY-MM-DD). Use zero-padded months and days.
• Weekends/holidays: FX calendars vary. The API’s historical date may return the nearest available business-day fix for that date. In time-series payloads, dates with no new fixing might be absent or repeated via business logic upstream—handle both possibilities.

Caching, retries, and pagination

Caching:

• Historical data is immutable. Cache your successful responses by URL (or by date range) in a CDN or object store to avoid redundant requests.
• For rolling windows (e.g., last 30 days), you can update only the newest day until it stabilizes.

Retries and backoff:

• Implement idempotent retries on network timeouts and 5xx responses with exponential backoff.
• Log both the URL and the request parameters; this simplifies recreating issues.

Pagination:

• The historical and time-series endpoints return the full response for the requested date window. If you need very long histories, break requests into monthly or quarterly chunks and stitch them client-side.

Quality checks before you publish the dataset

Before pushing your CSV into production systems:

• Validate base and symbol consistency (base=USD, symbol=HNL)
• Confirm monotonic date ordering and no duplicates
• Handle missing days explicitly (forward-fill, leave gaps, or interpolate—document your choice)
• Record your query window in metadata: start_date, end_date, and the timestamp of retrieval

Where to verify HNL context and symbol support

• Confirm availability and symbol codes here: Metals-API Supported Symbols
• Read endpoint-specific notes and parameter details: Metals-API Documentation
• If you want a policy or macroeconomic cross-check, consult official sources like the Banco Central de Honduras (Spanish): Banco Central de Honduras

Going further: from JSON to analytics and apps

With a clean HNL time series in hand, you can:

• Build a currency conversion microservice for pricing Honduran customers
• Backtest hedging strategies that involve HNL exposures
• Chart historical moves and alert on breakouts using your BI stack

For more endpoints beyond historical and time-series, explore the Metals-API Documentation. You can combine currency rates with metals data to price inventory, normalize cost curves, or report P/L consistently across currencies.

Common pitfalls and how to avoid them

• Mismatched base: If downstream code expects HNL per USD, keep base=USD. If the base changes midstream, label columns clearly (e.g., hnl_per_usd vs. usd_per_hnl).
• Weekend rollovers: Don’t assume seven entries per calendar week. Work with returned dates; if you need daily granularity, fill missing days deterministically.
• Float precision: Currency series can be sensitive to rounding. Keep raw JSON values in storage and round only for display.
• Recomputing large ranges repeatedly: Cache immutable ranges. Only refetch the most recent business day if you’re within a settling window.

FAQ

Q: How do I change the base so I get HNL per EUR instead of HNL per USD?
A: Add base=EUR to your request. The rates.HNL value will then mean “HNL per 1 EUR.” Verify your downstream labels and conversions after changing base.

Q: Why is a date missing in the time-series response?
A: FX calendars have weekends and holidays. The API returns available business days. Iterate over returned keys rather than calendar days, or forward-fill explicitly if your application requires daily continuity.

Q: Are the historical values final, or can they change?
A: Treat historical responses as stable. For the most recent business day, consider a short settling window if your workflow needs end-of-day consistency.

Q: What does the timestamp field represent?
A: A Unix epoch (UTC) associated with the data payload. Use it for logging, cache keys, and validating the freshness of the response.

Q: Can I request a very long range in a single call?
A: You can query a range with the time-series endpoint, but for maintainability and speed, it’s common to segment long histories (e.g., by month) and merge client-side. Check the documentation for any practical guidance when you approach large windows.

Get your API key and start shipping

Spin up your first HNL historical pull in minutes. Create a free key on the Metals-API Website, confirm HNL on the Supported Symbols page, and use the curl and Python snippets above to produce a production-ready CSV. For parameter details and additional endpoints, keep the API Documentation handy.