BEA Data Skill

Reading the credentials file (bash):

KEY=$(grep '^api_key=' ~/.config/bea/credentials 2>/dev/null | cut -d= -f2)
[ -z "$KEY" ] && KEY="${BEA_API_KEY}"
if [ -z "$KEY" ]; then
    echo "No BEA API key found. Get one free at https://apps.bea.gov/API/signup/"
    echo "Store in ~/.config/bea/credentials as api_key=YOUR_KEY"
    exit 1
fi

Reading the credentials file (Go):

func resolveAPIKey() (string, error) {
    home, _ := os.UserHomeDir()
    creds := filepath.Join(home, ".config", "bea", "credentials")
    if data, err := os.ReadFile(creds); err == nil {
        for _, line := range strings.Split(string(data), "\n") {
            line = strings.TrimSpace(line)
            if strings.HasPrefix(line, "api_key=") {
                return strings.TrimPrefix(line, "api_key="), nil
            }
        }
    }
    if key := os.Getenv("BEA_API_KEY"); key != "" {
        return key, nil
    }
    return "", fmt.Errorf("no BEA API key found; register free at https://apps.bea.gov/API/signup/")
}

API Structure

Base URL: https://apps.bea.gov/api/data/

All requests use GET with query parameters. Every request requires:

• UserID -- your API key
• method -- the API method to call
• ResultFormat -- always use JSON

API Methods

Key Datasets

Key Queries by Domain

GDP by Industry (Mining/Extraction)

# GDP by industry -- Mining sector (NAICS 21)
curl -s "https://apps.bea.gov/api/data/?\
UserID=$KEY&\
method=GetData&\
DatasetName=GDPByIndustry&\
TableID=1&\
Frequency=A&\
Year=2018,2019,2020,2021,2022,2023&\
Industry=21&\
ResultFormat=JSON"

Key Industry codes for PNGE:

Table IDs for GDPByIndustry:

Regional Data (State/County Level)

# Per capita personal income for WV counties
curl -s "https://apps.bea.gov/api/data/?\
UserID=$KEY&\
method=GetData&\
DatasetName=Regional&\
TableName=CAINC1&\
GeoFips=COUNTY&\
LineCode=3&\
Year=2022&\
ResultFormat=JSON"

Key Regional tables:

GeoFips codes:

LineCode values for CAINC1:

International Trade (Petroleum and Minerals)

# International trade in goods -- petroleum category
curl -s "https://apps.bea.gov/api/data/?\
UserID=$KEY&\
method=GetData&\
DatasetName=ITA&\
Indicator=BalGds&\
AreaOrCountry=AllCountries&\
Frequency=A&\
Year=2020,2021,2022,2023&\
ResultFormat=JSON"

Key ITA indicators:

Workflow

Step 1 -- Resolve Intent

Map the user's question to dataset and parameters:

Step 2 -- Discover Parameters (if needed)

If unsure of valid parameter values, query metadata first:

# List valid industries for GDPByIndustry
curl -s "https://apps.bea.gov/api/data/?\
UserID=$KEY&\
method=GetParameterValues&\
DatasetName=GDPByIndustry&\
ParameterName=Industry&\
ResultFormat=JSON"

# List valid tables for Regional dataset
curl -s "https://apps.bea.gov/api/data/?\
UserID=$KEY&\
method=GetParameterValues&\
DatasetName=Regional&\
ParameterName=TableName&\
ResultFormat=JSON"

Step 3 -- Fetch Data

Build the URL with appropriate parameters. Default behavior:

• Use Frequency=A (annual) unless quarterly data is needed
• Request the last 5-6 years unless the user specifies otherwise
• Use ResultFormat=JSON always

# Value added by oil and gas extraction as % of GDP
curl -s "https://apps.bea.gov/api/data/?\
UserID=$KEY&\
method=GetData&\
DatasetName=GDPByIndustry&\
TableID=25&\
Frequency=A&\
Year=2018,2019,2020,2021,2022,2023&\
Industry=211&\
ResultFormat=JSON"

Step 4 -- Parse Response

Response structure:

{
  "BEAAPI": {
    "Request": {
      "RequestParam": [...]
    },
    "Results": {
      "Statistic": "Value Added by Industry as a Percentage of GDP",
      "UTCProductionTime": "2024-11-15T12:30:00.000",
      "Dimensions": [...],
      "Data": [
        {
          "TableID": "25",
          "Frequency": "A",
          "Year": "2023",
          "Quarter": null,
          "Industry": "211",
          "IndustrYDescription": "Oil and gas extraction",
          "DataValue": "1.3",
          "NoteRef": ""
        }
      ],
      "Notes": [...]
    }
  }
}

Key fields:

• BEAAPI.Results.Data[] -- array of data records
• DataValue -- string, parse to float; may be "(D)" for suppressed data
• NoteRef -- footnote reference code (check Notes array)
• Year/Quarter -- time period

Special values in DataValue:

• "(D)" -- data suppressed to avoid disclosure of individual firms
• "(NA)" -- not available
• "(NM)" -- not meaningful
• Numeric strings including negative values

