FRED GeoFRED Endpoints

FRED GeoFRED Endpoints

GeoFRED endpoints provide access to geographic/regional economic data and shape files for mapping.

Table of Contents

1. geofred/shapes/file - Get geographic shape files
2. geofred/series/group - Get series group metadata
3. geofred/series/data - Get regional series data
4. geofred/regional/data - Get regional data by group

Base URL

https://api.stlouisfed.org/geofred/

About GeoFRED

GeoFRED provides regional economic data for mapping and geographic analysis:

• State-level data (unemployment, income, GDP)
• County-level data
• Metropolitan Statistical Area (MSA) data
• Federal Reserve district data
• International country data

geofred/shapes/file

Get geographic shape files in GeoJSON format for mapping.

URL: https://api.stlouisfed.org/geofred/shapes/file

Required Parameters

Optional Parameters

Shape Types

Example

# Get US state boundaries
response = requests.get(
    "https://api.stlouisfed.org/geofred/shapes/file",
    params={
        "api_key": API_KEY,
        "shape": "state"
    }
)
geojson = response.json()

Response (GeoJSON FeatureCollection)

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "properties": {
        "name": "California",
        "fips": "06"
      },
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [[[...]]]
      }
    },
    {
      "type": "Feature",
      "properties": {
        "name": "Texas",
        "fips": "48"
      },
      "geometry": {
        "type": "MultiPolygon",
        "coordinates": [[[...]]]
      }
    }
  ]
}

Mapping Example with Plotly

import plotly.express as px

# Get shapes
shapes = requests.get(
    "https://api.stlouisfed.org/geofred/shapes/file",
    params={"api_key": API_KEY, "shape": "state"}
).json()

# Get unemployment data
data = requests.get(
    "https://api.stlouisfed.org/geofred/regional/data",
    params={
        "api_key": API_KEY,
        "series_group": "1220",
        "region_type": "state",
        "date": "2023-01-01",
        "units": "Percent",
        "frequency": "a",
        "season": "NSA",
        "file_type": "json"
    }
).json()

# Create choropleth
fig = px.choropleth(
    data["data"]["2023-01-01"],
    geojson=shapes,
    locations="code",
    featureidkey="properties.fips",
    color="value",
    scope="usa",
    title="Unemployment Rate by State"
)
fig.show()

geofred/series/group

Get meta information for a regional data series.

URL: https://api.stlouisfed.org/geofred/series/group

Required Parameters

Optional Parameters

Example

# Get info about Texas employment series
response = requests.get(
    "https://api.stlouisfed.org/geofred/series/group",
    params={
        "api_key": API_KEY,
        "series_id": "TXNA",
        "file_type": "json"
    }
)

Response

{
  "series_group": {
    "title": "All Employees: Total Nonfarm",
    "region_type": "state",
    "series_group": "1223",
    "season": "NSA",
    "units": "Thousands of Persons",
    "frequency": "Annual",
    "min_date": "1990-01-01",
    "max_date": "2023-01-01"
  }
}

Response Fields

Note: This endpoint only works with FRED series that have associated geographic data.

geofred/series/data

Get regional data for a specific series.

URL: https://api.stlouisfed.org/geofred/series/data

Required Parameters

Optional Parameters

Note: XML format is unavailable for county-level data.

Example

# Get Wisconsin per capita income data
response = requests.get(
    "https://api.stlouisfed.org/geofred/series/data",
    params={
        "api_key": API_KEY,
        "series_id": "WIPCPI",
        "file_type": "json",
        "date": "2022-01-01"
    }
)

Response

{
  "meta": {
    "title": "Per Capita Personal Income",
    "region": "state",
    "seasonality": "Not Seasonally Adjusted",
    "units": "Dollars",
    "frequency": "Annual",
    "date": "2022-01-01"
  },
  "data": {
    "2022-01-01": [
      {
        "region": "Alabama",
        "code": "01",
        "value": "48000",
        "series_id": "ALPCPI"
      },
      {
        "region": "Alaska",
        "code": "02",
        "value": "62000",
        "series_id": "AKPCPI"
      }
    ]
  }
}

geofred/regional/data

Get regional data using a series group ID. This is the most flexible endpoint for regional data.

URL: https://api.stlouisfed.org/geofred/regional/data

Required Parameters

Optional Parameters

Region Types

Seasonality Codes

Example: State Unemployment Rates

response = requests.get(
    "https://api.stlouisfed.org/geofred/regional/data",
    params={
        "api_key": API_KEY,
        "series_group": "1220",  # Unemployment rate
        "region_type": "state",
        "date": "2023-01-01",
        "units": "Percent",
        "frequency": "a",
        "season": "NSA",
        "file_type": "json"
    }
)

Response

