FRED Tags Endpoints

FRED Tags Endpoints

Tags endpoints provide access to FRED tags, which are attributes assigned to series for organization and discovery.

Table of Contents

1. fred/tags - Get all FRED tags
2. fred/related_tags - Get related tags
3. fred/tags/series - Get series matching tags

About Tags

Tags are attributes assigned to series that help categorize and discover data. Tags are organized into groups:

fred/tags

Get FRED tags with optional filtering.

URL: https://api.stlouisfed.org/fred/tags

Required Parameters

Optional Parameters

Example: Get All Tags

response = requests.get(
    "https://api.stlouisfed.org/fred/tags",
    params={
        "api_key": API_KEY,
        "file_type": "json",
        "order_by": "popularity",
        "sort_order": "desc",
        "limit": 20
    }
)

Response

{
  "realtime_start": "2023-08-14",
  "realtime_end": "2023-08-14",
  "count": 5000,
  "offset": 0,
  "limit": 20,
  "tags": [
    {
      "name": "nation",
      "group_id": "geot",
      "notes": "",
      "created": "2012-02-27 10:18:19-06",
      "popularity": 100,
      "series_count": 150000
    },
    {
      "name": "usa",
      "group_id": "geo",
      "notes": "United States of America",
      "created": "2012-02-27 10:18:19-06",
      "popularity": 100,
      "series_count": 450000
    },
    {
      "name": "gdp",
      "group_id": "gen",
      "notes": "Gross Domestic Product",
      "created": "2012-02-27 10:18:19-06",
      "popularity": 85,
      "series_count": 22000
    }
  ]
}

Example: Get Geography Tags Only

response = requests.get(
    "https://api.stlouisfed.org/fred/tags",
    params={
        "api_key": API_KEY,
        "file_type": "json",
        "tag_group_id": "geo",
        "order_by": "series_count",
        "sort_order": "desc"
    }
)

Example: Search for Tags

# Find tags related to inflation
response = requests.get(
    "https://api.stlouisfed.org/fred/tags",
    params={
        "api_key": API_KEY,
        "file_type": "json",
        "search_text": "inflation",
        "order_by": "series_count",
        "sort_order": "desc"
    }
)

fred/related_tags

Get related FRED tags for one or more specified tags.

URL: https://api.stlouisfed.org/fred/related_tags

Required Parameters

Optional Parameters

Example: Find Tags Related to GDP

response = requests.get(
    "https://api.stlouisfed.org/fred/related_tags",
    params={
        "api_key": API_KEY,
        "tag_names": "gdp",
        "file_type": "json",
        "order_by": "series_count",
        "sort_order": "desc",
        "limit": 20
    }
)

Response

{
  "realtime_start": "2023-08-14",
  "realtime_end": "2023-08-14",
  "count": 500,
  "offset": 0,
  "limit": 20,
  "tags": [
    {
      "name": "quarterly",
      "group_id": "freq",
      "notes": "",
      "created": "2012-02-27 10:18:19-06",
      "popularity": 95,
      "series_count": 18000
    },
    {
      "name": "annual",
      "group_id": "freq",
      "series_count": 15000
    },
    {
      "name": "real",
      "group_id": "gen",
      "series_count": 12000
    }
  ]
}

Example: Find Geographic Tags Related to Unemployment

response = requests.get(
    "https://api.stlouisfed.org/fred/related_tags",
    params={
        "api_key": API_KEY,
        "tag_names": "unemployment rate",
        "file_type": "json",
        "tag_group_id": "geo",
        "order_by": "series_count",
        "sort_order": "desc"
    }
)

fred/tags/series

Get the series matching all specified tags.

URL: https://api.stlouisfed.org/fred/tags/series

Required Parameters

Optional Parameters

Order By Options

• series_id
• title
• units
• frequency
• seasonal_adjustment
• realtime_start
• realtime_end
• last_updated
• observation_start
• observation_end
• popularity
• group_popularity

Example: Find Quarterly GDP Series for USA

response = requests.get(
    "https://api.stlouisfed.org/fred/tags/series",
    params={
        "api_key": API_KEY,
        "tag_names": "gdp;quarterly;usa",
        "file_type": "json",
        "order_by": "popularity",
        "sort_order": "desc"
    }
)

