Bureau of Economic Analysis (BEA) API - Complete Dataset Reference

Bureau of Economic Analysis (BEA) API - Complete Dataset Reference

API Overview

Endpoint: https://apps.bea.gov/api/data

Description: Provides access to comprehensive U.S. economic data from the Bureau of Economic Analysis including GDP, personal income, regional economic data, industry statistics, and more.

API Key: Required (36-character UserID obtained from registration)

Update Frequency: Varies by dataset (quarterly, annual)

Use Cases for Business Initiative:

  • GDP and economic growth analysis
  • Regional economic data (state and county level)
  • Personal income and per capita income
  • Industry-level GDP and value added
  • Business investment and capital stock data
  • International trade and investment data

Available Datasets

NIPA (National Income and Product Accounts)

  • Dataset Name: NIPA
  • Description: Comprehensive data on the U.S. economy including GDP, GNP, personal income, corporate profits, and more
  • Use Case: National economic indicators, GDP analysis, income statistics
  • Tables: T10101 (GDP), T20100 (Personal Income), etc.

Regional

  • Dataset Name: Regional
  • Description: State and county level economic data including personal income, per capita income, employment
  • Use Case: Regional economic analysis, state-by-state comparisons, local market research
  • Tables: CAINC4 (Personal Income), CAINC5 (Per Capita Personal Income), etc.

FixedAssets

  • Dataset Name: FixedAssets
  • Description: Capital stock, investment, and depreciation data
  • Use Case: Business investment trends, capital formation analysis

UnderlyingGDPbyIndustry

  • Dataset Name: UnderlyingGDPbyIndustry
  • Description: Industry-level GDP, value added, gross output, and employment
  • Use Case: Industry performance analysis, sector comparisons

GDPbyIndustry

  • Dataset Name: GDPbyIndustry
  • Description: GDP by industry with detailed industry breakdowns
  • Use Case: Industry economic contribution, sector analysis

InputOutput

  • Dataset Name: InputOutput
  • Description: Input-Output accounts showing inter-industry relationships
  • Use Case: Supply chain analysis, economic impact studies

IntlServTrade

  • Dataset Name: IntlServTrade
  • Description: International trade in services
  • Use Case: Service exports/imports, international business analysis

IntlInvPosFA

  • Dataset Name: IntlInvPosFA
  • Description: International investment position and financial accounts
  • Use Case: Foreign investment, capital flows

ITA

  • Dataset Name: ITA
  • Description: International Transactions Accounts
  • Use Case: Trade balance, current account, capital account

MNE

  • Dataset Name: MNE
  • Description: Multinational Enterprise data
  • Use Case: Foreign direct investment, multinational business analysis

Common Parameters

Required Parameters

  • UserID: Your 36-character BEA API key
  • method: API method (GetDataSetList, GetParameterList, GetData, etc.)
  • ResultFormat: Response format (“JSON” or “XML”, default is JSON)

Dataset-Specific Parameters

For Regional Dataset

TableName
  • Parameter: TableName
  • Description: Table identifier specifying which data table to retrieve
  • Data Type: String
  • Required: Yes (for Regional dataset)
  • Common Values:
    • CAINC1 - Personal Income Summary
    • CAINC4 - Personal Income (detailed)
    • CAINC5 - Per Capita Personal Income
    • CAINC6 - Disposable Personal Income
    • CAINC11 - Personal Income by Major Source
    • CAINC30 - Employment by Place of Work
  • Use Case: Select the type of income/employment data needed
LineCode
  • Parameter: LineCode
  • Description: Line code specifying which data line/item within the table
  • Data Type: String (numeric code)
  • Required: Yes (for Regional dataset)
  • Common Values (for CAINC4):
    • 1 - Total Personal Income
    • 2 - Nonfarm Personal Income
    • 3 - Farm Income
    • 30 - Per Capita Personal Income
  • Use Case: Select specific income measure from the table
GeoFIPS
  • Parameter: GeoFIPS
  • Description: Geographic FIPS code identifying the location
  • Data Type: String (5-digit code or special code)
  • Required: Yes (for Regional dataset)
  • Common Values:
    • STATE - All states (returns data for all 50 states + DC)
    • 01000 - Alabama
    • 06000 - California
    • 36000 - New York
    • 48000 - Texas
    • COUNTY - All counties (use with state context)
  • Use Case: Specify geographic area for data retrieval
  • Note: See “Geographic FIPS Codes” section for complete list
Year
  • Parameter: Year
  • Description: Year or year range for data retrieval
  • Data Type: String
  • Required: Yes (for Regional dataset)
  • Format Options:
    • Single year: "2023"
    • Year range: "2020,2023" (comma-separated)
    • All years: "ALL"
  • Use Case: Specify time period for data
  • Example: "2020,2023" returns data for 2020, 2021, 2022, and 2023

