📄 / / profiles / r-and-d / raw_evidence / scientific-agent-skills / skills / database-lookup / references / bea.md

BEA (Bureau of Economic Analysis) API Reference

BEA (Bureau of Economic Analysis) API Reference

Overview

The Bureau of Economic Analysis API provides access to U.S. economic accounts data including GDP (national income and product accounts -- NIPA), personal income, international trade, industry accounts, and regional economic data. Structured as a single endpoint with dataset-specific parameters.

Base URL

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

Authentication

API Key: REQUIRED. Register at https://apps.bea.gov/API/signup/
Pass as query parameter: &UserID=YOUR_API_KEY

Rate Limits

100 requests per minute per API key.
100 MB of data per minute per API key.
30 errors per minute -- exceeding triggers a temporary lockout.
Daily and monthly limits are not formally published but BEA may throttle heavy use.

Common Parameters (all requests)

Parameter	Type	Required	Description
`UserID`	string	Yes	Your BEA API key.
`method`	string	Yes	API method (see below).
`ResultFormat`	string	No	`JSON` (default) or `XML`.

Methods

1. GetDataSetList

Lists all available datasets.

`GET /api/data?method=GetDataSetList&UserID=YOUR_KEY&ResultFormat=JSON`

Example:

https://apps.bea.gov/api/data?method=GetDataSetList&UserID=YOUR_KEY&ResultFormat=JSON

Response:

{
  "BEAAPI": {
    "Request": {
      "RequestParam": [
        {"ParameterName": "METHOD", "ParameterValue": "GETDATASETLIST"},
        {"ParameterName": "RESULTFORMAT", "ParameterValue": "JSON"}
      ]
    },
    "Results": {
      "Dataset": [
        {"DatasetName": "NIPA", "DatasetDescription": "Standard NIPA tables"},
        {"DatasetName": "NIUnderlyingDetail", "DatasetDescription": "National Income and Product Accounts Underlying Detail"},
        {"DatasetName": "MNE", "DatasetDescription": "Multinational Enterprises"},
        {"DatasetName": "FixedAssets", "DatasetDescription": "Fixed Assets"},
        {"DatasetName": "ITA", "DatasetDescription": "International Transactions"},
        {"DatasetName": "IIP", "DatasetDescription": "International Investment Position"},
        {"DatasetName": "GDPbyIndustry", "DatasetDescription": "GDP by Industry"},
        {"DatasetName": "Regional", "DatasetDescription": "Regional data"},
        {"DatasetName": "UnderlyingGDPbyIndustry", "DatasetDescription": "Underlying GDP by Industry"},
        {"DatasetName": "InputOutput", "DatasetDescription": "Input-Output Statistics"}
      ]
    }
  }
}

2. GetParameterList

Lists parameters for a specific dataset.

`GET /api/data?method=GetParameterList&DatasetName={dataset}&UserID=YOUR_KEY&ResultFormat=JSON`

Example:

https://apps.bea.gov/api/data?method=GetParameterList&DatasetName=NIPA&UserID=YOUR_KEY&ResultFormat=JSON

Response:

{
  "BEAAPI": {
    "Results": {
      "Parameter": [
        {
          "ParameterName": "TableName",
          "ParameterDataType": "string",
          "ParameterDescription": "The standard NIPA table identifier",
          "ParameterIsRequiredFlag": "1",
          "ParameterDefaultValue": ""
        },
        {
          "ParameterName": "Frequency",
          "ParameterDataType": "string",
          "ParameterDescription": "A - Annual, Q - Quarterly, M - Monthly",
          "ParameterIsRequiredFlag": "1",
          "ParameterDefaultValue": ""
        },
        {
          "ParameterName": "Year",
          "ParameterDataType": "string",
          "ParameterDescription": "List of year(s) of data to retrieve",
          "ParameterIsRequiredFlag": "1",
          "ParameterDefaultValue": ""
        }
      ]
    }
  }
}

3. GetParameterValues

Lists valid values for a parameter.

`GET /api/data?method=GetParameterValues&DatasetName={dataset}&ParameterName={param}&UserID=YOUR_KEY&ResultFormat=JSON`

Example (list NIPA tables):

https://apps.bea.gov/api/data?method=GetParameterValues&DatasetName=NIPA&ParameterName=TableName&UserID=YOUR_KEY&ResultFormat=JSON

Response (abbreviated):

{
  "BEAAPI": {
    "Results": {
      "ParamValue": [
        {"TableName": "T10101", "Description": "Table 1.1.1. Percent Change From Preceding Period in Real Gross Domestic Product"},
        {"TableName": "T10106", "Description": "Table 1.1.6. Real Gross Domestic Product, Chained Dollars"},
        {"TableName": "T10105", "Description": "Table 1.1.5. Gross Domestic Product"},
        {"TableName": "T20100", "Description": "Table 2.1. Personal Income and Its Disposition"},
        {"TableName": "T30100", "Description": "Table 3.1. Government Current Receipts and Expenditures"}
      ]
    }
  }
}

