skills/fred-economic-data
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
fred-economic-data/references/geofred.md
dfty e99c3e1ec9 Initial commit for fred-economic-data
2026-01-28 12:43:41 +08:00

14 KiB
Raw Permalink Blame History

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

Parameter Type Description
api_key string 32-character API key

Optional Parameters

Parameter Type Description
shape string Geographic shape type

Shape Types

Value Description
bea Bureau of Economic Analysis regions
msa Metropolitan Statistical Areas
frb Federal Reserve Bank districts
necta New England City and Town Areas
state US states
country Countries
county US counties
censusregion Census regions
censusdivision Census divisions

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

Parameter Type Description
api_key string 32-character API key
series_id string FRED series ID with geographic data

Optional Parameters

Parameter Type Default Description
file_type string xml xml or json

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

Field Description
title Series title
region_type Geographic region type
series_group Group identifier for related series
season Seasonality (NSA, SA, etc.)
units Units of measurement
frequency Data frequency
min_date Earliest available date
max_date Latest available date

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

Parameter Type Description
api_key string 32-character API key
series_id string FRED series ID with geographic data

Optional Parameters

Parameter Type Default Description
file_type string xml xml or json
date string most recent YYYY-MM-DD
start_date string - YYYY-MM-DD

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

Parameter Type Description
api_key string 32-character API key
series_group string Series group ID
region_type string Geographic region type
date string Target date (YYYY-MM-DD)
season string Seasonality code
units string Units of measurement

Optional Parameters

Parameter Type Default Description
file_type string xml xml or json
start_date string - YYYY-MM-DD
frequency string - Data frequency
transformation string lin Data transformation
aggregation_method string avg avg, sum, eop

Region Types

Value Description
bea Bureau of Economic Analysis regions
msa Metropolitan Statistical Areas
frb Federal Reserve Bank districts
necta New England City and Town Areas
state US states
country Countries
county US counties
censusregion Census regions

Seasonality Codes

Code Description
SA Seasonally Adjusted
NSA Not Seasonally Adjusted
SSA Smoothed Seasonally Adjusted
SAAR Seasonally Adjusted Annual Rate
NSAAR Not Seasonally Adjusted Annual Rate

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

Group ID Description Region Types
882 Per Capita Personal Income state, county, msa
1220 Unemployment Rate state, county, msa
1223 Total Nonfarm Employment state, msa
1282 Real GDP state, msa
1253 House Price Index state, msa
1005 Population state, county

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"
)
Reference in New Issue View Git Blame Copy Permalink