For NIPA Dataset

TableName
  • Parameter: TableName
  • Description: Table identifier for NIPA tables
  • Data Type: String
  • Required: Yes (for NIPA dataset)
  • Common Values:
    • T10101 - Gross Domestic Product (GDP)
    • T20100 - Personal Income and Outlays
    • T30100 - Corporate Profits
    • T40100 - Government Receipts and Expenditures
  • Use Case: Select national economic account table
Frequency
  • Parameter: Frequency
  • Description: Data frequency/timing
  • Data Type: String (single character)
  • Required: Yes (for NIPA dataset)
  • Values:
    • A - Annual data
    • Q - Quarterly data
    • M - Monthly data (if available)
  • Use Case: Specify data frequency needed
Year
  • Parameter: Year
  • Description: Year or year range
  • Data Type: String
  • Required: Yes (for NIPA dataset)
  • Format: Same as Regional dataset (single year, range, or “ALL”)

For GDPbyIndustry Dataset

TableName
  • Parameter: TableName
  • Description: Table identifier for GDP by Industry tables
  • Data Type: String
  • Required: Yes
  • Use Case: Select industry GDP table
Industry
  • Parameter: Industry
  • Description: Industry code (NAICS-based classification)
  • Data Type: String
  • Required: Yes (for GDPbyIndustry dataset)
  • Common Values:
    • ALL - All industries
    • Specific NAICS codes for individual industries
  • Use Case: Filter by specific industry or get all industries
Year
  • Parameter: Year
  • Description: Year or year range
  • Data Type: String
  • Required: Yes
  • Format: Same as other datasets
Frequency
  • Parameter: Frequency
  • Description: Data frequency
  • Data Type: String
  • Required: Yes (for GDPbyIndustry dataset)
  • Values:
    • A - Annual
    • Q - Quarterly
  • Use Case: Specify annual or quarterly industry GDP data

Common Table Names

Regional Dataset Tables

CAINC1

  • Table Name: CAINC1
  • Description: Personal Income Summary
  • Use Case: Overview of personal income by state/county
  • Data Type: Summary table with key income metrics

CAINC4

  • Table Name: CAINC4
  • Description: Personal Income (detailed breakdown)
  • Use Case: Detailed personal income data with multiple line items
  • Data Type: Detailed table with income components
  • Common Line Codes: 1 (Total), 2 (Nonfarm), 3 (Farm), 30 (Per Capita)

CAINC5

  • Table Name: CAINC5
  • Description: Per Capita Personal Income
  • Use Case: Income per person by geography
  • Data Type: Per capita calculations
  • Common Line Codes: 1 (Per Capita Personal Income)

CAINC6

  • Table Name: CAINC6
  • Description: Disposable Personal Income
  • Use Case: Income after taxes, available for spending
  • Data Type: After-tax income measures

CAINC11

  • Table Name: CAINC11
  • Description: Personal Income by Major Source
  • Use Case: Breakdown by income source (wages, property income, etc.)
  • Data Type: Income source analysis

CAINC30

  • Table Name: CAINC30
  • Description: Employment by Place of Work
  • Use Case: Employment statistics by geography
  • Data Type: Employment counts and wages

NIPA Dataset Tables

T10101

  • Table Name: T10101
  • Description: Gross Domestic Product (GDP)
  • Use Case: National GDP, economic growth measurement
  • Data Type: Quarterly and annual GDP data
  • Frequency: Quarterly (Q) or Annual (A)

T20100

  • Table Name: T20100
  • Description: Personal Income and Outlays
  • Use Case: Personal income, disposable income, consumption
  • Data Type: Income and spending data

T30100

  • Table Name: T30100
  • Description: Corporate Profits
  • Use Case: Corporate earnings, profit trends
  • Data Type: Corporate financial data

T40100

  • Table Name: T40100
  • Description: Government Receipts and Expenditures
  • Use Case: Government revenue and spending
  • Data Type: Fiscal data

Common Line Codes

Regional Dataset (CAINC4) - Personal Income

Line Code 1

  • Line Code: 1
  • Description: Total Personal Income
  • Data Type: Millions of dollars (typically)
  • Use Case: Total income for all sources in a geography
  • Example: 3,123,456 (millions) = $3.12 trillion

Line Code 2

  • Line Code: 2
  • Description: Nonfarm Personal Income
  • Data Type: Millions of dollars
  • Use Case: Income excluding farm sources
  • Note: Total income minus farm income

Line Code 3

  • Line Code: 3
  • Description: Farm Income
  • Data Type: Millions of dollars
  • Use Case: Income from agricultural activities
  • Note: Only relevant for agricultural regions

