AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

database-lookup

Queries documented public database APIs with explicit endpoints, filters, pagination, and provenance. Used when a scientific, regulatory, financial, or other database-backed fact must be retrieved reproducibly from a named source rather than inferred from general knowledge.

Original source
K-Dense-AI
License
MIT
Pinned revision
5f2bc0341354fd5590aef76a533ada1e1e5b4e62

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read k-dense-ai--database-lookup at revision 5f2bc0341354fd5590aef76a533ada1e1e5b4e62, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 83

references/bea.md

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/X for all years; prefer an explicit bounded range. |

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 county and metropolitan area). | | 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 county/metropolitan area | | CAGDP2 | GDP by county/metropolitan area; check current table description | | CAGDP9 | Real GDP by county/metropolitan area | | 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 | Percent change in prices for GDP | | 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.

Use GetParameterValues for current table/line labels and GetParameterValuesFiltered for valid combinations; special year values are dataset-specific. State GDP tables use the SAGDP family. Source: https://apps.bea.gov/api/_pdf/bea_web_service_api_user_guide.pdf