@varve/fred-api

TypeScript client for FRED series, observations, releases, categories, sources, tags, GeoFRED data, and graph metadata.

Federal Reserve Economic Data (FRED) publishes US and international economic series through the Federal Reserve Bank of St. Louis. @varve/fred-api wraps FRED categories, releases, series, observations, sources, tags, GeoFRED map data, and graph-friendly metadata in an isomorphic, Zod-validated TypeScript client.

npm install @varve/fred-api zod

import { FredClient, FredApiError, FredResponseError } from '@varve/fred-api';
 
const client = new FredClient({
  apiKey: process.env.FRED_API_KEY,
});

API key required

FRED requires an API key. Keep the key on the server for production apps.

const client = new FredClient({
  apiKey: process.env.FRED_API_KEY,
});

When to use this package

Use @varve/fred-api when you need:

economic series and observations
realtime and vintage-aware metadata
release calendars and release series
categories, sources, and tags
GeoFRED shapes and regional data
graph metadata for series-period observations

Data model

Series is the core FRED object, such as GDP.

Observation is a dated value for a series.

Release, category, source, and tag describe how series are organized and discovered.

GeoFRED adds geographic shapes and regional series data.

Quick start

const gdp = await client.getSeries('GDP');
 
const observations = await client.getSeriesObservations('GDP', {
  observationStart: '2020-01-01',
  observationEnd: '2024-12-31',
  units: 'lin',
});
 
console.log(gdp.seriess[0]);
console.log(observations.observations);

Common workflows

Series and observations

Fetch series metadata, observations, search results, vintages, and graph metadata.

Releases, tags, and GeoFRED

Browse categories, releases, sources, tags, shapes, and regional data.

Configuration

const client = new FredClient({
  apiKey: 'your-fred-api-key',
  baseUrl: 'https://api.stlouisfed.org',
  maxRetries: 2,
  timeoutMs: 30_000,
});

The client retries 429 and 5xx responses.

Error handling

Invalid JSON, schema mismatches, and FRED JSON error payloads throw FredResponseError. Non-2xx transport failures throw FredApiError.

try {
  await client.getSeries('missing');
} catch (err) {
  if (err instanceof FredApiError || err instanceof FredResponseError) {
    console.error(err.status);
    console.error(err.url);
    console.error(err.body);
  }
}

Endpoint registry

The package includes docs/endpoints.json, a machine-readable registry seeded from the FRED endpoint list. It helps make wrapper coverage auditable as additional FRED endpoints are added.