Line Code 30

  • Line Code: 30
  • Description: Per Capita Personal Income
  • Data Type: Dollars per person
  • Use Case: Average income per person in geography
  • Example: 65,432 = $65,432 per capita

Regional Dataset (CAINC5) - Per Capita Personal Income

Line Code 1

  • Line Code: 1
  • Description: Per Capita Personal Income
  • Data Type: Dollars per person
  • Use Case: Average income per person
  • Note: Primary line code for this table

Geographic FIPS Codes

State Codes (5-digit)

  • 01000: Alabama
  • 02000: Alaska
  • 04000: Arizona
  • 05000: Arkansas
  • 06000: California
  • 08000: Colorado
  • 09000: Connecticut
  • 10000: Delaware
  • 12000: Florida
  • 13000: Georgia
  • 15000: Hawaii
  • 16000: Idaho
  • 17000: Illinois
  • 18000: Indiana
  • 19000: Iowa
  • 20000: Kansas
  • 21000: Kentucky
  • 22000: Louisiana
  • 23000: Maine
  • 24000: Maryland
  • 25000: Massachusetts
  • 26000: Michigan
  • 27000: Minnesota
  • 28000: Mississippi
  • 29000: Missouri
  • 30000: Montana
  • 31000: Nebraska
  • 32000: Nevada
  • 33000: New Hampshire
  • 34000: New Jersey
  • 35000: New Mexico
  • 36000: New York
  • 37000: North Carolina
  • 38000: North Dakota
  • 39000: Ohio
  • 40000: Oklahoma
  • 41000: Oregon
  • 42000: Pennsylvania
  • 44000: Rhode Island
  • 45000: South Carolina
  • 46000: South Dakota
  • 47000: Tennessee
  • 48000: Texas
  • 49000: Utah
  • 50000: Vermont
  • 51000: Virginia
  • 53000: Washington
  • 54000: West Virginia
  • 55000: Wisconsin
  • 56000: Wyoming

Special Codes

  • STATE: All states
  • COUNTY: All counties (use with state context)
  • MSA: Metropolitan Statistical Areas

Example API Calls

Example 1: Get List of Available Datasets

GET https://apps.bea.gov/api/data
Parameters:
  UserID: YOUR_API_KEY
  method: GetDataSetList
  ResultFormat: JSON

Example 2: Get Parameters for Regional Dataset

GET https://apps.bea.gov/api/data
Parameters:
  UserID: YOUR_API_KEY
  method: GetParameterList
  datasetname: Regional
  ResultFormat: JSON

Example 3: Personal Income by State (2023)

GET https://apps.bea.gov/api/data
Parameters:
  UserID: YOUR_API_KEY
  method: GetData
  datasetname: Regional
  TableName: CAINC4
  LineCode: 1
  GeoFIPS: STATE
  Year: 2023
  ResultFormat: JSON

Example 4: Per Capita Income for California (2020-2023)

GET https://apps.bea.gov/api/data
Parameters:
  UserID: YOUR_API_KEY
  method: GetData
  datasetname: Regional
  TableName: CAINC5
  LineCode: 1
  GeoFIPS: 06000
  Year: 2020,2023
  ResultFormat: JSON

Example 5: GDP Data (NIPA)

GET https://apps.bea.gov/api/data
Parameters:
  UserID: YOUR_API_KEY
  method: GetData
  datasetname: NIPA
  TableName: T10101
  Frequency: Q
  Year: 2023
  ResultFormat: JSON

Example 6: GDP by Industry

GET https://apps.bea.gov/api/data
Parameters:
  UserID: YOUR_API_KEY
  method: GetData
  datasetname: GDPbyIndustry
  TableName: T10101
  Industry: ALL
  Year: 2023
  Frequency: A
  ResultFormat: JSON

Common Data Requests for Business Initiative

State Economic Comparison

Dataset: Regional
TableName: CAINC4
LineCode: 1 (Total Personal Income) or 30 (Per Capita)
GeoFIPS: STATE
Year: 2023
Use: Compare state economies, identify growth markets

County-Level Analysis

Dataset: Regional
TableName: CAINC4
LineCode: 1
GeoFIPS: 06000 (California) + county codes
Year: 2023
Use: Local market analysis, county economic data

Dataset: NIPA
TableName: T10101
Frequency: Q
Year: 2020,2023
Use: Economic growth trends, business cycle analysis

Industry Performance

Dataset: GDPbyIndustry
TableName: T10101
Industry: [specific NAICS code]
Year: 2023
Use: Industry economic contribution, sector analysis

Response Format

Dataset List Response

