Updated on 2026-05-12 NovaDataHub Engineering
Developer docs

Historical FX Time Series

Historical FX time-series requests are useful when you need reporting windows, reconciliation support, or analytics that depend on past currency values rather than only the latest rate.

Key points

  • Built for date-range retrieval instead of a single current snapshot.
  • Useful for reporting, reconciliation, finance analytics, and historical pricing analysis.
  • The response is easiest to work with when you keep the original date range and base context alongside the returned values.

Common errors

  • 400 start and end are required
  • 400 invalid_currency
  • 401 invalid_key
  • 429 rate_limited
Reference details

Parameters, response shape, and operational notes

Parameter notes

  • start and end should be valid YYYY-MM-DD values.
  • symbols should stay focused on the currencies the workflow actually needs so the payload remains easy to reason about.
  • Historical requests benefit from clear base-currency handling because later reports depend on that context.

Response highlights

  • Look for base, start, end, and date-keyed rate structures in the payload.
  • Time-series data is most valuable when joined with internal business metrics over the same period.
  • Historical and latest-rate workflows should not be conflated unless your application explicitly compares them.

Operational notes

  • Choose reporting windows intentionally rather than fetching oversized historical ranges by default.
  • Cache or persist results when the same finance or analytics reports are run repeatedly.
  • Make sure downstream consumers understand whether they are seeing current values or historical period data.

Implementation checklist

  • Start with a short, known date range and one target symbol to validate the response shape.
  • Decide whether you will store raw time-series JSON or normalize it into date-based rows for analytics.
  • Keep the base currency and requested range in every downstream record so auditability stays simple.
Code examples

Visible integration examples

curl

curl -s -H "x-api-key: YOUR_API_KEY" "https://novadatahub.com/api/fx/timeseries?base=EUR&symbols=USD&start=2024-01-01&end=2024-01-31"

Python

import requests
resp = requests.get('https://novadatahub.com/api/fx/timeseries', params={'base': 'EUR', 'symbols': 'USD', 'start': '2024-01-01', 'end': '2024-01-31'}, headers={'x-api-key': 'YOUR_API_KEY'}, timeout=60)
print(resp.json())

C# HttpClient

using System.Net.Http.Json;
using System.Text.Json;
using var http = new HttpClient();
http.DefaultRequestHeaders.Add("x-api-key", "YOUR_API_KEY");
var json = await http.GetFromJsonAsync<JsonElement>("https://novadatahub.com/api/fx/timeseries?base=EUR&symbols=USD&start=2024-01-01&end=2024-01-31");
Console.WriteLine(json.ToString());

Sample JSON response

{
  "ok": true,
  "base": "EUR",
  "start": "2024-01-01",
  "end": "2024-01-31",
  "rates": {
    "2024-01-01": { "USD": 1.103 },
    "2024-01-31": { "USD": 1.082 }
  }
}
Related resources

Move from reference docs into the next relevant workflow

Currency Exchange API landing page

Open the main FX overview page for current rates, conversion, and historical data use cases.

Open landing page

Multi-currency checkout guide

Read the implementation guide for base-currency design, fallbacks, and pricing consistency across surfaces.

Open guide

Historical FX reporting tutorial

Follow a practical workflow for date-range retrieval, normalization, and reporting-ready storage.

Open tutorial

FX comparison page

See what product and finance teams should evaluate when choosing an FX API for pricing and reporting.

Open comparison
Related links

Continue with connected pages

Currency Exchange API

Open the related NovaDataHub page for deeper documentation, comparisons, or implementation guidance.

Historical FX tutorial

Open the related NovaDataHub page for deeper documentation, comparisons, or implementation guidance.

Historical FX reporting guide

Open the related NovaDataHub page for deeper documentation, comparisons, or implementation guidance.

Historical exchange rate solution

Open the related NovaDataHub page for deeper documentation, comparisons, or implementation guidance.