fred-api-client

A fully-typed TypeScript client for the FRED® API (Federal Reserve Economic Data), published by the St. Louis Fed.

Covers all 36 endpoints across Categories, Releases, Series, Sources, Tags, GeoFRED Maps, and the v2 bulk API.

Features

• ✅ Full TypeScript types for every request and response
• ✅ All 36 FRED® API endpoints covered
• ✅ ESM + CJS dual output
• ✅ Zero runtime dependencies
• ✅ Custom fetch support (bring your own, for Node 18-, Deno, Bun, etc.)
• ✅ Configurable timeout and base URL
• ✅ Meaningful error types (FredError) with HTTP status codes

Installation

npm install fred-api-client

Node.js ≥ 18 is required (uses native fetch). For Node < 18 provide a custom fetch via the fetch option.

Quick Start

import { FredClient } from 'fred-api-client';

const fred = new FredClient({ apiKey: 'YOUR_API_KEY' });

// Get GDP observations
const data = await fred.series.getSeriesObservations({ series_id: 'GDP' });
console.log(data.observations);

// Search for series
const results = await fred.series.searchSeries({ search_text: 'unemployment rate' });
console.log(results.seriess);

Get your free API key at: https://fred.stlouisfed.org/docs/api/api_key.html

Configuration

const fred = new FredClient({
  apiKey: 'YOUR_API_KEY',      // required
  baseUrl: 'https://api.stlouisfed.org', // optional, default shown
  fileType: 'json',            // optional, 'json' | 'xml'
  timeout: 30_000,             // optional, milliseconds
  fetch: customFetchFn,        // optional, custom fetch implementation
});

API Reference

All methods are async and return typed Promises. Parameters mirror the official FRED API docs exactly.

fred.categories

| Method | FRED Endpoint | |--------|--------------| | getCategory(params) | GET /fred/category | | getCategoryChildren(params) | GET /fred/category/children | | getCategoryRelated(params) | GET /fred/category/related | | getCategorySeries(params) | GET /fred/category/series | | getCategoryTags(params) | GET /fred/category/tags | | getCategoryRelatedTags(params) | GET /fred/category/related_tags |

fred.releases

| Method | FRED Endpoint | |--------|--------------| | getReleases(params?) | GET /fred/releases | | getAllReleaseDates(params?) | GET /fred/releases/dates | | getRelease(params) | GET /fred/release | | getReleaseDates(params) | GET /fred/release/dates | | getReleaseSeries(params) | GET /fred/release/series | | getReleaseSources(params) | GET /fred/release/sources | | getReleaseTags(params) | GET /fred/release/tags | | getReleaseRelatedTags(params) | GET /fred/release/related_tags | | getReleaseTables(params) | GET /fred/release/tables |

fred.series

| Method | FRED Endpoint | |--------|--------------| | getSeries(params) | GET /fred/series | | getSeriesCategories(params) | GET /fred/series/categories | | getSeriesObservations(params) | GET /fred/series/observations | | getSeriesRelease(params) | GET /fred/series/release | | searchSeries(params) | GET /fred/series/search | | getSeriesSearchTags(params) | GET /fred/series/search/tags | | getSeriesSearchRelatedTags(params) | GET /fred/series/search/related_tags | | getSeriesTags(params) | GET /fred/series/tags | | getSeriesUpdates(params?) | GET /fred/series/updates | | getSeriesVintageDates(params) | GET /fred/series/vintagedates |

fred.sources

| Method | FRED Endpoint | |--------|--------------| | getSources(params?) | GET /fred/sources | | getSource(params) | GET /fred/source | | getSourceReleases(params) | GET /fred/source/releases |

fred.tags

| Method | FRED Endpoint | |--------|--------------| | getTags(params?) | GET /fred/tags | | getRelatedTags(params) | GET /fred/related_tags | | getTagsSeries(params) | GET /fred/tags/series |

fred.maps (GeoFRED)

| Method | FRED Endpoint | |--------|--------------| | getShapes(params) | GET /geofred/shapes/file | | getSeriesGroup(params) | GET /geofred/series/group | | getSeriesData(params) | GET /geofred/series/data | | getRegionalData(params) | GET /geofred/regional/data |

fred.v2 (Bulk API)

| Method | FRED Endpoint | |--------|--------------| | getReleaseObservations(params) | GET /fred/v2/release/observations |

Error Handling

import { FredClient, FredError } from 'fred-api-client';

const fred = new FredClient({ apiKey: 'YOUR_API_KEY' });

try {
  const data = await fred.series.getSeries({ series_id: 'INVALID_ID' });
} catch (err) {
  if (err instanceof FredError) {
    console.error(`FRED Error [${err.code}]: ${err.message}`);
    // err.status  → HTTP status code
    // err.code    → FRED API error code
    // err.message → Human-readable message
  }
}

Examples

Fetch US GDP with percent change transformation

const gdp = await fred.series.getSeriesObservations({
  series_id: 'GDP',
  units: 'pc1',           // Percent change from year ago
  frequency: 'q',         // Quarterly
  observation_start: '2010-01-01',
});

Search for series and get their tags

const search = await fred.series.searchSeries({
  search_text: 'consumer price index',
  limit: 5,
  order_by: 'popularity',
  sort_order: 'desc',
});

for (const s of search.seriess) {
  const tags = await fred.series.getSeriesTags({ series_id: (s as { id: string }).id });
  console.log(tags.tags.map((t) => t.name));
}

Get state-level unemployment data (GeoFRED)

const regional = await fred.maps.getRegionalData({
  series_group: '882',
  region_type: 'state',
  date: '2024-01-01',
  season: 'NSA',
  units: 'Percent',
});

Use with a custom fetch (Node < 18)

import fetch from 'node-fetch';
import { FredClient } from 'fred-api-client';

const fred = new FredClient({
  apiKey: 'YOUR_API_KEY',
  fetch: fetch as unknown as typeof globalThis.fetch,
});

Development

# Install dependencies
npm install

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Lint
npm run lint

# Build
npm run build

License

MIT © Your Name