{
  "BEAAPI": {
    "Results": {
      "Dataset": [
        {
          "DatasetName": "NIPA",
          "DatasetDescription": "Standard NIPA tables"
        }
      ]
    }
  }
}

Data Response

{
  "BEAAPI": {
    "Results": {
      "Data": [
        {
          "GeoFIPS": "06000",
          "GeoName": "California",
          "Code": "CAINC4",
          "Line": "1",
          "TimePeriod": "2023",
          "CL_UNIT": "Millions of dollars",
          "UNIT_MULT": "6",
          "DataValue": "3,123,456"
        }
      ]
    }
  }
}

Response Field Explanations

GeoFIPS

  • Field: GeoFIPS
  • Description: Geographic FIPS code
  • Data Type: String (5-digit code)
  • Example: "06000" (California)
  • Use Case: Identify the geographic area

GeoName

  • Field: GeoName
  • Description: Human-readable geographic name
  • Data Type: String
  • Example: "California", "Los Angeles County, CA"
  • Use Case: Display-friendly location name

Code

  • Field: Code
  • Description: Table code/identifier
  • Data Type: String
  • Example: "CAINC4", "T10101"
  • Use Case: Identify which table the data comes from

Line

  • Field: Line
  • Description: Line code from the table
  • Data Type: String
  • Example: "1", "30"
  • Use Case: Identify which data line/item this represents

TimePeriod

  • Field: TimePeriod
  • Description: Time period for the data point
  • Data Type: String
  • Format:
    • Annual: "2023"
    • Quarterly: "2023Q1", "2023Q2", etc.
    • Monthly: "2023M01", "2023M02", etc.
  • Use Case: Identify the time period

CL_UNIT

  • Field: CL_UNIT
  • Description: Unit of measurement (clear text)
  • Data Type: String
  • Example: "Millions of dollars", "Dollars", "Percent"
  • Use Case: Understand the data unit

UNIT_MULT

  • Field: UNIT_MULT
  • Description: Unit multiplier (power of 10)
  • Data Type: String (numeric)
  • Values:
    • 0 - Units (no multiplier)
    • 3 - Thousands
    • 6 - Millions
    • 9 - Billions
  • Example: "6" means multiply by 1,000,000 (millions)
  • Use Case: Convert DataValue to actual units

DataValue

  • Field: DataValue
  • Description: The actual data value
  • Data Type: String (numeric value as string)
  • Format: May include commas as thousands separators
  • Example: "3,123,456" with UNIT_MULT=”6” = $3.123456 trillion
  • Use Case: The economic data value
  • Note: Multiply by 10^UNIT_MULT to get actual value in base units

Data Limitations & Notes

  1. API Key Required: Must register at https://apps.bea.gov/api/signup/
  2. Rate Limits: Reasonable use limits (not explicitly stated, but be respectful)
  3. Data Availability: Not all datasets available for all time periods
  4. Data Lag: Economic data typically available 1-2 months after reference period
  5. Geographic Detail: County-level data may require state context
  6. Year Format: Can use single year, comma-separated range, or “ALL”
  7. Result Format: Default is JSON, can specify XML

MCP Tool Usage

Get Dataset List

Tool Name: fetch_bea_dataset_list

Description: Get list of all available BEA datasets.

Example Call:

{}

Response: Returns array of datasets with names and descriptions.

Get Parameter List

Tool Name: fetch_bea_parameter_list

Description: Get available parameters for a specific dataset.

Example Call:

{
  "dataset_name": "Regional"
}

Response: Returns parameters and their descriptions for the dataset.

Get Data

Tool Name: fetch_bea_data

Description: Fetch economic data from BEA datasets.

Example Call:

{
  "dataset_name": "Regional",
  "table_name": "CAINC4",
  "line_code": "1",
  "geo_fips": "STATE",
  "year": "2023"
}

Response: Returns economic data with geographic and time period information.

Finding Dataset Information

Method 1: Get Dataset List

Use fetch_bea_dataset_list to see all available datasets.

Method 2: Get Parameter List

Use fetch_bea_parameter_list with a dataset name to see available parameters and tables.

Method 3: BEA Website

  • URL: https://www.bea.gov/data
  • Browse datasets and tables interactively
  • Export data to see API parameters

Method 4: BEA API Documentation

  • User Guide: https://apps.bea.gov/api/_pdf/bea_web_service_api_user_guide.pdf
  • Interactive API: https://apps.bea.gov/api/signup/

References

  • Official Documentation: https://apps.bea.gov/api/
  • API User Guide: https://apps.bea.gov/api/_pdf/bea_web_service_api_user_guide.pdf
  • API Registration: https://apps.bea.gov/api/signup/
  • BEA Data Portal: https://www.bea.gov/data
  • Regional Data: https://www.bea.gov/data/economic-accounts/regional