mirror of
https://github.com/K-Dense-AI/claude-scientific-skills.git
synced 2026-03-28 07:33:45 +08:00
589 lines
14 KiB
Markdown
589 lines
14 KiB
Markdown
# FRED GeoFRED Endpoints
|
|
|
|
GeoFRED endpoints provide access to geographic/regional economic data and shape files for mapping.
|
|
|
|
## Table of Contents
|
|
|
|
1. [geofred/shapes/file](#geofredshapesfile) - Get geographic shape files
|
|
2. [geofred/series/group](#geofredseriesgroup) - Get series group metadata
|
|
3. [geofred/series/data](#geofredseriesdata) - Get regional series data
|
|
4. [geofred/regional/data](#geofredregionaldata) - 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
|
|
|
|
```python
|
|
# 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)
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
# 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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```python
|
|
# 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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```python
|
|
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
|
|
|
|
```json
|
|
{
|
|
"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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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
|
|
|
|
```python
|
|
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"
|
|
)
|
|
```
|