4. GetData

The main data retrieval method. Parameters vary by dataset.

`GET /api/data?method=GetData&DatasetName={dataset}&{params}&UserID=YOUR_KEY&ResultFormat=JSON`

Dataset-Specific Parameters & Examples

A. NIPA (National Income and Product Accounts)

Parameters: | Parameter | Type | Required | Description | |------------|--------|----------|-------------| | TableName| string | Yes | NIPA table identifier (e.g., T10101). | | Frequency| string | Yes | A (annual), Q (quarterly), M (monthly). | | Year | string | Yes | Comma-separated years, or ALL, or X for latest. |

Example (Real GDP percent change, quarterly, 2022-2024):

https://apps.bea.gov/api/data?method=GetData&DatasetName=NIPA&TableName=T10101&Frequency=Q&Year=2022,2023,2024&UserID=YOUR_KEY&ResultFormat=JSON

Example (GDP levels, annual, all years):

https://apps.bea.gov/api/data?method=GetData&DatasetName=NIPA&TableName=T10105&Frequency=A&Year=ALL&UserID=YOUR_KEY&ResultFormat=JSON

Response:

{
  "BEAAPI": {
    "Request": { ... },
    "Results": {
      "Statistic": "NIPA Table",
      "UTCProductionTime": "2024-11-01T13:00:00.000",
      "Dimensions": [
        {"Name": "TableName", "DataType": "string", "IsValue": "0"},
        {"Name": "SeriesCode", "DataType": "string", "IsValue": "0"},
        {"Name": "LineNumber", "DataType": "numeric", "IsValue": "0"},
        {"Name": "LineDescription", "DataType": "string", "IsValue": "0"},
        {"Name": "TimePeriod", "DataType": "string", "IsValue": "0"},
        {"Name": "METRIC_NAME", "DataType": "string", "IsValue": "0"},
        {"Name": "CL_UNIT", "DataType": "string", "IsValue": "0"},
        {"Name": "UNIT_MULT", "DataType": "numeric", "IsValue": "0"},
        {"Name": "DataValue", "DataType": "numeric", "IsValue": "1"}
      ],
      "Data": [
        {
          "TableName": "T10101",
          "SeriesCode": "A191RL",
          "LineNumber": "1",
          "LineDescription": "Gross domestic product",
          "TimePeriod": "2022Q1",
          "METRIC_NAME": "Fisher Quantity Index",
          "CL_UNIT": "Percent change",
          "UNIT_MULT": "0",
          "DataValue": "-1.6",
          "NoteRef": "T10101"
        },
        {
          "TableName": "T10101",
          "SeriesCode": "A191RL",
          "LineNumber": "1",
          "LineDescription": "Gross domestic product",
          "TimePeriod": "2022Q2",
          "CL_UNIT": "Percent change",
          "DataValue": "-0.6"
        }
      ],
      "Notes": [
        {"NoteRef": "T10101", "NoteText": "Table 1.1.1. Percent Change From Preceding Period..."}
      ]
    }
  }
}

B. Regional (State, County, MSA data)

Parameters: | Parameter | Type | Required | Description | |--------------|--------|----------|-------------| | TableName | string | Yes | Regional table (e.g., CAGDP1 for GDP by state). | | LineCode | int | Yes | Line number within the table (specifies the data series). | | GeoFips | string | Yes | FIPS code: STATE (all states), COUNTY (all counties), MSA (all MSAs), or specific FIPS (e.g., 06000 for California). | | Year | string | Yes | Comma-separated years or ALL or LAST5. |

Common Regional Tables: | Table | Description | |-------|-------------| | CAGDP1 | GDP summary by state | | CAGDP2 | GDP by component by state | | CAGDP9 | Real GDP by state | | CAINC1 | Personal income summary by state | | CAINC4 | Personal income and employment by state | | CAINC5N | Personal income by type by state | | SAINC1 | State annual personal income | | SQINC1 | State quarterly personal income |

Example (GDP by state, all states, 2020-2023):

https://apps.bea.gov/api/data?method=GetData&DatasetName=Regional&TableName=CAGDP1&LineCode=1&GeoFips=STATE&Year=2020,2021,2022,2023&UserID=YOUR_KEY&ResultFormat=JSON

Example (Personal income for California):

https://apps.bea.gov/api/data?method=GetData&DatasetName=Regional&TableName=CAINC1&LineCode=1&GeoFips=06000&Year=LAST5&UserID=YOUR_KEY&ResultFormat=JSON

Response:

{
  "BEAAPI": {
    "Results": {
      "Data": [
        {
          "GeoFips": "06000",
          "GeoName": "California",
          "Code": "CAINC1-1",
          "TimePeriod": "2023",
          "CL_UNIT": "Thousands of dollars",
          "UNIT_MULT": "3",
          "DataValue": "3,220,965,123"
        }
      ]
    }
  }
}