Response

{
  "realtime_start": "2023-08-14",
  "realtime_end": "2023-08-14",
  "count": 150,
  "offset": 0,
  "limit": 1000,
  "seriess": [
    {
      "id": "GDP",
      "realtime_start": "2023-08-14",
      "realtime_end": "2023-08-14",
      "title": "Gross Domestic Product",
      "observation_start": "1947-01-01",
      "observation_end": "2023-04-01",
      "frequency": "Quarterly",
      "units": "Billions of Dollars",
      "seasonal_adjustment": "Seasonally Adjusted Annual Rate",
      "last_updated": "2023-06-29 07:44:02-05",
      "popularity": 95
    },
    {
      "id": "GDPC1",
      "title": "Real Gross Domestic Product",
      "frequency": "Quarterly",
      "units": "Billions of Chained 2017 Dollars",
      "popularity": 90
    }
  ]
}

Example: Find Monthly Unemployment Rates by State

response = requests.get(
    "https://api.stlouisfed.org/fred/tags/series",
    params={
        "api_key": API_KEY,
        "tag_names": "unemployment rate;monthly;state",
        "file_type": "json",
        "exclude_tag_names": "discontinued",
        "order_by": "title",
        "limit": 100
    }
)

Example: Find Inflation-Related Series Excluding NSA

response = requests.get(
    "https://api.stlouisfed.org/fred/tags/series",
    params={
        "api_key": API_KEY,
        "tag_names": "inflation;monthly;usa",
        "file_type": "json",
        "exclude_tag_names": "nsa",  # Exclude not seasonally adjusted
        "order_by": "popularity",
        "sort_order": "desc"
    }
)

Common Tag Combinations

Macroeconomic Indicators

# GDP
tags = "gdp;quarterly;usa"

# Unemployment
tags = "unemployment rate;monthly;nation"

# Inflation (CPI)
tags = "cpi;monthly;usa;sa"

# Interest Rates
tags = "interest rate;daily;treasury"

Regional Data

# State unemployment
tags = "unemployment rate;state;monthly"

# County population
tags = "population;county;annual"

# MSA employment
tags = "employment;msa;monthly"

International

# OECD countries GDP
tags = "gdp;oecd;annual"

# Exchange rates
tags = "exchange rate;daily;nation"

# International trade
tags = "trade;monthly;usa"

Tag Discovery Pattern

def discover_tags_for_topic(api_key, topic):
    """Find relevant tags for a research topic."""

    # Step 1: Find tags matching the topic
    response = requests.get(
        "https://api.stlouisfed.org/fred/tags",
        params={
            "api_key": api_key,
            "file_type": "json",
            "search_text": topic,
            "order_by": "popularity",
            "sort_order": "desc",
            "limit": 10
        }
    )
    initial_tags = response.json().get("tags", [])

    if not initial_tags:
        return []

    # Step 2: Find related tags
    top_tag = initial_tags[0]["name"]
    response = requests.get(
        "https://api.stlouisfed.org/fred/related_tags",
        params={
            "api_key": api_key,
            "tag_names": top_tag,
            "file_type": "json",
            "order_by": "series_count",
            "sort_order": "desc",
            "limit": 20
        }
    )
    related = response.json().get("tags", [])

    return {
        "primary_tags": initial_tags,
        "related_tags": related
    }

# Example: Discover inflation-related tags
tags = discover_tags_for_topic(API_KEY, "inflation")

Building Filtered Series Lists

def get_filtered_series(api_key, topic_tags, geo_tags=None, freq_tag=None):
    """Get series matching topic with optional filters."""

    all_tags = topic_tags.copy()
    if geo_tags:
        all_tags.extend(geo_tags)
    if freq_tag:
        all_tags.append(freq_tag)

    response = requests.get(
        "https://api.stlouisfed.org/fred/tags/series",
        params={
            "api_key": api_key,
            "tag_names": ";".join(all_tags),
            "file_type": "json",
            "order_by": "popularity",
            "sort_order": "desc",
            "limit": 50
        }
    )

    return response.json().get("seriess", [])

# Example: Monthly US inflation series
series = get_filtered_series(
    API_KEY,
    topic_tags=["inflation", "cpi"],
    geo_tags=["usa"],
    freq_tag="monthly"
)