skills/claude-scientific-skills

Fork 0

mirror of https://github.com/K-Dense-AI/claude-scientific-skills.git synced 2026-03-27 07:09:27 +08:00

Files

Timothy Kassis d17d74dc5d Add support for economic data form the Federal Reserve using FRED

2026-01-27 10:41:40 -08:00

14 KiB

Raw Blame History

FRED GeoFRED Endpoints

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

geofred/shapes/file - Get geographic shape files
geofred/series/group - Get series group metadata
geofred/series/data - Get regional series data
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"
)

14 KiB Raw Blame History

FRED GeoFRED Endpoints

Table of Contents

Base URL

About GeoFRED

geofred/shapes/file

Required Parameters

Optional Parameters

Shape Types

Example

Response (GeoJSON FeatureCollection)

Mapping Example with Plotly

geofred/series/group

Required Parameters

Optional Parameters

Example

Response

Response Fields

geofred/series/data

Required Parameters

Optional Parameters

Example

Response

geofred/regional/data

Required Parameters

Optional Parameters

Region Types

Seasonality Codes

Example: State Unemployment Rates

Response

Example: Per Capita Income by County

Example: GDP by Metro Area

Common Series Groups

Building a Regional Dashboard

Creating Choropleth Maps

Time Series by Region

14 KiB

Raw Blame History