C. ITA (International Transactions Accounts / Trade)

Parameters: | Parameter | Type | Required | Description | |-------------|--------|----------|-------------| | Indicator | string | Yes | Indicator code (e.g., BalGds for goods balance). | | AreaOrCountry | string | Yes | Country code: AllCountries, China, Japan, etc., or All. | | Frequency | string | Yes | A, Q, M. | | Year | string | Yes | Comma-separated years or ALL. |

Common ITA Indicators: | Code | Description | |------|-------------| | BalGds | Balance on goods | | BalServ | Balance on services | | BalGdsServ | Balance on goods and services | | BalCurAcct | Current account balance | | ExpGds | Exports of goods | | ImpGds | Imports of goods | | ExpServ | Exports of services | | ImpServ | Imports of services |

Example (US trade balance in goods with China, quarterly):

https://apps.bea.gov/api/data?method=GetData&DatasetName=ITA&Indicator=BalGds&AreaOrCountry=China&Frequency=Q&Year=2022,2023,2024&UserID=YOUR_KEY&ResultFormat=JSON

D. GDPbyIndustry

Parameters: | Parameter | Type | Required | Description | |-------------|--------|----------|-------------| | TableID | int | Yes | Table number (1-15). | | Industry | string | Yes | Industry code: ALL, or specific (e.g., 11 for agriculture). | | Frequency | string | Yes | A or Q. | | Year | string | Yes | Comma-separated years or ALL. |

Common Table IDs: | ID | Description | |----|-------------| | 1 | Value added by industry | | 5 | Value added by industry as % of GDP | | 6 | Real value added by industry | | 7 | Percent change in real value added by industry |

Example (Value added by all industries, annual):

https://apps.bea.gov/api/data?method=GetData&DatasetName=GDPbyIndustry&TableID=1&Industry=ALL&Frequency=A&Year=2020,2021,2022,2023&UserID=YOUR_KEY&ResultFormat=JSON

E. IIP (International Investment Position)

Parameters: | Parameter | Type | Required | Description | |----------------|--------|----------|-------------| | TypeOfInvestment | string | Yes | ALL, FinAssetsExclFinDeriv, etc. | | Component | string | Yes | ALL or specific component. | | Frequency | string | Yes | A or Q. | | Year | string | Yes | Comma-separated years or ALL. |

Example:

https://apps.bea.gov/api/data?method=GetData&DatasetName=IIP&TypeOfInvestment=ALL&Component=ALL&Frequency=A&Year=2020,2021,2022,2023&UserID=YOUR_KEY&ResultFormat=JSON

F. FixedAssets

Parameters: | Parameter | Type | Required | Description | |------------|--------|----------|-------------| | TableName| string | Yes | Fixed asset table ID. | | Year | string | Yes | Comma-separated years or ALL. |

Example:

https://apps.bea.gov/api/data?method=GetData&DatasetName=FixedAssets&TableName=FAAt101&Year=ALL&UserID=YOUR_KEY&ResultFormat=JSON

Key NIPA Table Reference

TableName	Description
`T10101`	Percent change in real GDP
`T10105`	GDP (current dollars)
`T10106`	Real GDP (chained 2017 dollars)
`T10107`	GDP price index (percent change)
`T10110`	GDP price deflator
`T20100`	Personal income and its disposition
`T20301`	Personal consumption expenditures by type
`T20600`	Personal income and outlays
`T30100`	Government current receipts and expenditures
`T40100`	Foreign transactions in the national accounts
`T50100`	Saving and investment by sector
`T50105`	Saving and investment (real)
`T60100`	Corporate profits
`T70100`	GDP by major type of product
`T11000`	Real GDP, expanded detail
`T11200`	Contributions to GDP growth

GeoFips Reference (Common)

FIPS	State
`00000`	United States
`01000`	Alabama
`06000`	California
`12000`	Florida
`36000`	New York
`48000`	Texas
`STATE`	All states
`COUNTY`	All counties
`MSA`	All metropolitan statistical areas

Notes

DataValue in responses is a string, sometimes with commas (e.g., "3,220,965,123"). Parse by removing commas.
Year=X returns only the most recent year available.
Year=LAST5 returns the 5 most recent years.
For NIPA tables, results contain multiple line items per table (different GDP components are different LineNumbers).
The GetParameterValues method is essential for discovering valid table names, line codes, and indicator codes for each dataset.
BEA also provides bulk download files at https://apps.bea.gov/iTable/ for interactive use.
Time periods for quarterly data use format 2024Q1, 2024Q2, etc.
All monetary values are in U.S. dollars unless otherwise specified. Units are indicated in CL_UNIT and UNIT_MULT fields.