Step 5 -- Produce Output

Format: Data Table + Narrative

Present a markdown table of the most relevant rows (cap at ~20 rows), then a narrative summary covering:

1. Current state -- most recent values
2. Trend -- direction and magnitude over the time window
3. Comparative context -- how regions or industries compare
4. Economic significance -- share of GDP, income growth, trade balance
5. PNGE relevance -- connect to oilfield economics, regional development
6. Units and caveats -- current vs chained dollars, data suppression

Example output structure:

## Oil and Gas Extraction -- Value Added as % of GDP (2018-2023)

| Year | Oil/Gas Extraction (% GDP) | All Mining (% GDP) |
|------|----------------------------|--------------------|
| 2023 | 1.3 | 1.9 |
| 2022 | 2.1 | 2.8 |
| 2021 | 1.2 | 1.7 |
| 2020 | 0.7 | 1.1 |
| 2019 | 1.5 | 2.0 |
| 2018 | 1.7 | 2.2 |

**Summary:** Oil and gas extraction contributed 1.3% of U.S. GDP in 2023,
down from its post-COVID rebound peak of 2.1% in 2022 when high commodity
prices inflated the sector's nominal value added. The 2020 trough (0.7%)
reflects the COVID demand destruction. For WV specifically, the mining
sector's GDP share is significantly higher -- use the Regional dataset
(SAGDP2N) for state-level industry breakdown.

*Source: BEA GDP by Industry accounts. Nominal value added.*

Pagination

The BEA API does not paginate -- it returns all matching data in a single response. For large result sets (e.g., all counties), the response may be large but complete.

If a request returns too many records (e.g., all counties x all years), narrow the query by specifying GeoFips codes or limiting the year range.

Error Handling

Common error response:

{
  "BEAAPI": {
    "Request": {...},
    "Results": {
      "Error": {
        "APIErrorCode": "40",
        "APIErrorDescription": "The parameter value '999' is not valid..."
      }
    }
  }
}

PNGE-Relevant Query Patterns

Compare Energy County Incomes

# Per capita income for key Marcellus/Utica counties
# Monongalia WV, Marion WV, Washington PA, Belmont OH
curl -s "https://apps.bea.gov/api/data/?\
UserID=$KEY&\
method=GetData&\
DatasetName=Regional&\
TableName=CAINC1&\
GeoFips=54061,54049,42125,39013&\
LineCode=3&\
Year=2018,2019,2020,2021,2022&\
ResultFormat=JSON"

Mining Earnings as Share of County Income

# Earnings by NAICS industry for WV counties
curl -s "https://apps.bea.gov/api/data/?\
UserID=$KEY&\
method=GetData&\
DatasetName=Regional&\
TableName=CAINC5N&\
GeoFips=54061&\
LineCode=200&\
Year=2022&\
ResultFormat=JSON"

LineCode 200 = Mining, quarrying, and oil and gas extraction earnings.

WV State GDP by Industry

# GDP by industry for West Virginia
curl -s "https://apps.bea.gov/api/data/?\
UserID=$KEY&\
method=GetData&\
DatasetName=Regional&\
TableName=SAGDP2N&\
GeoFips=54000&\
LineCode=6&\
Year=2022&\
ResultFormat=JSON"

LineCode 6 = Mining, quarrying, and oil and gas extraction.

FIPS Code Reference for Appalachian Energy Counties

Caveats and Data Quality

• Publication lag: GDP by industry released annually (~6 months after year end). Regional county data lags ~18 months. Advance estimates may be revised for up to 3 years.
• Data suppression: County-level data for small industries is frequently suppressed (D) to protect individual firm confidentiality. Mining data is especially prone to this in counties with few operators.
• NAICS aggregation: "Mining" (NAICS 21) includes oil/gas extraction (211), non-oil/gas mining (212, includes lithium), and support activities (213). Finer breakdowns are often suppressed at the county level.
• Current vs real dollars: GDP tables with "nominal" or "current dollar" values reflect both price and quantity changes. Use "chained dollar" or "real" tables (TableID 5, 11) for volume trends. Do not compare nominal values across years without deflating.
• Regional data coverage: County-level GDP data (CAGDP series) began in 2017 and covers fewer industries than state-level data. Personal income data goes back to 1969 for most counties.
• API rate limits: BEA does not publish explicit rate limits, but excessive requests may trigger throttling. Add 200ms delay between sequential calls.

Implementation Notes

• Use bash with curl + jq for API calls
• GET requests only -- all BEA API calls are GET with query parameters
• DataValue is always a string -- parse to float, handle special values (D), (NA), (NM) as missing data
• Year parameter: Comma-separated list of years or ALL for all available years. LAST5 returns the last 5 years.
• GeoFips: State codes are XX000 (e.g., 54000 for WV). County codes are 5-digit FIPS. Use STATE, COUNTY, or MSA for all entities of that type.
• Multiple industries: Use Industry=ALL or comma-separated codes. At the county level, only broad industry groups are available.
• BEA API documentation: Full reference at https://apps.bea.gov/api/_pdf/bea_web_service_api_user_guide.pdf