go-fred

Go client for the FRED API. Stdlib only — zero dependencies.

Install

go get github.com/shanehull/go-fred

Quick Start

package main

import (
    "context"
    "fmt"
    "time"

    "github.com/shanehull/go-fred"
)

func main() {
    client, _ := fred.New() // uses $FRED_API_KEY

    obs, _ := client.GetSeriesObservations(context.Background(), "DGS20",
        fred.WithObservationStart(time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)),
        fred.WithObservationSortOrder(fred.SortDesc),
    )
    for _, o := range obs {
        if !o.IsNA {
            fmt.Printf("%s  %.2f%%\n", o.Date.Format("2006-01-02"), o.Value)
        }
    }
}

API Key

Get a free key at fred.stlouisfed.org/docs/api/api_key.html.

// Environment variable (recommended)
client, _ := fred.New()

// Explicit option (overrides env)
client, _ := fred.New(fred.WithAPIKey("your-key"))

Usage

Observations

FRED series contain time-indexed data points. Each observation has a date, value, and metadata. Missing values use "." in the API and become IsNA=true in the response.

obs, err := client.GetSeriesObservations(ctx, "DGS20",
    fred.WithObservationStart(time.Date(2024, 1, 1, 0, 0, 0, 0, time.UTC)),
    fred.WithObservationSortOrder(fred.SortDesc),
    fred.WithUnits("lin"),
    fred.WithFrequency("m"),
)

// Get metadata about a series
info, _ := client.GetSeriesInfo(ctx, "DGS20")

Vintage Data (ALFRED)

FRED stores all revisions — every time a data point is updated, the previous value is preserved. This is called ALFRED (Archival FRED). Each observation has three dates: date (the period), realtime_start (first date this value was reported), and realtime_end (last date before a revision).

// All releases: every revision for every date
all, _ := client.GetSeriesAllReleases(ctx, "DGS20",
    fred.WithRealtimeStart(time.Date(2023, 1, 1, 0, 0, 0, 0, time.UTC)),
)

// First release: the earliest published value for each date
first, _ := client.GetSeriesFirstRelease(ctx, "DGS20")

// As-of: the data as it was known on a specific date
asof, _ := client.GetSeriesAsOf(ctx, "DGS20", time.Date(2023, 6, 1, 0, 0, 0, 0, time.UTC))

// Vintage dates: all dates when this series was revised
dates, _ := client.GetSeriesVintageDates(ctx, "DGS20")

Search

Search FRED by keyword, filter by tags, or browse series belonging to a release or category. Search endpoints auto-paginate — set limit=0 for all results.

results, _ := client.SearchSeries(ctx, "real GDP",
    fred.WithLimit(50),
    fred.WithOrderBy(fred.OrderByPopularity),
)

// Series belonging to a release or category
series, _ := client.GetReleaseSeries(ctx, 53, fred.WithLimit(100))
series, _ := client.GetCategorySeries(ctx, 1, fred.WithLimit(100))

Categories, Releases, Sources, Tags

FRED organizes data into categories (topics), releases (publications), sources (data providers), and tags (keywords). These form the taxonomy for discovering series.

cat, _  := client.GetCategory(ctx, 1)
children, _ := client.GetCategoryChildren(ctx, 0)
rel, _  := client.GetRelease(ctx, 53)
src, _  := client.GetSource(ctx, 1)
tags, _ := client.GetTags(ctx, fred.WithTagLimit(20))

GeoFRED

GeoFRED provides geographic data — maps at the state, county, MSA, and country level. Get map metadata, then pull regional data by series group.

group, _ := client.GetSeriesGroup(ctx, "SMU56000000500000001A")
data, _  := client.GetSeriesData(ctx, "WIPCPI",
    fred.WithMapDate("2012-01-01"),
)
regional, _ := client.GetRegionalData(ctx,
    fred.WithSeriesGroup("882"),
    fred.WithRegionType("state"),
    fred.WithRegionalDate("2013-01-01"),
    fred.WithMapUnits("Dollars"),
    fred.WithSeason("NSA"),
    fred.WithRegionalFrequency("a"),
)

Error Handling

obs, err := client.GetSeriesObservations(ctx, "INVALID")
var apiErr fred.APIError
if errors.As(err, &apiErr) {
    fmt.Printf("FRED API error %d: %s\n", apiErr.Code, apiErr.Message)
}

API Coverage

Domain	Methods
Series	GetSeriesInfo, GetSeriesObservations, GetSeriesCategories, GetSeriesRelease, GetSeriesTags, GetSeriesUpdates, GetSeriesVintageDates, SearchSeries, SearchSeriesTags, SearchSeriesRelatedTags
Vintage	GetSeriesAllReleases, GetSeriesFirstRelease, GetSeriesAsOf
Categories	GetCategory, GetCategoryChildren, GetCategoryRelated, GetCategorySeries, GetCategoryTags, GetCategoryRelatedTags
Releases	GetReleases, GetReleasesDates, GetRelease, GetReleaseDates, GetReleaseSeries, GetReleaseSources, GetReleaseTags, GetReleaseRelatedTags, GetReleaseTables
Sources	GetSources, GetSource, GetSourceReleases
Tags	GetTags, GetRelatedTags, GetTagsSeries
GeoFRED	GetSeriesGroup, GetSeriesData, GetRegionalData

Examples

See examples/ for runnable programs:

• observations — fetch and display series data
• search — search for series
• vintage — compare first vs latest release values
• categories — explore the category tree
• releases — release info and dates
• tags — popular tags and related tags
• geofred — map metadata and regional data
• sources — data sources and their releases