{
  "meta": {
    "title": "Unemployment Rate",
    "region": "state",
    "seasonality": "Not Seasonally Adjusted",
    "units": "Percent",
    "frequency": "Annual"
  },
  "data": {
    "2023-01-01": [
      {
        "region": "Alabama",
        "code": "01",
        "value": "2.8",
        "series_id": "ALUR"
      },
      {
        "region": "California",
        "code": "06",
        "value": "4.3",
        "series_id": "CAUR"
      }
    ]
  }
}

Example: Per Capita Income by County

response = requests.get(
    "https://api.stlouisfed.org/geofred/regional/data",
    params={
        "api_key": API_KEY,
        "series_group": "882",  # Per capita income
        "region_type": "county",
        "date": "2021-01-01",
        "units": "Dollars",
        "frequency": "a",
        "season": "NSA",
        "file_type": "json"
    }
)

Example: GDP by Metro Area

response = requests.get(
    "https://api.stlouisfed.org/geofred/regional/data",
    params={
        "api_key": API_KEY,
        "series_group": "1282",  # Real GDP
        "region_type": "msa",
        "date": "2022-01-01",
        "units": "Millions of Chained 2017 Dollars",
        "frequency": "a",
        "season": "NSA",
        "file_type": "json"
    }
)

Common Series Groups

Building a Regional Dashboard

def get_state_dashboard(api_key, state_code, date):
    """Get key economic indicators for a state."""

    indicators = {
        "unemployment": {"group": "1220", "units": "Percent"},
        "income": {"group": "882", "units": "Dollars"},
        "employment": {"group": "1223", "units": "Thousands of Persons"}
    }

    dashboard = {}

    for name, params in indicators.items():
        response = requests.get(
            "https://api.stlouisfed.org/geofred/regional/data",
            params={
                "api_key": api_key,
                "series_group": params["group"],
                "region_type": "state",
                "date": date,
                "units": params["units"],
                "frequency": "a",
                "season": "NSA",
                "file_type": "json"
            }
        )
        data = response.json()

        # Find state data
        for region in data.get("data", {}).get(date, []):
            if region["code"] == state_code:
                dashboard[name] = {
                    "value": region["value"],
                    "units": params["units"],
                    "series_id": region["series_id"]
                }
                break

    return dashboard

# Get California dashboard
ca_data = get_state_dashboard(API_KEY, "06", "2023-01-01")

Creating Choropleth Maps

import pandas as pd
import plotly.express as px

def create_state_map(api_key, series_group, date, title):
    """Create a choropleth map of state-level data."""

    # Get shapes
    shapes = requests.get(
        f"https://api.stlouisfed.org/geofred/shapes/file",
        params={"api_key": api_key, "shape": "state"}
    ).json()

    # Get data
    response = requests.get(
        "https://api.stlouisfed.org/geofred/regional/data",
        params={
            "api_key": api_key,
            "series_group": series_group,
            "region_type": "state",
            "date": date,
            "units": "Percent",
            "frequency": "a",
            "season": "NSA",
            "file_type": "json"
        }
    )
    data = response.json()

    # Convert to DataFrame
    df = pd.DataFrame(data["data"][date])
    df["value"] = pd.to_numeric(df["value"], errors="coerce")

    # Create map
    fig = px.choropleth(
        df,
        geojson=shapes,
        locations="code",
        featureidkey="properties.fips",
        color="value",
        hover_name="region",
        scope="usa",
        title=title,
        color_continuous_scale="RdYlGn_r"
    )

    return fig

# Create unemployment map
map_fig = create_state_map(
    API_KEY,
    series_group="1220",
    date="2023-01-01",
    title="Unemployment Rate by State (2023)"
)
map_fig.show()

Time Series by Region

def get_regional_time_series(api_key, series_group, region_type, start_date, end_date):
    """Get time series data for all regions."""
    from datetime import datetime

    # Generate dates (annual)
    start = datetime.strptime(start_date, "%Y-%m-%d")
    end = datetime.strptime(end_date, "%Y-%m-%d")

    all_data = {}

    for year in range(start.year, end.year + 1):
        date = f"{year}-01-01"

        response = requests.get(
            "https://api.stlouisfed.org/geofred/regional/data",
            params={
                "api_key": api_key,
                "series_group": series_group,
                "region_type": region_type,
                "date": date,
                "units": "Percent",
                "frequency": "a",
                "season": "NSA",
                "file_type": "json"
            }
        )
        data = response.json()

        for region in data.get("data", {}).get(date, []):
            region_name = region["region"]
            if region_name not in all_data:
                all_data[region_name] = {}
            all_data[region_name][date] = region["value"]

    return all_data

# Get 5-year unemployment trends by state
trends = get_regional_time_series(
    API_KEY,
    series_group="1220",
    region_type="state",
    start_date="2019-01-01",
    end_date="2023-01-01"
)