@varve/fred-api

An isomorphic, Zod-validated TypeScript client for the Federal Reserve Economic Data (FRED) API.

Works in Node.js 18+ and modern browsers. The client exposes FRED categories, releases, series, observations, sources, tags, GeoFRED maps data, and graph-friendly metadata for natural-language query systems.

Installation

npm install @varve/fred-api zod

zod is a required peer dependency.

Quick start

import { FredClient } from '@varve/fred-api';

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

const gdp = await client.getSeries('GDP');

const observations = await client.getSeriesObservations('GDP', {
  observationStart: '2020-01-01',
  observationEnd: '2024-12-31',
  units: 'lin',
});

const graph = await client.getSeriesObservationGraphMetadata('GDP', {
  observationStart: '2020-01-01',
  observationEnd: '2024-12-31',
});

console.log(gdp.seriess[0]);
console.log(observations.observations);
console.log(graph.observations);

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 with a short delay. FRED API keys are explicit to keep browser and server use predictable.

API reference

Series

const series = await client.getSeries('GDP');
const observations = await client.getSeriesObservations('GDP', {
  observationStart: '2020-01-01',
  observationEnd: '2024-12-31',
  units: 'pch',
  frequency: 'q',
  aggregationMethod: 'avg',
});

const results = await client.searchSeries({
  searchText: 'unemployment rate',
  tagNames: ['usa'],
  limit: 10,
});

const categories = await client.getSeriesCategories('GDP');
const release = await client.getSeriesRelease('GDP');
const tags = await client.getSeriesTags('GDP');
const vintages = await client.getSeriesVintageDates('GDP');

Categories

const root = await client.getCategory();
const children = await client.getCategoryChildren({ categoryId: 0 });
const related = await client.getCategoryRelated(125);
const categorySeries = await client.getCategorySeries({ categoryId: 106 });
const categoryTags = await client.getCategoryTags({ categoryId: 106 });

Releases

const releases = await client.getReleases({ limit: 100 });
const release = await client.getRelease(53);
const dates = await client.getReleaseDates();
const releaseDates = await client.getReleaseDatesForRelease(53);
const releaseSeries = await client.getReleaseSeries({ releaseId: 53, limit: 100 });
const sources = await client.getReleaseSources(53);
const tables = await client.getReleaseTables(53);

Sources and tags

const sources = await client.getSources();
const source = await client.getSource(1);
const sourceReleases = await client.getSourceReleases(1);

const tags = await client.getTags({ searchText: 'price' });
const relatedTags = await client.getRelatedTags({ tagNames: ['usa', 'price'] });
const taggedSeries = await client.getTagsSeries({ tagNames: ['usa', 'gdp'] });

Maps API

const shapes = await client.getGeoShapes('state');

const group = await client.getGeoSeriesGroup('SMU56000000500000001a');

const regionalSeries = await client.getGeoSeriesData('WIPCPI', {
  date: '2012-01-01',
});

const regionalGroup = await client.getGeoRegionalData({
  seriesGroup: 882,
  date: '2013-01-01',
  regionType: 'state',
  units: 'Dollars',
  frequency: 'a',
  season: 'NSA',
});

Graph metadata

FRED series observations naturally map to a series -> period -> value graph.

const graph = await client.getSeriesObservationGraphMetadata('GDP', {
  observationStart: '2020-01-01',
  observationEnd: '2024-12-31',
});

graph.series;
graph.periods;
graph.observations;

Example graph shape:

(:Series {id})-[:HAS_OBSERVATION]->(:Observation {period, value})

FRED represents missing observations as ".". Graph metadata omits those by default; pass includeMissingValues: true to include them as null.

Endpoint registry

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

Official docs

• FRED API documentation: https://fred.stlouisfed.org/docs/api/fred/
• API keys: https://fred.stlouisfed.org/docs/api/api_key.html
• Series observations: https://fred.stlouisfed.org/docs/api/fred/series_observations.html

Error handling

All non-2xx responses throw a FredApiError. Invalid JSON, schema mismatches, and FRED JSON error payloads throw FredResponseError.

import { FredApiError, FredResponseError } from '@varve/fred-api';

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);
  }
}