0% found this document useful (0 votes)
115 views65 pages

BEA API Data Retrieval User Guide

The BEA API User Guide provides instructions for accessing economic statistics published by the Bureau of Economic Analysis (BEA) through a programmatic interface. Users must register to obtain a unique UserID and can retrieve data using specific methods and parameters, with support for various programming languages including JavaScript. The guide also details error handling, rate limiting, and the structure of data and metadata responses from the API.

Uploaded by

isrellanakasi
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd
0% found this document useful (0 votes)
115 views65 pages

BEA API Data Retrieval User Guide

The BEA API User Guide provides instructions for accessing economic statistics published by the Bureau of Economic Analysis (BEA) through a programmatic interface. Users must register to obtain a unique UserID and can retrieve data using specific methods and parameters, with support for various programming languages including JavaScript. The guide also details error handling, rate limiting, and the structure of data and metadata responses from the API.

Uploaded by

isrellanakasi
Copyright
© All Rights Reserved
We take content rights seriously. If you suspect this is your content, claim it here.
Available Formats
Download as PDF, TXT or read online on Scribd

BEA API for Data Retrieval

User Guide
Introduction
The Bureau of Economic Analysis (BEA) publishes economic statistics in a variety of formats. This document
describes the BEA Data Retrieval Application Programming Interface (API) – including detailed instructions
for retrieving data and meta-data published by BEA. The API is intended to provide programmatic access to
published economic statistics using industry-standard methods and procedures. The intended audience of this
document is programmers who are familiar with the concepts and techniques of retrieving data from Web
Services.

The BEA API includes methods for retrieving a subset of BEA statistical data, and meta-data that describes it.
As additional datasets are added, the meta-data retrieval methods can be used to discover the current data
accessible through the API.

Access to the BEA API


The API is available to registered users on the BEA public web site. Before using the API, users must obtain a
unique 36-character UserID by registering at https:/[Link]/api/signup/ . To register, API users must
provide their name (or organization name), a valid email address (see note #1 below) and agree to the
published terms of service. After completing the registration form an email is sent containing the assigned
UserID, and a link that completes the registration process. Assigned UserIDs are activated when the link has
been clicked.

NOTES:
1. To prevent abuse, BEA does not permit users to register for an API key with a disposable email
address.
2. In mid-2018, BEA restructured its website and created a new subdomain, [Link], to host all
dynamic, database-driven web applications referenced from the primary domain, [Link].
While API registration and documentation links remain on the primary domain, the URI for the API is
accessed on the [Link] subdomain, as shown below.

The URI 1 of the API is: [Link] All API access is through this URI; no other paths are
0F

used. Data is retrieved by sending an HTTP GET to the URI with appropriate (querystring) parameters supplied.
The minimum parameters for every request include the UserID and the name of the method being invoked. For
example:

[Link]

would retrieve a list of the datasets currently offered by the BEA API (if the UserID was valid – it’s not).

Statistical data offered by the API is organized into defined “Datasets”. An API data retrieval request always
specifies one dataset by name. Each dataset has a number of defined parameters, and each parameter has a
defined set of valid values. There are four API methods that return meta-data about the API – corresponding to
1
Uniform Resource Identifier

Page 1 of 15 November 12, 2024


datasets, parameters, and valid parameter values. There is one method that returns data.

JavaScript Usage
While the API may be used from any language capable of issuing HTTP requests (Java, PHP, Perl, Python, C,
etc. ), two features are supported that allow JavaScript to issue requests without violating same-origin security
checks - CORS and JSONP.

If you're writing a browser-based web application for modern web browsers with support for CORS then you
may simply use an XMLHttpRequest as usual, without any changes. All HTTP responses generated by the API
will include the necessary CORS headers.

If you're writing a browser-based web application for legacy browsers without support for CORS then your
request URL query string may include a jsonp argument. If present, this prefix will be wrapped around the
response, allowing you to capture the result of the query.

For example:
[Link]
Key&method=GetData&datasetname=Regional&TableName=CAINC4&LineCode=30&GeoFIPS=COUNTY
&Year=2013&ResultFormat=json&jsonp=MY_FUNCTION_NAME

Data Return Format


The API returns data in one of two formats: JSON2 or XML 3. The optional ResultFormat parameter can be
included on any request to specify the format of the results. If ResultFormat is not supplied on the request, or an
invalid ResultFormat is specified, the default format returned is JSON.

The valid values for ResultFormat are “JSON” and “XML”. For example, the following request would return a
list of the available datasets in XML format:
[Link]
Key&method=GETDATASETLIST&ResultFormat=XML

This request would return a list of the available datasets in JSON format:
[Link]
Key&method=GETDATASETLIST&ResultFormat=JSON

The data returned from the API always has the following basic structure, with some additional structure
depending on the data requested:
<BEAAPI>
<Request>
<RequestParam ParameterValue="GETDATASETLIST" ParameterName="METHOD"/>
<RequestParam ParameterValue=" Your-36Character-Key" ParameterName="USERID"/>
<RequestParam ParameterValue="XML" ParameterName="RESULTFORMAT"/>
</Request>
<Dataset DatasetDescription="Standard NIPA tables" DatasetName="NIPA"/>
<Dataset DatasetDescription="Standard NI underlying detail tables" DatasetName="NIUnderlyingDetail"/>
<Dataset DatasetDescription="Multinational Enterprises" DatasetName="MNE"/>
<Dataset DatasetDescription="Standard Fixed Assets tables" DatasetName="FixedAssets"/>
<Dataset DatasetDescription="International Transactions Accounts" DatasetName="ITA"/>
<Dataset DatasetDescription="International Investment Position" DatasetName="IIP"/>
<Dataset DatasetDescription="GDP by Industry" DatasetName="GDPbyIndustry"/>
<Dataset DatasetDescription="Regional data sets" DatasetName="Regional"/>
</Results>
</BEAAPI>

2
Java Script Object Notation
3
Extensible Markup Language

Page 2 of 15 November 12, 2024


In XML form, the root node is always <BEAAPI>, followed by the child node <Request>. The <Request> node
contains <RequestParam> children that echo the parameters passed in the request. The root node, <BEAAPI>,
then has another child node, <Results>, containing the results of the request. The Results content is different
depending on the method and parameters passed. In this example, the result of the GetDatasetList method is
shown to be a simple list of Dataset names and descriptions.

In JSON form, the example above returns data as follows (white-space and indentation added for clarity):
{
"BEAAPI":{
"Request"
:{
"RequestParam":[
{
"ParameterName":"USERID",
"ParameterValue":" Your-
36Character-Key "
},
{
"ParameterName":"RESULTFORMAT",
"ParameterValue":"JSON"
},
{
"ParameterName":"METHOD",
"ParameterValue":"GETDATASETLIST
"
}
]
},
"Results":{
"Dataset
":[
{
"DatasetName":"NIPA",
"DatasetDescription":"Standard NIPA
tables"
},
{
"DatasetName":"NIUnderlyingDetail",
"DatasetDescription":"Standard NI underlying
detail tables"
},
{
"DatasetName":"MNE",
"DatasetDescription":"Multinational
Enterprises"
},
{
"DatasetName":"FixedAssets",
"DatasetDescription":"Standard Fixed
Assets tables"
},
{
"DatasetName":"ITA",
"DatasetDescription":"International Transactions Accounts"
},
{
"DatasetName":"IIP",
"DatasetDescription":"International Investment Position"
},
{
"DatasetName":"GDPbyIndustry",
"DatasetDescription":"GDP by
Industry"
},
{
"DatasetName":"Regional",
"DatasetDescription":"Regional data sets"
}

]
}
}
}

Page 3 of 15 November 12, 2024


Error Return Format
When invalid values are supplied for parameters in a request, or required parameters are missing, the results
contain an error message – for example:
<BEAAPI>
<Request>
<RequestParam ParameterName="USERID" ParameterValue="Your-36Character-Key" />
<RequestParam ParameterName="METHOD" ParameterValue="GETDATASETLIST" />
<RequestParam ParameterName="ResultFormat" ParameterValue="XML" />
</Request>
<Results>
<Error APIErrorCode="3" APIErrorDescription="The BEA API UserID provided in the request does not exist. " />
</Results>
</BEAAPI>

API Calling Limits (rate limiting)

NOTE:
These limits have periodically been adjusted since the API’s inception and will continue to be
evaluated and adjusted as needed to protect BEA’s API and webserver infrastructure from extreme
and/or abusive activity that may be detrimental to our infrastructure and/or unfairly impede other
API users.

The BEA API implements a throttling (rate limiting) mechanism to protect our servers from resource contention,
and to promote a fair opportunity for all users to share resources and retrieve data.

Here’s how the throttling mechanism works:

There are three standard limits applied for all API user accounts:
• Number of requests per minute (100), and or
• Data volume retrieved per minute (100 MB), and/or
• Errors per minute (30)

When any of these limits are exceeded by an API user in the previous minute, that user will receive an error for
any additional requests for a time-out period of one hour.

Example Error Response in XML Format:

<BEAAPI>
<Request>
...
</Request>
<Results>
<Error APIErrorCode="1" APIErrorDescription="Request Denied - exceeded Volume per minute
quota."/>
</Results>
</BEAAPI>

Page 4 of 15 November 12, 2024


In addition, each throttling error response will return an HTTP 429 (too many requests) status code and include
a RETRY-AFTER header indicating how long to wait (in seconds) before making a new request.

Example Header Response:

HTTP/1.1 429 Requests


Transfer-Encoding: chunked
Content-Type: application/xml;charset=ISO-8859-1
Age: 0
Retry-After: 3600
Server: Microsoft-IIS/10.0
… … …

If you make any subsequent API requests during the time-out period, the HTTP 429 response header will
decrement the RETRY-AFTER value until the time-out period is over, based on the starting timestamp.

Here are some techniques to minimize or eliminate throttling while using the BEA API:

1. Be informed about published release schedules ([Link] The API data in


different datasets is typically published according to schedules that provide monthly data updates (with
some exceptions). The release of all updated API data is on the same release schedule as other published
sources of BEA data (e.g. Interactive Tables). Automating API retrievals to obtain data that has not been
updated is discouraged.
2. Monitor the number of requests and volume of data received by your program. By tracking the actual
number of requests submitted, and the actual volume of data received, and pausing request activity when
the stated throttling limits are approached, you can eliminate all throttling.
3. Include logic in your client software to recognize when a throttling error is received (based on the HTTP
429 status code, and HTTP RETRY-AFTER header). If a throttling event occurs, pause retrieval activity
for the throttle timeout period (1 hour / 3600 seconds) before attempting additional requests. Responding
to requests that are throttled requires bandwidth and server resources that contribute to our need for
throttling.
4. Develop single-threaded client programs that wait for a result before submitting a new request. While
multi-threaded asynchronous requests are allowed, our throttling limits are tuned such that no single
request would trigger throttling, and (serial) single-threaded requests would rarely trigger throttling.
5. Do not overuse the special values “ALL” or “X”. Depending on the dataset, some parameters (e.g.,
YEAR) permit the “ALL” or “X” special value to fetch all data for that given parameter. This can yield
extraordinarily large data results, which take longer to prepare and can tax the backend databases.
Limiting the use of the “ALL” or “X” special value to just one parameter is an effective method to
regulate the size of API result volume.

Meta-Data API Methods


The API contains three methods for retrieving meta-data as follows:

G et D at a S et L i st – retrieves a list of the datasets currently

Page 5 of 15 November 12, 2024


offered. Required Parameters: UserID, Method
Optional Parameters: ResultFormat

Result: Dataset node with DatasetName and DatasetDescription

attributes. Example Request:

[Link]
36Character-
Key&method=GETDATASETLIST&ResultFormat=XML
&ResultFormat=XML&

Example Return:
<BEAAPI>
<Request>
<RequestParam ParameterValue="GETDATASETLIST" ParameterName="METHOD"/>
<RequestParam ParameterValue="Your-36Character-Key" ParameterName="USERID"/>
<RequestParam ParameterValue="XML" ParameterName="RESULTFORMAT"/>
</Request>
<Results>
<Dataset DatasetDescription="Standard NIPA tables" DatasetName="NIPA"/>
<Dataset DatasetDescription="Standard NI underlying detail tables" DatasetName="NIUnderlyingDetail"/>
<Dataset DatasetDescription="Multinational Enterprises" DatasetName="MNE"/>
<Dataset DatasetDescription="Regional data sets" DatasetName="Regional"/>
<Dataset DatasetDescription="Standard Fixed Assets tables" DatasetName="FixedAssets"/>
<Dataset DatasetDescription="International Transactions Accounts" DatasetName="ITA"/>
<Dataset DatasetDescription="International Investment Position" DatasetName="IIP"/>
<Dataset DatasetDescription="GDP by Industry" DatasetName="GDPbyIndustry"/>
</Results>
</BEAAPI>

The RegionalData, RegionalIncome, and RegionalProduct data sets are obsolete and API calls using
these data sets will no longer function. Users should instead access the dataset Regional, which
provides comprehensive detail in statistics, industries, geography, and years. See Appendix N for
instructions on how to use the Regional data set. In addition, BEA continues to add new datasets as
appropriate, and while any new datasets will be announced on the BEA’s website Developers page
([Link] we also encourage users to periodically call the above
GETDATASETLIST discover new datasets.

G et P a ra m et er L i st – retrieves a list of the parameters (required and optional) for a particular dataset.

Required Parameters: UserID, Method, DatasetName


Optional Parameters: ResultFormat

Result: Parameter node with attributes:


• ParameterName – the name of the parameter as used in a data request
• ParameterDataType – String or Integer
• ParameterDescription – a description of the parameter
• ParameterIsRequired – 0 if the parameter can be omitted from a request, 1 if required
• ParameterDefaultValue – the default value used for the request if the parameter is not supplied
• MultipleAcceptedFlag – 0 if the parameter may only have a single value, 1 if multiple values
are permitted. Note that multiple values for a parameter are submitted as a comma-separated
string.
• AllValue – the special value for a parameter that means all valid values are used without supplying

Page 6 of 15 November 12, 2024


them individually.

Example Request 1:

[Link]
Key&method=getparameterlist&datasetname=Regional&ResultFormat=XML

Example Return 1:
<BEAAPI>
<Request>
<RequestParam ParameterName="USERID" ParameterValue="Your-36Character-Key" />
<RequestParam ParameterName="METHOD" ParameterValue="GetParameterList" />
<RequestParam ParameterName="DatasetName" ParameterValue="Regional" />
<RequestParam ParameterName="ResultFormat" ParameterValue="XML" />
</Request>
<Results>
<Parameter ParameterName="GeoFips" MultipleAcceptedFlag="1" ParameterIsRequiredFlag="1"
ParameterDataType="string" ParameterDescription="Comma-delimited list of 5-character geographic codes;
COUNTY for all counties, STATE for all states, MSA for all MSAs, MIC for all Micropolitan Areas, PORT for
all state metro/nonmetro portions, DIV for all Metropolitan Divisions, CSA for all Combined Statistical
Areas, state post office abbreviation for all counties in one state (e.g. NY)" />
<Parameter ParameterName="TableName" MultipleAcceptedFlag="0" ParameterIsRequiredFlag="1" ParameterDataType="string"
ParameterDescription="Income or employment table to retrieve" />
<Parameter ParameterName="LineCode" MultipleAcceptedFlag="0" ParameterIsRequiredFlag="1" ParameterDataType="integer"
ParameterDescription="Line code for a statistic or industry"/>
<Parameter ParameterName="Year" MultipleAcceptedFlag="1" ParameterIsRequiredFlag="0" ParameterDescription="Comma-delimted
list of years; LAST5 for latest 5 years; LAST10 for latest 10 years; ALL for all years" ParameterDefaultValue="LAST5"
ParameterDataType="string" />
</Results>
</BEAAPI>

In this example, the parameters for the “Regional” dataset are being requested. The results indicate that the
dataset has four parameters: GeoFips, LineCode, TableName, and Year.

GeoFips is a string typed parameter indicating the geographic codes requested. GeoFIPS is required.
Multiple values are accepted, in a comma-delimited list, and there are special values such as COUNTY for
all counties.

TableName is a string typed parameter that specifies what table has the statistic requested. We can’t tell from
this what the valid TableNames are, but we can see that it is required (and therefore has no default value), and
that multiple values are not allowed (and therefore there is no special “all” value).

LineCode specifies the requested statistic in the table. This integer is the line code in the table specified in the
TableName parameter. We don’t know what these line codes are, but we can send another request to find out.

Year is a string typed parameter containing the years requested. It is not required in a request, and if is not
included, the default value used is “LAST5”. A comma-delimited list of years is accepted, as well as other
special values like “LAST10” and “ALL”.

Example Request 2:

[Link]
IntlServTrade&ResultFormat=XML

Example Return 2:
<BEAAPI>
<Request>
<RequestParam ParameterValue="XML" ParameterName="RESULTFORMAT"/>
<RequestParam ParameterValue="Your-36Character-Key" ParameterName="USERID"/>

Page 7 of 15 November 12, 2024


<RequestParam ParameterValue="INTLSERVTRADE" ParameterName="DATASETNAME"/>
<RequestParam ParameterValue="GETPARAMETERLIST" ParameterName="METHOD"/>
</Request>
<Results>
<Parameter ParameterName="TypeOfService" AllValue="ALL" MultipleAcceptedFlag="1" ParameterDefaultValue="ALL"
ParameterIsRequiredFlag="0" ParameterDescription="The type of service requested" ParameterDataType="string"/>
<Parameter ParameterName="TradeDirection" AllValue="ALL" MultipleAcceptedFlag="1" ParameterDefaultValue="ALL"
ParameterIsRequiredFlag="0" ParameterDescription="The type of trade direction requested"
ParameterDataType="string"/>
<Parameter ParameterName="Affiliation" AllValue="ALL" MultipleAcceptedFlag="1" ParameterDefaultValue="ALL"
ParameterIsRequiredFlag="0" ParameterDescription="The affiliation requested" ParameterDataType="string"/>
<Parameter ParameterName="AreaOrCountry" AllValue="ALL" MultipleAcceptedFlag="1" ParameterDefaultValue="AllCountries"
ParameterIsRequiredFlag="0" ParameterDescription="The area or country requested" ParameterDataType="string"/>
<Parameter ParameterName="Year" AllValue="ALL" MultipleAcceptedFlag="1" ParameterDefaultValue="ALL"
ParameterIsRequiredFlag="0" ParameterDescription="The year requested" ParameterDataType="string"/>
</Results>
</BEAAPI>

In this example, the parameters for the “IntlServTrade” dataset are being requested. The results indicate that
the dataset has five parameters: TypeOfService, TradeDirection, Affiliation, AreaOrCountry, and Year.

TypeOfService is a string typed parameter described as the type of service. It is not required. Multiple values
are accepted, and there is a value to select all types of service, “All”.

The other parameters have characteristics like the first. To get more information about the parameters,
“GetParameterValues” should be used.

G et P a ra m et erV a lu es – retrieves a list of the valid values for a particular

parameter. Required Parameters: UserID, Method, DatasetName, ParameterName


Optional Parameters: ResultFormat

Result: ParamValue node with attributes that contain the actual permissible values (and usually a description
of the value).

Example Request 1:

[Link]
Key&method=GetParameterValues&datasetname=INTLSERVTRADE&ParameterName=Tra
deDirection&ResultFormat=XML

Example Return 1:
<BEAAPI>
<Request>
<RequestParam ParameterName="USERID" ParameterValue="Your-36Character-Key" />
<RequestParam ParameterName="METHOD" ParameterValue="GetParameterValues" />
<RequestParam ParameterName="DatasetName" ParameterValue=INTLSERVTRADE" />
<RequestParam ParameterName="ParameterName" ParameterValue="TRADEDIRECTION" />
<RequestParam ParameterName="ResultFormat" ParameterValue="XML" />
</Request>
<Results>
<ParamValue Desc="Balance” Key="Balance"/>
<ParamValue Desc="Exports" Key="Exports"/>
<ParamValue Desc="Imports" Key="Imports"/>
<ParamValue Desc="Supplemental detail on insurance transactions" Key="SupplementalIns"/>
</Results>
</BEAAPI>

Example Request 2:

[Link]
Key&method=GetParameterValues&datasetname=Regional&ParameterName=TableName&ResultFormat=
XML

Page 8 of 15 November 12, 2024


Example Return 2:
<BEAAPI>
<Request>
<RequestParam ParameterName="USERID" ParameterValue="Your-36-Character-Key"/>
<RequestParam ParameterName="METHOD" ParameterValue="GETPARAMETERVALUES"/>
<RequestParam ParameterName="DATASETNAME" ParameterValue="REGIONAL"/>
<RequestParam ParameterName="PARAMETERNAME" ParameterValue="TABLENAME"/>
<RequestParam ParameterName="RESULTFORMAT" ParameterValue="XML"/>
</Request>
<Results>
<ParamValue Key="CAGDP1" Desc="County and MSA gross domestic product (GDP) summary"/>
<ParamValue Key="CAGDP11" Desc="Contributions to percent change in real GDP"/>
<ParamValue Key="CAGDP2" Desc="Gross domestic product (GDP) by county and metropolitan area"/>
<ParamValue Key="CAGDP8" Desc="Chain-type quantity indexes for real GDP by county and metropolitan area (2017=100.0)"/>
<ParamValue Key="CAGDP9" Desc="Real GDP by county and metropolitan area"/>
<ParamValue Key="CAINC1" Desc="County and MSA personal income summary: personal income, population, per capita personal
income"/>
<ParamValue Key="CAINC30" Desc="Economic profile"/>
<ParamValue Key="CAINC4" Desc="Personal income by major component"/>
<ParamValue Key="CAINC5N" Desc="Personal income by major component and earnings by NAICS industry"/>
<ParamValue Key="CAINC5S" Desc="Personal income by major component and earnings by SIC industry"/>
<ParamValue Key="CAINC6N" Desc="Compensation of employees by NAICS industry"/>
<ParamValue Key="CAINC6S" Desc="Compensation of employees by SIC industry"/>
<ParamValue Key="CAINC91" Desc="Gross flow of earnings"/>
<ParamValue Key="MAIRPD" Desc="Implicit regional price deflators by MSA"/>
<ParamValue Key="MARPI" Desc="Real personal income by MSA"/>
<ParamValue Key="MARPP" Desc="Regional price parities by MSA"/>
<ParamValue Key="PAIRPD" Desc="Implicit regional price deflators by portion"/>
<ParamValue Key="PARPI" Desc="Real personal income by portion"/>
<ParamValue Key="PARPP" Desc="Regional price parities by portion"/>
<ParamValue Key="SAACArtsComp" Desc="ACPSA compensation by ACPSA industry"/>
<ParamValue Key="SAACArtsEmp" Desc="ACPSA full-time and part-time employment by ACPSA industry"/>
<ParamValue Key="SAACArtsVA" Desc="ACPSA value added by ACPSA industry"/>
<ParamValue Key="SAACCompLQ" Desc="Arts compensation location quotient"/>
<ParamValue Key="SAACCompRatio" Desc="Arts compensation ratio"/>
<ParamValue Key="SAACEmpLQ" Desc="Arts employment location quotient"/>
<ParamValue Key="SAACEmpRatio" Desc="Arts employment ratio"/>
<ParamValue Key="SAACVALQ" Desc="Arts value added location quotient"/>
<ParamValue Key="SAACVARatio" Desc="Arts value added ratio"/>
<ParamValue Key="SAGDP1" Desc="State annual gross domestic product (GDP) summary"/>
<ParamValue Key="SAGDP11N" Desc="Contributions to percent change in real GDP"/>
<ParamValue Key="SAGDP2N" Desc="Gross domestic product (GDP) by state"/>
<ParamValue Key="SAGDP3N" Desc="Taxes on production and imports less subsidies"/>
<ParamValue Key="SAGDP4N" Desc="Compensation of employees"/>
<ParamValue Key="SAGDP5N" Desc="Subsidies"/>
<ParamValue Key="SAGDP6N" Desc="Taxes on production and imports"/>
<ParamValue Key="SAGDP7N" Desc="Gross operating surplus"/>
<ParamValue Key="SAGDP8N" Desc="Chain-type quantity indexes for real GDP by state (2017=100.0)"/>
<ParamValue Key="SAGDP9N" Desc="Real GDP by state"/>
<ParamValue Key="SAINC1" Desc="State annual personal income summary: personal income, population, per capita personal
income"/>
<ParamValue Key="SAINC30" Desc="Economic profile"/>
<ParamValue Key="SAINC35" Desc="Personal current transfer receipts"/>
<ParamValue Key="SAINC4" Desc="Personal income and employment by major component"/>
<ParamValue Key="SAINC40" Desc="Property income"/>
<ParamValue Key="SAINC50" Desc="Personal current taxes"/>
<ParamValue Key="SAINC51" Desc="State annual disposable personal income summary: disposable personal income, population,
and per capita disposable personal income"/>
<ParamValue Key="SAINC5H" Desc="Personal income by major component and earnings by industry (historical)"/>
<ParamValue Key="SAINC5N" Desc="Personal income by major component and earnings by NAICS industry"/>
<ParamValue Key="SAINC5S" Desc="Personal income by major component and earnings by SIC industry"/>
<ParamValue Key="SAINC6N" Desc="Compensation of employees by NAICS industry"/>
<ParamValue Key="SAINC6S" Desc="Compensation of employees by SIC industry"/>
<ParamValue Key="SAINC70" Desc="Transactions of state and local government defined benefit pension plans"/>
<ParamValue Key="SAINC7H" Desc="Wages and salaries by industry (historical)"/>
<ParamValue Key="SAINC7N" Desc="Wages and salaries by NAICS industry"/>
<ParamValue Key="SAINC7S" Desc="Wages and salaries by SIC industry"/>
<ParamValue Key="SAINC91" Desc="Gross flow of earnings"/>
<ParamValue Key="SAIRPD" Desc="Implicit regional price deflators by state"/>
<ParamValue Key="SAOACTVA" Desc="Outdoor recreation satellite account activities - value added"/>
<ParamValue Key="SAOCOMP" Desc="Outdoor recreation satellite account compensation"/>
<ParamValue Key="SAOEMP" Desc="Outdoor recreation satellite account employment"/>
<ParamValue Key="SAOVA" Desc="Outdoor recreation satellite account value added"/>
<ParamValue Key="SAPCE1" Desc="Personal consumption expenditures (PCE) by major type of product"/>
<ParamValue Key="SAPCE2" Desc="Per capita personal consumption expenditures (PCE) by major type of product"/>
<ParamValue Key="SAPCE3" Desc="Personal consumption expenditures (PCE) by state by type of product"/>
<ParamValue Key="SAPCE4" Desc="Personal consumption expenditures (PCE) by state by function"/>
<ParamValue Key="SARPI" Desc="Real personal income and real personal Consumption Expenditures (PCE) by state"/>
<ParamValue Key="SARPP" Desc="Regional price parities by state"/>
<ParamValue Key="SASUMMARY" Desc="State annual summary statistics: personal income, GDP, consumer spending, price
indexes, and employment"/>
<ParamValue Key="SQGDP1" Desc="State quarterly gross domestic product (GDP) summary"/>
<ParamValue Key="SQGDP11" Desc="Contributions to percent change in real GDP"/>
<ParamValue Key="SQGDP2" Desc="Gross domestic product (GDP) by state"/>
<ParamValue Key="SQGDP8" Desc="Chain-type quantity indexes for real GDP by state (2017=100.0)"/>
<ParamValue Key="SQGDP9" Desc="Real GDP by state"/>
<ParamValue Key="SQINC1" Desc="State quarterly personal income summary: personal income, population, per capita personal
income"/>
<ParamValue Key="SQINC35" Desc="Personal current transfer receipts"/>
<ParamValue Key="SQINC4" Desc="Personal income by major component"/>
<ParamValue Key="SQINC5H" Desc="Personal income by major component and earnings by industry (historical)"/>
<ParamValue Key="SQINC5N" Desc="Personal income by major component and earnings by NAICS industry"/>
<ParamValue Key="SQINC5S" Desc="Personal income by major component and earnings by SIC industry"/>
<ParamValue Key="SQINC6N" Desc="Compensation of employees by NAICS industry"/>

Page 9 of 15 November 12, 2024


<ParamValue Key="SQINC6S" Desc="Compensation of employees by SIC industry"/>
<ParamValue Key="SQINC7H" Desc="Wages and salaries by industry (historical)"/>
<ParamValue Key="SQINC7N" Desc="Wages and salaries by NAICS industry"/>
<ParamValue Key="SQINC7S" Desc="Wages and salaries by SIC industry"/>
<ParamValue Key="TASUMMARY1" Desc="Summary of GDP and components for U.S. territories, current dollars"/>
<ParamValue Key="TASUMMARY2" Desc="Summary of real GDP and components for U.S. territories, chained dollars"/>
</Results>
</BEAAPI>

To summarize, the API includes three methods that retrieve meta-data about the statistics that are available:
GetDatasetList, GetParameterList, and GetParameterValues. There is also a method called
GetParameterValuesFiltered.
G et P a ra m et erV a lu esFi lt ered – retrieves a list of the valid values for a particular parameter based on
other provided parameters.

In our example above with the Regional data set, it is necessary to supply a TableName and LineCode. You
will want to discover the LineCode values available for a given TableName. The
GetParameterValuesFiltered method is designed to do this.

GetParameterValuesFiltered will return values for one target parameter based on the values of other
named parameters.

Example request to retrieve the valid LineCode values for a given TableName:

[Link]
Key&method=GetParameterValuesFiltered&datasetname=Regional&TargetParameter=LineCode&TableN
ame=SAINC1&ResultFormat=XML

Example return:
<BEAAPI>
<Request>
<RequestParam ParameterValue="Your-36Character-Key" ParameterName="USERID"/>
<RequestParam ParameterValue="XML" ParameterName="RESULTFORMAT"/>
<RequestParam ParameterValue="LINECODE" ParameterName="TARGETPARAMETER"/>
<RequestParam ParameterValue="SAINC1" ParameterName="TABLENAME"/>
<RequestParam ParameterValue="REGIONAL" ParameterName="DATASETNAME"/>
<RequestParam ParameterValue="GETPARAMETERVALUESFILTERED" ParameterName="METHOD"/>
</Request>
<Results>
<ParamValue Desc="[SAINC1] Personal income (millions of dollars)" Key="1"/>
<ParamValue Desc="[SAINC1] Population (persons)" Key="2"/>
<ParamValue Desc="[SAINC1] Per capita personal income (dollars)" Key="3"/>
</Results>
</BEAAPI>

All results from GetParameterValuesFiltered contain “Desc” and “Key”. Key is the value you will want to
pass in as a parameter to the data request for the target parameter you specified. In our example, a desired
Key will be passed into LineCode.

Although there is only one TargetParameter, mulitiple other parameters may be passed in. For example you
may want to know what years are available for a given TableName and GeoFips--

Example request:
[Link]
Key&method=GetParameterValuesFiltered&datasetname=Regional&TargetParameter=Year&TableName
=CAINC5N&GeoFips=01001&ResultFormat=XML

Example return:

Page 10 of 15 November 12, 2024


<BEAAPI>
<Request>
<RequestParam ParameterValue="YEAR" ParameterName="TARGETPARAMETER"/>
<RequestParam ParameterValue="CAINC5N" ParameterName="TABLENAME"/>
<RequestParam ParameterValue="XML" ParameterName="RESULTFORMAT"/>
<RequestParam ParameterValue="REGIONAL" ParameterName="DATASETNAME"/>
<RequestParam ParameterValue="01001" ParameterName="GEOFIPS"/>
<RequestParam ParameterValue="GETPARAMETERVALUESFILTERED" ParameterName="METHOD"/>
<RequestParam ParameterValue="Your-36CharacterKey" ParameterName="USERID"/>
</Request>
<Results>
<ParamValue Desc="2001" Key="2001"/>
<ParamValue Desc="2002" Key="2002"/>
<ParamValue Desc="2003" Key="2003"/>
<ParamValue Desc="2004" Key="2004"/>
<ParamValue Desc="2005" Key="2005"/>
<ParamValue Desc="2006" Key="2006"/>
<ParamValue Desc="2007" Key="2007"/>
<ParamValue Desc="2008" Key="2008"/>
<ParamValue Desc="2009" Key="2009"/>
<ParamValue Desc="2010" Key="2010"/>
<ParamValue Desc="2011" Key="2011"/>
<ParamValue Desc="2012" Key="2012"/>
<ParamValue Desc="2013" Key="2013"/>
<ParamValue Desc="2014" Key="2014"/>
<ParamValue Desc="2015" Key="2015"/>
<ParamValue Desc="2016" Key="2016”/>
<ParamValue Desc="2017" Key="2017"/>
<ParamValue Desc="2018" Key="2018"/>
<ParamValue Desc="2019" Key="2019"/>
<ParamValue Desc="2020" Key="2020"/>
<ParamValue Desc="2021" Key="2021"/>
<ParamValue Desc="2022" Key="2022”/>
</Results>
</BEAAPI>

There are many more examples of using GetParameterValuesFiltered in the Regional appendix N.

Please note that the GetParameterValuesFiltered method does not yet work with all BEA data sets. If
you try GetParametersValuesFiltered on a data set that does not yet support it, an error will be
returned--
<BEAAPI>
<Request>
<RequestParam ParameterValue="GETPARAMETERVALUESFILTERED" ParameterName="METHOD"/>
<RequestParam ParameterValue="Your-36CharacterKey" ParameterName="USERID"/>
<RequestParam ParameterValue="1" ParameterName="TABLEID"/>
<RequestParam ParameterValue="NIPA" ParameterName="DATASETNAME"/>
<RequestParam ParameterValue="XML" ParameterName="RESULTFORMAT"/>
<RequestParam ParameterValue="Q" ParameterName="FREQUENCY"/>
<RequestParam ParameterValue="YEAR" ParameterName="TARGETPARAMETER"/>
</Request>
<Results>
<Error APIErrorDescription="The GetParameterValuesFiltered method has not been implemented on this dataset (coming soon)."
APIErrorCode="34"/>
</Results>
</BEAAPI>

Data Retrieval API


Method

The API has one method for retrieving data – GetData.


Every data retrieval request requires the UserID, Method, and DatasetName parameters. Each dataset has a
defined set of parameters – some required and others optional. Each dataset returns different results that are
documented in appendices to this document.
GetData
Required Parameters: UserID, Method, DatasetName, additional required parameters (depending on
the dataset)

Optional Parameters: ResultFormat, additional optional parameters (depending on the dataset)

Page 11 of 15 November 12, 2024


Result: Dimensions nodes with attributes:
• Ordinal – ordinal number indicating a standardized order of returned dimensions – note that attributes in
returned data are not guaranteed to be in any particular order. Programmatic usage of attributes should
refer to them by name.
• Name – The Name of each data dimension returned
• DataType – string or numeric – whether the data dimension is purely numeric or should be treated
as string data
• IsValue – most datasets have one dimension that represents the statistic of interest, and the other
dimensions are descriptive of the statistic. IsValue = 1 for the data dimension that is the statistic
of interest, otherwise 0. The statistic of interest is usually numeric so that it can be summarized or
aggregated based on the descriptive dimension values.

Each Dataset contains different dimensions. There are a few pre-defined dimensions that are common to most
Datasets, including:

• CL_UNIT – a descriptor of the units reported for the data value (e. g. USD for U. S. dollars, and PC
for percent)
• UNIT_MULT – a descriptor of the multiplier that applies to the data value. This value is the base-
10 exponent that should be applied to the data value (e. g. amounts reported in millions would have
a UNIT_MULT of 6; amounts reported in billions would have a UNIT_MULT of 9).

The specific meaning of each dimension is described in the Appendix for each dataset.

The result then includes Data nodes containing the actual results specified in the parameters. Each Data
node contains one attribute for each data dimension (specified in the Dimensions nodes).

Finally, the result may include Note nodes. Notes (as in footnotes) further describe or qualify any of the other
nodes in the result (or the result node itself). A result node qualified by a Note has an attribute named
NoteRef. If a result node includes the NoteRef attribute, the value for it will always be present among the
Notes nodes.

Example Request 1:

[Link]
Key&method=GetData&datasetname=Regional&TableName=CAINC1&LineCode=3&GeoFIPS=DE&Yea
r=2014&ResultFormat=XML

In this example, the GetData method is used to return a result from the dataset named Regional. The TableId
and LineCode parameters are used to request statistic for “Per Capita personal income (county annual income)”.
The GeoFIPS parameter value is “DE” – meaning the data for all counties in Delaware are requested. A single
year’s data is requested – 2014.

Note that the GeoFIPS parameter could have been “COUNTY” for all counties, or a list of individual state
or county GeoFIPS codes. Also, multiple years could have been requested by providing them in a comma-
separated list, or the special year parameters “LAST5” or “LAST10” could be used.

Page 12 of 15 November 12, 2024


Example Return 1:
<BEAAPI>
<Request>
<RequestParam ParameterValue="Your-36Character-Key" ParameterName="USERID"/>
<RequestParam ParameterValue="REGIONAL" ParameterName="DATASETNAME"/>
<RequestParam ParameterValue="GETDATA" ParameterName="METHOD"/>
<RequestParam ParameterValue="DE" ParameterName="GEOFIPS"/>
<RequestParam ParameterValue="CAINC1" ParameterName="TABLENAME"/>
<RequestParam ParameterValue="3" ParameterName="LINECODE"/>
<RequestParam ParameterValue="2014" ParameterName="YEAR"/>
<RequestParam ParameterValue="XML" ParameterName="RESULTFORMAT"/>
</Request>
<Results NoteRef="2" UTCProductionTime="2017-03-03T14:37:59.443" PublicTable="CAINC1 Personal Income Summary: Personal
Income, Population, Per Capita Personal Income" UnitOfMeasure="dollars" Statistic="Per capita personal income">
<Dimensions IsValue="0" DataType="string" Name="Code"/>
<Dimensions IsValue="0" DataType="string" Name="GeoFips"/>
<Dimensions IsValue="0" DataType="string" Name="GeoName"/>
<Dimensions IsValue="0" DataType="string" Name="TimePeriod"/>
<Dimensions IsValue="1" DataType="numeric" Name="DataValue"/>
<Dimensions IsValue="0" DataType="string" Name="CL_UNIT"/>
<Dimensions IsValue="0" DataType="numeric" Name="UNIT_MULT"/>
<Data DataValue="45284" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2014" GeoName="Delaware" GeoFips="10000" Code="CA1-3"/>
<Data DataValue="36845" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2014" GeoName="Kent, DE" GeoFips="10001" Code="CA1-3"/>
<Data DataValue="48503" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2014" GeoName="New Castle, DE" GeoFips="10003"
Code="CA1-3"/>
<Data DataValue="43710" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2014" GeoName="Sussex, DE" GeoFips="10005" Code="CA1-
3"/>
<Notes NoteRef="2" NoteText="Per capita personal income was computed using Census Bureau midyear population estimates.
Estimates for 2010-2015 reflect county population estimates available as of March 2016."/>
<Notes NoteRef="Note--" NoteText="All dollar estimates are in current dollars (not adjusted for inflation)."/>
<Notes NoteRef=" " NoteText="Last updated: November 17, 2016-- new estimates for 2015; revised estimates for 1998-2014."/>
</Results>
</BEAAPI>

In this example the Result node contains a NoteRef attribute having the value “2”, and there is a Notes node
having the NoteRef value of “2”. This should be interpreted as meaning that the NoteText attribute for that
Notes node applies to the whole result.

Example Request 2:

[Link]
Key&method=GetData&datasetname=Regional&TableName=SAINC1&GeoFIPS=STATE&LineCode=3&
Year=2013&ResultFormat=XML

In this example, the GetData method is used to return the dataset named Regional. The TableName and
LineCode parameters are used to request statistic for “Per capita personal income (dollars)” – as shown in the
result of the first GetParameterValuesFiltered example above. The GeoFIPS parameter value is “STATE” –
meaning the data for all states is requested. Finally, a single year’s data is requested – 2013.

Note that the GeoFIPS parameter could have been a list of 5-digit geographic codes. Also, multiple years
could have been requested by providing them in a comma-separated list.

Example Return 2:
<BEAAPI>
<Request>
<RequestParam ParameterValue="2013" ParameterName="YEAR"/>
<RequestParam ParameterValue="3" ParameterName="LINECODE"/>
<RequestParam ParameterValue="REGIONAL" ParameterName="DATASETNAME"/>
<RequestParam ParameterValue="STATE" ParameterName="GEOFIPS"/>
<RequestParam ParameterValue="Your-36Character-Key" ParameterName="USERID"/>
<RequestParam ParameterValue="GETDATA" ParameterName="METHOD"/>
<RequestParam ParameterValue="SAINC1" ParameterName="TABLENAME"/>
<RequestParam ParameterValue="XML" ParameterName="RESULTFORMAT"/>
</Request>
<Results NoteRef="2" UTCProductionTime="2015-04-24T14:22:56.983" PublicTable="SA1 Personal Income Summary: Personal Income,
Population, Per Capita Personal Income" UnitOfMeasure="dollars" Statistic="Per capita personal income">
<Dimensions IsValue="0" DataType="string" Name="Code" Ordinal="1"/>
<Dimensions IsValue="0" DataType="string" Name="GeoFips" Ordinal="2"/>

Page 13 of 15 November 12, 2024


<Dimensions IsValue="0" DataType="string" Name="GeoName" Ordinal="3"/>
<Dimensions IsValue="0" DataType="string" Name="TimePeriod" Ordinal="4"/>
<Dimensions IsValue="1" DataType="numeric" Name="DataValue" Ordinal="5"/>
<Data DataValue="44,765" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="United States" GeoFips="00000"
Code="SA1-3"/>
<Data DataValue="36,481" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Alabama" GeoFips="01000" Code="SA1-
3"/>
<Data NoteRef="*" DataValue="50,150" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Alaska" GeoFips="02000"
Code="SA1-3"/>
<Data DataValue="36,983" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Arizona" GeoFips="04000" Code="SA1-
3"/>
<Data DataValue="36,698" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Arkansas" GeoFips="05000" Code="SA1-
3"/>
<Data DataValue="48,434" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="California" GeoFips="06000" Code="SA1-
3"/>
<Data DataValue="46,897" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Colorado" GeoFips="08000" Code="SA1-
3"/>
<Data DataValue="60,658" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Connecticut" GeoFips="09000" Code="SA1-
3"/>
<Data DataValue="44,815" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Delaware" GeoFips="10000" Code="SA1-
3"/>
<Data DataValue="75,329" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="District of Columbia" GeoFips="11000"
Code="SA1-3"/>
<Data DataValue="41,497" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Florida" GeoFips="12000" Code="SA1-
3"/>
<Data DataValue="37,845" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Georgia" GeoFips="13000" Code="SA1-3"/>
<Data NoteRef="*" DataValue="45,204" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Hawaii" GeoFips="15000"
Code="SA1-3"/>
<Data DataValue="36,146" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Idaho" GeoFips="16000" Code="SA1-3"/>
<Data DataValue="46,980" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Illinois" GeoFips="17000" Code="SA1-
3"/>
<Data DataValue="38,622" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Indiana" GeoFips="18000" Code="SA1-
3"/>
<Data DataValue="44,763" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Iowa" GeoFips="19000" Code="SA1-3"/>
<Data DataValue="44,417" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Kansas" GeoFips="20000" Code="SA1-
3"/>
<Data DataValue="36,214" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Kentucky" GeoFips="21000" Code="SA1-
3"/>
<Data DataValue="41,204" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Louisiana" GeoFips="22000" Code="SA1-
3"/>
<Data DataValue="40,924" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Maine" GeoFips="23000" Code="SA1-3"/>
<Data DataValue="53,826" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Maryland" GeoFips="24000" Code="SA1-
3"/>
<Data DataValue="57,248" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Massachusetts" GeoFips="25000"
Code="SA1-3"/>
<Data DataValue="39,055" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Michigan" GeoFips="26000" Code="SA1-
3"/>
<Data DataValue="47,500" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Minnesota" GeoFips="27000" Code="SA1-
3"/>
<Data DataValue="33,913" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Mississippi" GeoFips="28000" Code="SA1-
3"/>
<Data DataValue="40,663" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Missouri" GeoFips="29000" Code="SA1-
3"/>
<Data DataValue="39,366" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Montana" GeoFips="30000" Code="SA1-
3"/>
<Data DataValue="47,157" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Nebraska" GeoFips="31000" Code="SA1-
3"/>
<Data DataValue="39,235" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Nevada" GeoFips="32000" Code="SA1-
3"/>
<Data DataValue="51,013" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="New Hampshire" GeoFips="33000"
Code="SA1-3"/>
<Data DataValue="55,386" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="New Jersey" GeoFips="34000" Code="SA1-
3"/>
<Data DataValue="35,965" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="New Mexico" GeoFips="35000" Code="SA1-
3"/>
<Data DataValue="54,462" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="New York" GeoFips="36000" Code="SA1-
3"/>
<Data DataValue="38,683" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="North Carolina" GeoFips="37000"
Code="SA1-3"/>
<Data DataValue="53,182" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="North Dakota" GeoFips="38000"
Code="SA1-3"/>
<Data DataValue="41,049" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Ohio" GeoFips="39000" Code="SA1-3"/>
<Data DataValue="41,861" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Oklahoma" GeoFips="40000" Code="SA1-
3"/>
<Data DataValue="39,848" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Oregon" GeoFips="41000" Code="SA1-
3"/>
<Data DataValue="46,202" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Pennsylvania" GeoFips="42000"
Code="SA1-3"/>
<Data DataValue="46,989" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Rhode Island" GeoFips="44000"
Code="SA1-3"/>
<Data DataValue="35,831" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="South Carolina" GeoFips="45000"
Code="SA1-3"/>
<Data DataValue="46,039" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="South Dakota" GeoFips="46000"
Code="SA1-3"/>
<Data DataValue="39,558" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Tennessee" GeoFips="47000" Code="SA1-
3"/>
<Data DataValue="43,862" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Texas" GeoFips="48000" Code="SA1-3"/>
<Data DataValue="36,640" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Utah" GeoFips="49000" Code="SA1-3"/>
<Data DataValue="45,483" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Vermont" GeoFips="50000" Code="SA1-
3"/>
<Data DataValue="48,838" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Virginia" GeoFips="51000" Code="SA1-
3"/>
<Data DataValue="47,717" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Washington" GeoFips="53000" Code="SA1-
3"/>
<Data DataValue="35,533" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="West Virginia" GeoFips="54000"
Code="SA1-3"/>
<Data DataValue="43,244" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Wisconsin" GeoFips="55000" Code="SA1-
3"/>
<Data DataValue="52,826" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Wyoming" GeoFips="56000" Code="SA1-

Page 14 of 15 November 12, 2024


3"/>
<Data DataValue="54,797" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="New England" GeoFips="91000" Code="SA1-
3"/>
<Data DataValue="52,485" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Mideast" GeoFips="92000" Code="SA1-
3"/>
<Data DataValue="42,192" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Great Lakes" GeoFips="93000" Code="SA1-
3"/>
<Data DataValue="44,796" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Plains" GeoFips="94000" Code="SA1-
3"/>
<Data DataValue="39,760" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Southeast" GeoFips="95000" Code="SA1-
3"/>
<Data DataValue="42,074" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Southwest" GeoFips="96000" Code="SA1-
3"/>
<Data DataValue="42,391" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Rocky Mountain" GeoFips="97000"
Code="SA1-3"/>
<Data DataValue="47,185" UNIT_MULT="0" CL_UNIT="dollars" TimePeriod="2013" GeoName="Far West" GeoFips="98000" Code="SA1-
3"/>
<Notes NoteRef="2" NoteText="Per capita personal income is total personal income divided by total midyear population."/>
<Notes NoteRef="*" NoteText="Estimates prior to 1950 are not available for Alaska and Hawaii."/>
<Notes NoteRef="Note--" NoteText="All dollar estimates are in current dollars (not adjusted for inflation)."/>
<Notes NoteRef=" " NoteText="Last updated: March 25, 2015-- new estimates for 2014."/>
</Results>
</BEAAPI>

In this example the Result node contains a NoteRef attribute having the value “2”, and there is a Notes node
having the NoteRef value of “2”. This should be interpreted as meaning that the NoteText attribute for that
Notes node applies to the whole result.

There are two Data nodes having a NoteRef attribute with the value “*”, and there is one Notes nodes having
the matching NoteRef attribute (“*”). This should be interpreted to mean that the Notes node having NoteRef
= “*” apply as a group to the corresponding Data nodes.

DataSet Documentation
BEA expects to publish several API Datasets containing a variety of economic statistics. The Datasets that are
currently available are each documented separately as appendices here.

Page 15 of 15 November 12, 2024


Appendix A – RegionalData (DEPRECATED)

The RegionalData dataset is obsolete and API calls using this dataset will no longer function. Users
should instead access the dataset Regional, which provides comprehensive detail in statistics, industries,
geography, and years. See Appendix N for instructions on how to use the Regional dataset.
Appendix B – NIPA (National Income and Product Accounts)
The DataSetName is NIPA. This dataset contains data from the National Income and Product Accounts
which include measures of the value and composition of [Link] and the incomes generated in
producing it. NIPA data is provided on a table basis; individual tables contain between fewer than 10 to more
than 200 distinct data series. Three parameters are used to retrieve data from the NIPA dataset, as follows:

Name Type Description Is Required Multiple “All” value


Values
Accepted
TableName String The standard NIPA No No N/A
table identifier

Frequency String List of frequencies to Yes Yes N/A


retrieve

Year String List of year(s) of Yes Yes X


data to retrieve ALL

Example calls

Percent change in Real Gross Domestic Product, Annually and Quarterly for all years

[Link]
NIPA&TableName=T10101&Frequency=A,Q&Year=ALL&ResultFormat=xml

Personal Income, Monthly, for 2015 and 2016

[Link]
NIPA&TableName=T20600&Frequency=M&Year=2015,2016&ResultFormat=xml

API Call [GETPARAMETERVALUES] to Obtain a List of Available Values & Descriptions for
Each Parameter
[Details of each are described in the section below. ]

Parameter Name Parameter Value List


[Link]
TableName Key&method=GetParameterValues&DataSetName=NIPA&ParameterName=
TableName&ResultFormat=xml
[Link]
Frequency Key&method=GetParameterValues&DataSetName=NIPA&ParameterName=
Frequency&ResultFormat=xml
[Link]
Year Key&method=GetParameterValues&DataSetName=NIPA&ParameterName=
Year&ResultFormat=xml
TableName Parameter – (required)
The TableName parameter is a string that identifies a specific NIPA table. Only one NIPA table can be
requested in each data request. Requests with an invalid combination of TableName, Frequency or Year values
will result in an error. The TableName parameter must be passed or an error will result.

TableID Parameter – (discontinued; February 2018)


The TableID parameter is discontinued. The TableName parameter replaces the TableId parameter. A
crosswalk between TableId and TableName values can be found in the appendix to this document.

Frequency Parameter – (required, multiple values allowed)


The Frequency parameter is a string that refers to the time series for the requested NIPA table. Multiple
frequencies are requested by specifying them as a comma-delimited string, e. g. “A,Q,M”.

When data is requested for frequencies that are not available for the requested NIPA table, only data that is
available is returned; if no data is available for the requested frequencies, an error will be returned.

When calling the GetParameterValues method and passing a TableName value the response will identify the
valid frequencies for that table.

Accepted parameter values are:

1. A – Annual
2. Q – Quarterly
3. M – Monthly

Year Parameter – (required, multiple values allowed)


The Year parameter specifies the year(s) of the data requested. When quarterly or monthly data are
requested all available quarters for the specified year(s) will be returned. Multiple years are requested by
specifying them as a comma-delimited string, e. g. “2000,2001,2002”.

If the request supplies the special value X or ALL for the Year parameter, all available years of data for
that NIPA table returned. Note that using the X or ALL value for all years can return large amounts of
data, and should be avoided when the actual required years are known.

When data is requested for years that are not available for the requested NIPA table, only data that is
available is returned; if no data is available for the requested year(s), an error will be returned.

When calling the GetParameterValues method and passing a TableName value the response will identify the
valid years for that table.

NIPA Dataset Result Data

NIPA (National Income and Product Accounts) Dimensions Elements in Return Data

Parameter Name Ordinal Datatype IsValue Description


1 String No Unique identifier for the NIPA table
TableName requested.

2 A unique identifier for the time series of the


SeriesCode String No
data item.
LineNumber 3 String No Sequence of the data item within the table.

4 String No A description of the transactions measured


LineDescription in the data item.
String No Time period for the data item in the form
TimePeriod 5 YYYY for annual data; YYYYQn for quarterly
data (where n is the quarter digit); or YYYYMx
for monthly data (where x is the month digit).
6 String No
String indicating the
Metric_Name
measurement of the data
item. Example values are
Current Dollars, Fisher Price
Index, etc.
7 String No The calculation type of the data item.
CL_UNIT
8 An integer representing the base-10
String No exponent of the multiplier used to interpret
UNIT_MULT the data value. For example “6” refers to
millions (DataValue × 106).
9 Value of the data item, formatted with
DataValue Numeric Yes
commas.

A NoteRef attribute is also included in all data elements and acts as a reference to one of the Notes elements
in the returned data. The NoteRef attribute may have multiple values represented by a comma-delimited
string. Any NoteRef attribute included in the data is guaranteed to have a corresponding Notes element. For
the NIPA dataset, every data element includes at least one Noteref that corresponds to a Note element
containing the title of the table.

Additional Information
Explanation of the estimates can be found in the National section of our website:
[Link] Please consult the schedule of releases which impacts data and table
availability. Updates and changes to the accounts are detailed at: [Link]
National Income and Product Account Methodologies can be found in our handbook.

TableName – TableID Mapping


TableName TableId TableName TableId TableName TableId TableName TableId
T10101 1 T10803 45 T30200 87 T40203 131
T10102 2 T10806 46 T30300 88 T40204 132
T10103 3 T10903 47 T30400 89 T40205 133
T10104 4 T10904 48 T30500 90 T40206 134
T10105 5 T10905 49 T30600 91 T4030A 135
T10106 6 T10906 50 T30700 92 T4030B 136
T10106A 7 T11000 51 T30800 93 T50100 137
T10106B 8 T11100 52 T30901 94 T50203 138
T10106C 9 T11200 53 T30902 95 T50205 139
T10106D 10 T11300 54 T30903 96 T50206 140
T10107 11 T11400 55 T30904 97 T50301 141
T10108 12 T11500 56 T30905 98 T50302 142
T10109 13 T11600 57 T30906 99 T50303 143
T10110 14 T11701 316 T31001 100 T50304 144
T10111 310 T11705 317 T31003 101 T50305 145
T10201 15 T11706 318 T31004 102 T50306 146
T10202 16 T20100 58 T31005 103 T50401 147
T10203 17 T20200A 59 T31006 104 T50402 148
T10204 18 T20200B 60 T31101 105 T50403 149
T10205 19 T20301 61 T31102 326 T50404 150
T10206 20 T20302 62 T31103 106 T50405 151
T10301 21 T20303 63 T31104 107 T50406 152
T10303 22 T20304 64 T31105 108 T50501 153
T10304 23 T20305 65 T31106 109 T50502 154
T10305 24 T20306 66 T31200 110 T50503 155
T10306 25 T20307 67 T31300 111 T50504 156
T10401 26 T20403 68 T31400 112 T50505 157
T10403 27 T20404 69 T31501 113 T50506 158
T10404 28 T20405 70 T31502 114 T50601 327
T10405 29 T20406 71 T31503 115 T50602 328
T10406 30 T20503 72 T31504 116 T50603 329
T10501 31 T20504 73 T31505 117 T50604 330
T10502 32 T20505 74 T31506 118 T50605 331
T10503 33 T20506 75 T31600 119 T50606 332
T10504 34 T20600 76 T31700 120 T50705A 163
T10505 35 T20700A 77 T31800A 121 T50705B 164
T10506 36 T20700B 78 T31800B 122 T50706A 165
T10604 37 T20801 79 T31900 123 T50706B 166
T10607 38 T20803 80 T32000 124 T50805A 173
T10608 39 T20804 81 T32100 125 T50805B 174
T10701 40 T20805 82 T32200 126 T50806A 175
T10703 41 T20806 83 T32300 127 T50806B 176
T10704 42 T20807 84 T40100 128 T50809A 333
T10705 43 T20900 85 T40201 129 T50809B 334
T10706 44 T30100 86 T40202 130 T50903A 335
TableName TableId TableName TableId TableName TableId
T50903B 336 T61100A 216 T62200B 261
T50904A 337 T61100B 217 T62200C 262
T50904B 338 T61100C 218 T62200D 263
T50905A 339 T61100D 219 T70100 264
T50905B 340 T61200A 220 T70201A 265
T50906B 342 T61200B 221 T70201B 266
T51000 178 T61200C 222 T70203A 267
T51100 343 T61200D 223 T70203B 268
T60100B 179 T61300A 224 T70204A 269
T60100C 180 T61300B 225 T70204B 270
T60100D 181 T61300C 226 T70205A 271
T60200A 182 T61300D 227 T70205B 272
T60200B 183 T61400A 228 T70206B 273
T60200C 184 T61400B 229 T70303 274
T60200D 185 T61400C 230 T70304 275
T60300A 186 T61400D 231 T70305 276
T60300B 187 T61500A 232 T70306 277
T60300C 188 T61500B 233 T70403 278
T60300D 189 T61500C 234 T70404 279
T60400A 190 T61500D 235 T70405 280
T60400B 191 T61600A 236 T70406 281
T60400C 192 T61600B 237 T70500 282
T60400D 193 T61600C 238 T70600 283
T60500A 194 T61600D 239 T70700 284
T60500B 195 T61700A 240 T70800 285
T60500C 196 T61700B 241 T70900 286
T60500D 197 T61700C 242 T71000 287
T60600A 198 T61700D 243 T71100 288
T60600B 199 T61800A 244 T71200 289
T60600C 200 T61800B 245 T71300 290
T60600D 201 T61800C 246 T71400 291
T60700A 202 T61800D 247 T71500 292
T60700B 203 T61900A 248 T71600 293
T60700C 204 T61900B 249 T71700 294
T60700D 205 T61900C 250 T71800 295
T60800A 206 T61900D 251 T71900 297
T60800B 207 T62000A 252 T72000 296
T60800C 208 T62000B 253 T72100 392
T60800D 209 T62000C 254 T72200 393
T60900B 210 T62000D 255 T72300 394
T60900C 211 T62100A 256 T72400 395
T60900D 212 T62100B 257 T72500 397
T61000B 213 T62100C 258
T61000C 214 T62100D 259
T61000D 215 T62200A 260
Appendix C – NIPA Underlying Detail (National Income and Product Accounts)
The DataSetName is NIUnderlyingDetail. This dataset contains underlying detail data from the National
Income and Product Accounts which include measures of the value and composition of [Link]
and the incomes generated in producing it. NIPA Underlying Detail data is provided on a table basis;
individual tables contain between fewer than 10 to more than 200 distinct data series. Four parameters are used
to retrieve data from the NIPA Underlying Detail dataset, as follows:

Name Type Description Is Required Multiple “All” value


Values
Accepted
TableName String The standard NIPA No No N/A
table identifier

Frequency String List of frequencies to Yes Yes N/A


retrieve

Year String List of year(s) of Yes Yes X


data to retrieve ALL

Example calls

Personal Conumption Expenditures, Current Dollars, Annually, Quarterly and Monthly for all years

[Link]
NIUnderlyingDetail&TableName=U20305&Frequency=A,Q,M&Year=ALL&ResultFormat=xml

Auto and Truck Unit Sales, Production, Inventories, Expenditures and Price, Monthly, for 2015 and 2016

[Link]
NIUnderlyingDetail &TableName=U70205S&Frequency=M&Year=2015,2016&ResultFormat=xml

API Call [GETPARAMETERVALUES] to Obtain a List of Available Values & Descriptions for
Each Parameter
[Details of each are described in the section below. ]

Parameter Name Parameter Value List


[Link]
TableName Key&method=GetParameterValues&DataSetName=NIUnderlyingDetail&ParameterName=
TableName&ResultFormat=xml
[Link] Key&method=GetParameterValues&
Frequency DataSetName=NIUnderlyingDetail&ParameterName= Frequency&ResultFormat=xml

[Link] Key&method=GetParameterValues&
Year DataSetName=NIUnderlyingDetail&ParameterName= Year&ResultFormat=xml
TableName Parameter – (required)
The TableName parameter is a string that identifies a specific NIPA Underlying Detail table. Only one NIPA
Underlying Detail table can be requested in each data request. Requests with an invalid combination of
TableName, Frequency or Year values will result in an error. The TableName must be passed or an error will
result.

TableID Parameter – (discontinued; February 2018)


The TableID parameter is discontinued. The TableName parameter replaces the TableId parameter. A
crosswalk between TableId and TableName values can be found in the appendix to this document.

Frequency Parameter – (required, multiple values allowed)


The Frequency parameter is a string that refers to the time series for the requested NIPA Underlying Detail
table. Multiple frequencies are requested by specifying them as a comma-delimited string, e. g. “A,Q,M”.

When data is requested for frequencies that are not available for the requested NIPA Underlying Detail table,
only data that is available is returned; if no data is available for the requested frequencies, an error will be
returned.

When calling the GetParameterValues method and passing a TableName value the response will identify the
valid frequencies for that table.

Accepted parameter values are:

1. A – Annual
2. Q – Quarterly
3. M – Monthly

Year Parameter – (required, multiple values allowed)


The Year parameter specifies the year(s) of the data requested. When quarterly or monthly data are
requested all available quarters for the specified year(s) will be returned. Multiple years are requested by
specifying them as a comma-delimited string, e. g. “2000,2001,2002”.

If the request supplies the special value X or ALL for the Year parameter, all available years of data for
that NIPA Underlying Detail table returned. Note that using the X or ALL value for all years can return
large amounts of data, and should be avoided when the actual required years are known.

When data is requested for years that are not available for the requested NIPA Underlying Detail table,
only data that is available is returned; if no data is available for the requested year(s), an error will be
returned.

When calling the GetParameterValues method and passing a TableName value the response will identify the
valid years for that table.

NIPA Underlying Detail Dataset Result Data

NIPA (National Income and Product Accounts) Dimensions Elements in Return Data
Parameter Name Ordinal Datatype IsValue Description

1 String No Unique identifier for the NIPA table


TableName requested.

2 A unique identifier for the time series of the


SeriesCode String No
data item.
LineNumber 3 String No Sequence of the data item within the table.

4 String No A description of the transactions measured


LineDescription in the data item.
String No Time period for the data item in the form
TimePeriod 5 YYYY for annual data; YYYYQn for quarterly
data (where n is the quarter digit); or YYYYMx
for monthly data (where x is the month digit).
6 String No
String indicating the
Metric_Name
measurement of the data
item. Example values are
Current Dollars, Fisher Price
Index, etc.
7 String No The calculation type of the data item.
CL_UNIT
8 An integer representing the base-10
String No exponent of the multiplier used to interpret
UNIT_MULT the data value. For example “6” refers to
millions (DataValue × 106).
9 Value of the data item, formatted with
DataValue Numeric Yes
commas.

A NoteRef attribute is also included in all data elements and acts as a reference to one of the Notes elements
in the returned data. The NoteRef attribute may have multiple values represented by a comma-delimited
string. Any NoteRef attribute included in the data is guaranteed to have a corresponding Notes element. For
the NIPA dataset, every data element includes at least one Noteref that corresponds to a Note element
containing the title of the table.

Additional Information
Explanation of the estimates can be found in the National section of our website:
[Link] Please consult the schedule of releases which impacts data and table
availability. Updates and changes to the accounts are detailed at: [Link]
National Income and Product Account Methodologies can be found in our handbook.
TableName – TableID Mapping

TableName TableId TableName TableId TableName TableId TableName TableId


U001A 2001 U20305 2014 U50203 2070 U50705BU3 2092
U001A2 2012 U20306 2015 U50205 2071 U50706AM 2093
U001B 2023 U20403 2074 U50206 2072 U50706AU 2094
U001BC 2034 U20404 2016 U50404 2029 U50706BM 2095
U002AU 2045 U20405 2017 U50405 2030 U50706BU 2096
U002AUI 2056 U20406 2018 U50406 2031 U51100 2053
U002BU 2059 U30400 2019 U50504 2032 U70204 2054
U002BUI 2060 U30500 2020 U50505 2033 U70205 2057
U003AU 2061 U30600 2021 U50506 2035 U70205S 2055
U003BU 2002 U30700 2022 U50705AM1 2081 U70206 2058
U004A1 2003 U30800 2024 U50705AM2 2082 U90100 2075
U004A2 2004 U31200 2025 U50705AM3 2083 U90200 2076
U004A3 2005 U31300 2026 U50705AU1 2084 U90300 2077
U004B1 2006 U32400 2027 U50705AU2 2085 U90400 2078
U004B2 2007 U32500 2028 U50705AU3 2086 U90500 2079
U004B3 2008 U40203 2114 U50705BM1 2087
U00500 2009 U40204 2111 U50705BM2 2088
U00600 2010 U40205 2113 U50705BM3 2089
U00700 2011 U40206 2112 U50705BU1 2090
U20304 2013 U4030B 2073 U50705BU2 2091
Appendix D – Fixed Assets

The DataSetName is FixedAssets. This dataset contains data from the standard set of Fixed Assets tables as
published online. Two parameters are used to retrieve data from the Fixed Assets dataset, as follows:

Name Type Description Is Required Multiple “All” value


Values
Accepted
TableName String The standard NIPA Yes No N/A
table identifier

Year String List of year(s) of Yes Yes X


data to retrieve ALL

Example calls

Current-Cost Net Stock of Private Fixed Assets, Equipment, Structures, and Intellectual Property Products
by Type, for all years

[Link]
Key&method=GetData&DataSetName=FixedAssets&TableName=FAAt201&Year=ALL&ResultFormat=xml

Chain-Type Quantity Indexes for Depreciation of Private Nonresidential Fixed Assets by Industry Group and
Legal Form of Organization, for 2015 and 2016

[Link]
Key&method=GetData&DataSetName=FixedAssets&TableName=FAAt405&Year=2015,2016&ResultFormat=xml

API Call [GETPARAMETERVALUES] to Obtain a List of Available Values & Descriptions for
Each Parameter
[Details of each are described in the section below. ]

Parameter Name Parameter Value List


[Link]
TableName Key&method=GetParameterValues&DataSetName=FixedAssets&ParameterName=
TableName&ResultFormat=xml
[Link]
Year Key&method=GetParameterValues&DataSetName=FixedAssets&ParameterName=
Year&ResultFormat=xml

TableName Parameter – (required)


The TableName parameter is a string that identifies a specific NIPA table. Only one NIPA table can be requested
in each data request. Requests with an invalid combination of TableName and Year values will result in an error.
The TableName parameter must be passed or an error will result.
TableID Parameter – (discontinued; October 2018)
The TableID parameter is discontinued. The TableName parameter replaces the TableId parameter. A crosswalk
between TableId and TableName values can be found in the appendix to this document.

Year Parameter – (required, multiple values allowed)


The Year parameter specifies the year(s) of the data requested. Multiple years are requested by specifying
them as a comma-delimited string, e. g. “2000,2001,2002”.

If the request supplies the special value X or ALL for the Year parameter, all available years of data for that
NIPA table returned. Note that using the X or ALL value for all years can return large amounts of data, and
should be avoided when the actual required years are known.

When data is requested for years that are not available for the requested NIPA table, only data that is
available is returned; if no data is available for the requested year(s), an error will be returned.

When calling the GetParameterValues method and passing a TableName value the response will identify the
valid years for that table.

NIPA Dataset Result Data

NIPA (National Income and Product Accounts) Dimensions Elements in Return Data

Parameter Name Ordinal Datatype IsValue Description

1 String No Unique identifier for the NIPA table


TableName requested.

2 A unique identifier for the time series of the


SeriesCode String No
data item.
LineNumber 3 String No Sequence of the data item within the table.

4 String No A description of the transactions measured


LineDescription in the data item.
String No Time period for the data item in the form
TimePeriod 5 YYYY for annual data; YYYYQn for quarterly
data (where n is the quarter digit); or YYYYMx
for monthly data (where x is the month digit).
6 String No
String indicating the
Metric_Name
measurement of the data
item. Example values are
Current Dollars, Fisher Price
Index, etc.
7 String No The calculation type of the data item.
CL_UNIT
8 An integer representing the base-10
String No exponent of the multiplier used to interpret
UNIT_MULT the data value. For example “6” refers to
millions (DataValue × 106).
9 Value of the data item, formatted with
DataValue Numeric Yes
commas.

A NoteRef attribute is also included in all data elements and acts as a reference to one of the Notes elements in
the returned data. The NoteRef attribute may have multiple values represented by a comma-delimited string.
Any NoteRef attribute included in the data is guaranteed to have a corresponding Notes element. For the NIPA
dataset, every data element includes at least one Noteref that corresponds to a Note element containing the title
of the table.

Additional Information
Explanation of the estimates can be found in the Fixed Assets section of our website:
[Link] Fixed Assets data is updated once
per year, typically between late-August through early October.
TableName – TableID Mapping

TableName TableId TableName TableId TableName TableId

FAAt101 16 FAAt307ESI 138 FAAt610 119

FAAt102 17 FAAt307I 139 FAAt701 149

FAAt103 86 FAAt307S 55 FAAt702 150

FAAt104 87 FAAt308E 57 FAAt703 151

FAAt105 96 FAAt308ESI 140 FAAt704 152

FAAt106 97 FAAt308I 141 FAAt705 153

FAAt107 105 FAAt308S 147 FAAt706 154

FAAt108 124 FAAt309E 108 FAAt707 155

FAAt109 125 FAAt309ESI 142 FAAt801 32

FAAt201 18 FAAt309I 143 FAAt802 33

FAAt202 19 FAAt309S 110 FAAt803 50

FAAt203 42 FAAt310E 111 FAAt804 83

FAAt204 65 FAAt310ESI 144 FAAt805 148

FAAt205 66 FAAt310I 145 FAAt806 85

FAAt206 67 FAAt310S 113 FAAt807 63

FAAt207 51 FAAt401 26 FAAt808 64

FAAt208 52 FAAt402 27 FAAt809 122

FAAt209 106 FAAt403 46 FAAt810 123

faaT210 146 FAAt404 77 FAAt901 34

FAAt301E 21 FAAt405 78 FAAt902 95

FAAt301ESI 126 FAAt406 79 FAAt903 104

FAAt301I 127 FAAt407 59

FAAt301S 22 FAAt408 60

FAAt302E 24 FAAt409 114

FAAt302ESI 128 FAAt410 115


FAAt302I 129 FAAt501 28

FAAt302S 25 FAAt502 29

FAAt303E 44 FAAt503 47

FAAt303ESI 130 FAAt504 88

FAAt303I 131 FAAt505 89

FAAt303S 45 FAAt506 90

FAAt304E 69 FAAt507 98

FAAt304ESI 132 FAAt508 99

FAAt304I 133 FAAt509 116

FAAt304S 70 FAAt510 117

FAAt305E 72 FAAt601 41

FAAt305ESI 134 FAAt602 48

FAAt305I 135 FAAt603 49

FAAt305S 73 FAAt604 80

FAAt306E 75 FAAt605 81

FAAt306ESI 136 FAAt606 82

FAAt306I 137 FAAt607 61

FAAt306S 76 FAAt608 62

FAAt307E 54 FAAt609 118


Appendix E – Data on Direct Investment and Multinational Enterprises (MNEs)

The DataSetName is MNE. This dataset contains two types of statistics:

1. Direct Investment (DI)—income and financial transactions in direct investment that underlie the U. S.
balance of payments statistics, and direct investment positions that underlie the U. S. international
investment positions; and
2. Activities of Multinational Enterprises (AMNE)—operations and finances of U. S. parent enterprises
and their foreign affiliates and U. S. affiliates of foreign MNEs.

API requests for the two types of statistics share most of the same parameters, though the allowable values for
each parameter may be different, depending on the type of statistic desired (e. g. , DI or AMNE).

Type 1: Direct Investment (DI) Data Request


Multiple
“All”
Parameter Name Type Description Required Values Default
value
Accepted
Outward = US direct
investment abroad Not
DirectionOfInvestment String Yes No
Inward = Foreign accepted
investment in the US

SeriesID Integer Data Series Identifier No Yes All All

Classification Results by country Not


String Yes No
and/or industry accepted
Year String Time Period Yes Yes All
Geographic Area
Country String No Yes All All
Code
Industry String Industry Code No Yes All All
Yes = Include
Not
GetFootnotes String footnotes No No No
accepted
No = Exclude footnotes

Examples of Direct Investment (DI) Data Requests


U. S. direct investment position in China and Asia for 2011 and 2012

[Link] Your-36Character-
Key&method=GetData&DataSetName=MNE&Year=2012,2011&Country=650,699&DirectionOfInvestment=Outw
ard&Classification=Country&ResultFormat=xml

Foreign direct investment position in the U. S. from Germany in the manufacturing industry for 2011 and 2012
[Link] Your-36Character-
Key&method=GetData&DataSetName=MNE&Year=2013,2012,2011,2010&Country=308&Industry=3000&Directi
onOfInvestment=Inward&Classification=CountryByIndustry&ResultFormat=xml
Type 2: Activities of Multinational Enterprises (AMNE) Data Request
Multiple
“All”
Parameter Name Type Description Required Values Default
value
Accepted
Outward, Inward, Not
DirectionOfInvestment String Yes No
State, Parent accepted
0 = Majority-Owned
Not
OwnershipLevel Binary Affiliates Yes No
accepted
1 = All Affiliates
0 = Both Bank and
NonBank Affiliates Not
NonBankAffiliatesOnly Binary Yes No
1 = Nonbank accepted
Affiliates
Data Series
SeriesID Integer No Yes All All
Identifier
Classification Results by country Not
String Yes No
and/or industry accepted
Year String Time Period Yes Yes All
Geographic Area
Country String No Yes All All
Code
Industry String Industry Code No Yes All All
Two-digit State FIPS
State String No No All All
Code
Yes = Include
footnotes Not
GetFootnotes String No No No
No = Exclude accepted
footnotes

Examples of Activities of Multinational Enterprises (AMNE) Data Requests

Net income and sales for Brazilian affiliates of U. S. parent enterprises, all industries, 2011 and 2012

[Link] Your-36Character-
Key&method=GetData&DataSetName=MNE&Year=2012,2011&Country=202&Industry=all&DirectionOfInvestm
ent=Outward&Classification=CountryByIndustry&SeriesId=5,4&NonBankAffiliatesOnly=0&OwnershipLevel=0&R
esultFormat=xml

Total employment in U. S. affiliates of foreign-owned enterprises, all countries, 2011, include footnotes

[Link] Your-36Character-
Key&method=GetData&DataSetName=MNE&Year=2011&Country=all&Industry=0000&DirectionOfInvestment=I
nward&Classification=Country&SeriesId=8&OwnershipLevel=0&NonbankAffiliatesOnly=0&GetFootnotes=Yes&R
esultFormat=xml
API Call [GETPARAMETERVALUES] to Obtain a List of Available Values & Descriptions for
Each Parameter
[Details of each are described in the section below. ]

Parameter Name Parameter Value List


[Link] Your-36Character-Key
DirectionOfInvestment Y&method=GetParameterValues&DataSetName=MNE&ParameterName=Dir
ectionOfInvestment&ResultFormat=xml
[Link] Your-36Character-Key
OwnershipLevel &method=GetParameterValues&DataSetName=MNE&ParameterName=Ow
nershipLevel&ResultFormat=xml
[Link] Your-36Character-Key
NonBankAffiliatesOnly &method=GetParameterValues&DataSetName=MNE&ParameterName=Non
bankAffiliatesOnly&ResultFormat=xml
[Link]
SeriesID Key&method=GetParameterValues&DataSetName=MNE&ParameterName=
SeriesID&ResultFormat=xml
[Link] Your-36Character-Key
Classification &method=GetParameterValues&DataSetName=MNE&ParameterName=Clas
sification&ResultFormat=xml
[Link] Your-36Character-Key
Year &method=GetParameterValues&DataSetName=MNE&ParameterName=Yea
r&ResultFormat=xml
[Link] Your-36Character-Key
Country &method=GetParameterValues&DataSetName=MNE&ParameterName=cou
ntry&ResultFormat=xml
[Link] Your-36Character-Key
Industry &method=GetParameterValues&DataSetName=MNE&ParameterName=Ind
ustry&ResultFormat=xml
[Link] Your-36Character-Key
State &method=GetParameterValues&DataSetName=MNE&ParameterName=stat
e&ResultFormat=xml
[Link] Your-36Character-Key
GetFootnotes &method=GetParameterValues&DataSetName=MNE&ParameterName=Get
Footnotes&ResultFormat=xml
Parameter Details

DirectionOfInvestment Parameter – (Required, single value)


DirectionOfInvestment can take on two values for DI statistics and four for AMNE
statistics. The two values shared by DI and AMNE statistics are:

1. ‘Outward’ – for AMNE statistics, provides data for foreign affiliates; for DI statistics,
provides data on transactions and positions between foreign affiliates and their U. S.
parent enterprises.
2. ‘Inward’ – for AMNE statistics, provides data for U. S. affiliates; for DI statistics,
provides data on transactions and positions between U. S. affiliates and their
foreign parent groups.

For AMNE statistics only there are two additional options:

3. ‘State’ – provides data on U. S. affiliates of foreign multinational enterprises at the


state level. Note that only data on employment (and for 2007 and earlier years,
property, plant, and equipment) are available at the state level.
4. ‘Parent’ – provides data on U. S. parent enterprises.

OwnershipLevel Parameter – (used with AMNE statistics only, required, single value)

1. 1 – Returns data for all affiliates


2. 0 – Returns data for majority-owned affiliates only

If DirectionOfInvestment = “Parent” then OwnershipLevel must be set to 1.

NonBankAffiliatesOnly Parameter – (used with AMNE statistics only, required, single value)

1. 1 – Returns data for nonbank affiliates only


2. 0 – Returns data for both bank and nonbank affiliates only

Select NonBankAffiliatesOnly = 0 for data from 2009 – present for ‘outward’ AMNE and
from 2007 – present for ‘inward’ AMNE

Select NonBankAffiliatesOnly = 1 for data up to 2008 for ‘outward’ AMNE and up to 2006 for
‘inward AMNE

SeriesID Parameter – (optional, default = 0, multiple values allowed)

Refer to the GETPARAMETERVALUES API call above for the list of SeriesID values and
their descriptions. Note that not all series are available for all classes of ownership and years.

A value of 0 will return data for all available series given the other parameters. Separate
multiple values with a comma.

Classification Parameter – (required, single value)

Refer to the GETPARAMETERVALUES API call above for the list of CLASSIFICATION
parameter values and their descriptions. Note that not all series are available for all
classifications. The CLASSIFICATION parameter is required and must be single-valued.

Year Parameter (required, multiple values allowed)

Use the four-digit year to request data for a specific year. Use ‘all’ to return data for all
available years. Separate multiple values with a comma.

Country Parameter – (optional, default = all, multiple values allowed)

Refer to the GETPARAMETERVALUES API call above for the list of three-digit
country and region identification values. Use ‘000’ for the total of all countries and ‘all’
for all available countries and regions. Separate multiple values with a comma.

Industry Parameter – (optional, default = all, multiple values allowed)

Refer to the GETPARAMETERVALUES API call abovefor the list of four-digit industry
identification values. These generally follow the North American Industry Classification
System (NAICS). Use ‘0000’ for the all- industries total and ‘all’ for all available industries.
Separate multiple values with a comma.

State Parameter – (optional, default = all, multiple values allowed)

At the state level, data are only available on employment and (for limited years), gross
property, plant, and equipment.

Refer to the GETPARAMETERVALUES API call above for the list of the two-digit Federal
Information Processing Standards (FIPS) codes, available at:
[Link]

Use ‘70’ for “Other U. S. Areas”, ‘75’ for “Foreign”, ‘00’ for total U. S., and ‘all’ for all
states and areas. Separate multiple values with a comma.

GetFootnotes Parameter – (optional, default=no, single value)

1. ‘yes’ – Include footnotes with data returned


2. ‘no’ – Do not include footnotes with data returned
Appendix F – Gross Domestic Product by Industry (GDPbyIndustry)

The gross domestic product by industry data are contained within a dataset called GDPbyIndustry. BEA's
industry accounts are used extensively by policymakers and businesses to understand industry interactions,
productivity trends, and the changing structure of the U. S. economy. The GDP-by-industry dataset includes
data in both current and chained (real) dollars. The dataset contains estimates for value added, gross output,
intermediate inputs, KLEMS and employment statistics.

Gross Domestic Product by Industry (GDPbyIndustry) Data Request


Multiple
“All”
Parameter Name Type Description Required Values Default
value
Accepted

The unique GDP by


TableID Integer Industry table identifier Yes Yes ALL N/A
(ALL for All)

Frequency String A - Annual, Q-Quarterly Yes Yes A,Q N/A

List of year(s) of data to


Year Integer Yes Yes ALL N/A
retrieve (ALL for All)
List of industries to
Industry String Yes Yes ALL N/A
retrieve (ALL for All)

Examples of GDP by Industry (GDPbyIndustry) Data Requests


Annual Value Added by Industry data for all industries for years 2011 and 2012:

[Link]
Key&method=GetData&DataSetName=GDPbyIndustry&Year=2012,2011&Industry=ALL&tableID=1&Frequency=
A&ResultFormat=xml

All annual and quarterly data in all tables for the Agriculture industry in 2010.

[Link]
Key&method=GetData&DataSetName=GDPbyIndustry&Year=2010&Industry=11&tableID=ALL&Frequency=A,Q
&ResultFormat=xml

API Call [GETPARAMETERVALUES] to Obtain a List of Available Values & Descriptions for
Each Parameter
[Details of each are described in the section below. ]

Parameter Name Parameter Value List


Appendix F: Page 1 of 3 June 8, 2018
[Link]
TableID Key%20Y&method=GetParameterValues&DataSetName=GDPbyIndustry&Param
eterName=TableID&ResultFormat=xml
[Link]
Frequency Key%20Y&method=GetParameterValues&DataSetName=GDPbyIndustry&Param
eterName=Frequency&ResultFormat=xml
[Link]
Year Key%20Y&method=GetParameterValues&DataSetName=GDPbyIndustry&Param
eterName=Year&ResultFormat=xml
[Link]
Industry Key%20Y&method=GetParameterValues&DataSetName=GDPbyIndustry&Param
eterName=Industry&ResultFormat=xml

Parameter Details

TableID Parameter – (Required, multiple values accepted, no default value, ‘ALL’ for all tables)
• The TableID parameter is a unique table identifier. This parameter is required to query data and does
accept multiple comma separated values. If all tables are required, use the ‘ALL’ keyword.
• All tables are published annually, but only a subset are published quarterly. The Descr in the
GetParameterValues result will contain (A) if the table is published annually and (Q) indicating that the
table is also published quarterly.

Frequency Parameter – (Required, multiple values accepted, no default value, ‘A,Q’ for all frequencies)
• The Frequency parameter indicates whether annual or quarterly data are to be returned. This parameter is
required to query data and does accept multiple comma separated values.
• All tables are published annually (Frequency = A) but only a subset are published quarterly (Frequency =
Q)
• If a data request is submitted for both annual and quarterly data from a table that is only published
annually then only the annual data will be returned.
• If a data request is submitted for quarterly data from a table that is only published annually then the user
will receive the following error:

<Error APIErrorCode="204" APIErrorDescription="Error retrieving GDP by Industry data. ">


<ErrorDetail Description="This TableID is not published quarterly: 25" />
</Error>

Year Parameter – (Required, multiple values accepted, no default value, ’ALL‘ for all years)
• The Year parameter indicates what periods of data are requested. This parameter is required to query data
and does accept multiple comma separated values. Use the keyword ‘ALL’ to return all periods of data.
• If requesting quarterly frequency data, all available quarters for a year will be returned.
• Annual data publications begin in 1997 for most tables and 1998 for percent change and contributions
tables. Quarterly data began publication in 2005.

Appendix F: Page 2 of 3 June 8, 2018


• If a data request is submitted for quarterly or annual data before the earliest estimate period the user
will receive one of the following errors:

<Error APIErrorCode="204" APIErrorDescription="Error retrieving GDP by Industry data. ">


<ErrorDetail Description="Quarterly data begin in 2005. Invalid year: 1997" />
</Error>

<Error APIErrorCode="204" APIErrorDescription="Error retrieving GDP by Industry data. ">


<ErrorDetail Description="Annual data begin in 1997 and quarterly data begins in
2005. Invalid year: 1996" />
</Error>

Industry Parameter – (Required, multiple values accepted, no default value, ‘ALL‘ for all industries)
• The Industry parameter indicates what periods of data are requested. This parameter is required to
query data and does accept multiple comma separated values. Use the keyword ‘ALL’ to return all
industries.
• All industries are published annually, but only a subset are published quarterly. The Descr in the
GetParameterValues result will contain (A) if the industry is published annually and (Q) indicating
that the industry is also published quarterly.
• If a data request is submitted for an industry that is not published in the requested tables the user
will receive the following error:

<Error APIErrorCode="204" APIErrorDescription="Error retrieving GDP by Industry data. ">


<ErrorDetail Description="Invalid industry: 111CA" />
</Error>

General Use
• Data will be returned for all data cells that fit the requested criteria. If the request contains parameter
values requesting data for which only part of a set is available, only the data matching the criteria will
be returned. For example, requesting ALL TableIDs for 1997 will return only annual data because the
quarterly publications begin in estimate year 2005. Blanks will not be returned for missing data.
• If no data fit the selected criteria the user will receive the following error:

<Error APIErrorCode="204" APIErrorDescription="Error retrieving GDP by Industry data. ">


<ErrorDetail Description="No data exist for selected criteria" />
</Error>

Appendix F: Page 3 of 3 June 8, 2018


Appendix G – ITA (International Transactions)

The DataSetName is ITA. This dataset contains data on U. S. international transactions. BEA's international
transactions (balance of payments) accounts include all transactions between U. S. and foreign residents. Four
parameters are used to retrieve data from the ITA dataset, as follows:

ITA (International Transactions) Data Request Parameters


Multiple
Parameter Name Type Description Required Values “All”
Default
Accepted value
The indicator code
for the type of
Indicator String No Yes All All
transaction
requested
The area or country
AreaOrCountry String No Yes All AllCountries
requested
A - Annual, QSA -
Quarterly seasonally
Frequency String adjusted, QNSA - No Yes All All
Quarterly not
seasonally adjusted

Year String Year requested No Yes All All

Examples of ITA (International Transactions) Data Requests

Balance on goods with China for 2011 and 2012

[Link]
Key&method=GetData&DataSetName=ITA&Indicator=BalGds&AreaOrCountry=China&Frequency=A&Year=2011
,2012&ResultFormat=xml

Net U. S. acquisition of portfolio investment assets (quarterly not seasonally adjusted) for 2013

[Link]
Key&method=GetData&DataSetName=ITA&Indicator=PfInvAssets&AreaOrCountry=AllCountries&Frequency=Q
NSA&Year=2013&ResultFormat=xml

Appendix G: Page 1 of 3 June 8, 2018


API Call [GETPARAMETERVALUES] to Obtain a List of Available Values & Descriptions for
Each Parameter
[Details of each are described in the section below. ]

Parameter Name Parameter Value List


[Link]
Indicator Key&method=GetParameterValues&DataSetName=ITA&ParameterName=Indica
tor&ResultFormat=xml
[Link]
AreaOrCountry Key&method=GetParameterValues&DataSetName=ITA&ParameterName=AreaO
rCountry&ResultFormat=xml
[Link]
Frequency Key&method=GetParameterValues&DataSetName=ITA&ParameterName=Frequ
ency&ResultFormat=xml
[Link]
Year Key&method=GetParameterValues&DataSetName=ITA&ParameterName=Year&
ResultFormat=xml

Parameter Details

Indicator Parameter – (optional, multiple values allowed)

The Indicator parameter specifies the type of transaction. The Indicator parameter values usually correspond to
lines in ITA tables at [Link] cfm?reqid=62&step=2&isuri=1&6210=1.

Exactly one Indicator parameter value must be provided in all data requests unless exactly one AreaOrCountry
parameter value other than “ALL” and “AllCountries” is requested. That is, multiple Indicators can only be
specified if a single AreaOrCountry is specified.

AreaOrCountry Parameter – (optional, multiple values allowed)

The AreaOrCountry parameter specifies the counterparty area or country of the transactions.

The default parameter value (“AllCountries”) returns the total for all countries, while “All” returns all data
available by area and country.

Exactly one AreaOrCountry parameter value must be provided in all data requests unless exactly one Indicator
parameter value is requested. This single parameter value may not be either “ALL” or “AllCountries. ” That is,
a list of countries or the grand total for all countries can only be specified if a single Indicator is specified.

For information on geographic area definitions, see


[Link] cfm

Frequency Parameter – (optional, multiple values allowed)


Appendix G: Page 2 of 3 June 8, 2018
3. A – Annual
4. QSA – Quarterly seasonally adjusted
5. QNSA – Quarterly not seasonally adjusted
Year Parameter – (optional, multiple values allowed)
The Year parameter specifies the year of the data requested. When quarterly data are requested,
all available quarters for the specified year will be returned.

ITA (International Transactions) Dimensions Elements in Return Data

Parameter Name Ordinal Datatype IsValue Description

Indicator 1 The Indicator parameter value of the data


String No
item.
The AreaOrCountry parameter value of the
AreaOrCountry 2 String No
data item.
The Frequency parameter value of the data
Frequency 3 String No
item.
Year 4 String No The Year parameter value of the data item.

TimeSeriesId 5 A unique identifier for the time series of the


String No
data item.
TimeSeriesDescription 6 A description of the transactions measured in
String No
the data item.
A string containing the time period for the
TimePeriod 7 data item in the form YYYY for annual data
String No
and YYYYQn for quarterly data (where n is the
quarter digit)
A string indicating the base unit of
CL_UNIT 8 measurement of the data item. For example,
String No
“USD” is used when the reported statistic is
in U. S. dollars.
An integer representing the base-10
UNIT_MULT 9 exponent of the multiplier used to interpret
String No
the data value. For example “6” refers to
millions (DataValue × 106).
An integer or decimal value of the statistic.
DataValue 10 Numeric No
May be blank.

A NoteRef attribute is also included in all data elements and acts as a reference to one of the Notes elements
in the returned data. The NoteRef attribute may have multiple values represented by a comma-delimited
string. Any NoteRef attribute included in the data is guaranteed to have a corresponding Notes element. The
NoteRef attribute may be blank.

Appendix G: Page 3 of 3 June 8, 2018


Appendix H – IIP (International Investment Position)

The DataSetName is IIP. This dataset contains data on the U. S. international investment position. BEA's
international investment position accounts include the end of period value of accumulated stocks of U. S.
financial assets and liabilities. Four parameters are used to retrieve data from the IIP dataset, as follows:

IIP (International Investment Position) Data Request Parameters


Multiple
“All”
Parameter Name Type Description Required Values Default
value
Accepted

TypeOfInvestment String Type of investment No Yes All All

Component of
Component String No Yes All All
changes in position
A - Annual, QNSA -
Frequency String Quarterly not No Yes All All
seasonally adjusted
Year String Year requested No Yes All All

Examples of IIP (International Investment Position) Data Requests

U. S. assets excluding financial derivatives; change in position attributable to price changes for all available
years

[Link]
Key&method=GetData&DataSetName=IIP&TypeOfInvestment=FinAssetsExclFinDeriv&Component=ChgPosPrice
&Frequency=A&Year=ALL&ResultFormat=xml

U. S. liabilities to foreign official agencies (quarterly not seasonally adjusted) for 2013

[Link]
Key&method=GetData&DataSetName=IIP&TypeOfInvestment=FinLiabsFoa&Component=Pos&Frequency=QNSA
&Year=2013&ResultFormat=xml

Appendix H: Page 1 of 3 June 8, 2018


API Call [GETPARAMETERVALUES] to Obtain a List of Available Values & Descriptions for
Each Parameter
[Details of each are described in the section below. ]

Parameter Name Parameter Value List


[Link]
TypeOfInvestment Key&method=GetParameterValues&DataSetName=IIP&ParameterName=TypeOf
Investment&ResultFormat=xml
[Link]
Component Key&method=GetParameterValues&DataSetName=IIP&ParameterName=Compo
nent&ResultFormat=xml
[Link]
Frequency Key&method=GetParameterValues&DataSetName=IIP&ParameterName=Freque
ncy&ResultFormat=xml
[Link]
Year Key&method=GetParameterValues&DataSetName=IIP&ParameterName=Year&
ResultFormat=xml

Parameter Details

TypeOfInvestment Parameter – (optional, multiple values allowed)


The TypeOfInvestment parameter specifies the type of investment. The TypeOfInvestment parameter values
usually correspond to lines in IIP tables at [Link]
cfm?reqid=62&step=5&isuri=1&6210=2.

Exactly one TypeOfInvestment parameter value must be provided in all data requests unless exactly one Year
parameter value other than “ALL” is requested. That is, more than one TypeOfInvestment can only be specified
if a single Year is specified.

Component Parameter – (optional, multiple values allowed)

The Component parameter specifies either the position (“Pos”) or a component in the change of position from
the previous period. For instance, the parameter value “ChgPosTrans” specifies changes due to financial-
account transactions.

Frequency Parameter – (optional, multiple values allowed)

1. A – Annual
2. QNSA – Quarterly not seasonally adjusted

Year Parameter – (optional, multiple values allowed)


The Year parameter specifies the year of the data requested. When quarterly data are requested, all available
quarters for the specified year will be returned.
Appendix H: Page 2 of 3 June 8, 2018
Exactly one Year parameter value must be provided in all data requests unless exactly one
TypeOfInvestment parameter value other than “ALL” is requested. That is, more than one Year can only be
specified if a single TypeOfInvestment is specified.

IIP (International Investment Position) Dimensions Elements in Return Data

Parameter Name Ordinal Datatype IsValue Description

TypeOfInvestment 1 The TypeOfInvestment parameter value of


String No
the data item.
The Component parameter value of the data
Component 2 String No
item.
The Frequency parameter value of the data
Frequency 3 String No
item.
Year 4 String No The Year parameter value of the data item.

TimeSeriesId 5 A unique identifier for the time series of the


String No
data item.
TimeSeriesDescription 6 A description of the transactions measured in
String No
the data item.
A string containing the time period for the
TimePeriod 7 data item in the form YYYY for annual data
String No
and YYYYQn for quarterly data (where n is the
quarter digit)
A string indicating the base unit of
CL_UNIT 8 measurement of the data item. For example,
String No
“USD” is used when the reported statistic is
in U. S. dollars.
An integer representing the base-10
UNIT_MULT 9 exponent of the multiplier used to interpret
String No
the data value. For example “6” refers to
millions (DataValue × 106).
An integer or decimal value of the statistic.
DataValue 10 Numeric No
May be blank.

A NoteRef attribute is also included in all data elements and acts as a reference to one of the Notes elements
in the returned data. The NoteRef attribute may have multiple values represented by a comma-delimited
string. Any NoteRef attribute included in the data is guaranteed to have a corresponding Notes element. The
NoteRef attribute may be blank.

Appendix H: Page 3 of 3 June 8, 2018


Appendix I – RegionalIncome (DEPRECATED)

NOTE:

The RegionalIncome dataset is obsolete and API calls using this dataset will no longer function.
Users should instead access the dataset Regional, which provides comprehensive detail in
statistics, industries, geography, and years. See Appendix N for instructions on how to use the
Regional dataset.

Appendix I: Page 1 of 1 December 10, 2019


Appendix J – RegionalProduct (DEPRECATED)

NOTE:
The RegionalProduct dataset is obsolete and API calls using this dataset will no longer
function. Users should instead access the dataset Regional, which provides comprehensive
detail in statistics, industries, geography, and years. See Appendix N for instructions on how to
use the Regional dataset.
Appendix K – Input‐Output Statistics (InputOutput)

The Input‐Output Statistics are contained within a dataset called InputOutput. BEA's industry accounts are used
extensively by policymakers and businesses to understand industry interactions, productivity trends, and the changing
structure of the U.S. economy. The input-output accounts provide a detailed view of the interrelationships
between U.S. producers and users. The Input‐Output dataset contains Make Tables, Use Tables, and Direct and Total
Requirements tables.

InputOutput Data Request


Multiple
“All”
Parameter Name Type Description Required Values Default
value
Accepted

TableID Integer Yes Yes N/A N/A


The unique Input Output
table identifier
List of year(s) of data to
Year Integer Yes Yes ALL N/A
retrieve

Examples of InputOutput Data Requests


NOTE: The example URI's below are valid as of the date of this appendix. However, dataset parameter values
sometimes are changed to accommodate changes in data definitions, availability of data, etc. Therefore, the best way
to obtain the most current parameter values is to use the “GetParameterValues” method shown in the table below
these examples.

Data from Industry‐by‐Commodity Total Requirements, After Redefinitions (Sector Level) table for years 2010, 2011, and
2012:

[Link]
Key&method=GetData&DataSetName=InputOutput&Year=2010,2011,2012,2013&tableID=56&ResultFormat=x
ml

Data for Industry‐by‐Commodity Total Requirements, After Redefinitions sector and summary level tables:

[Link]
Key&method=GetData&DataSetName=InputOutput&Year=2007&tableID=56,57&&ResultFormat=xml

Appendix K: Page 1 of 2 February 11, 2020


API Call [GETPARAMETERVALUES] to Obtain a List of Available Values &
Descriptions for Each Parameter
[Details of each are described in the section below.]

Parameter Name Parameter Value List


[Link]
TableID &method=GetParameterValues&DataSetName=InputOutput&ParameterName=
TableID&ResultFormat=xml

[Link]
Year &method=GetParameterValues&DataSetName=InputOutput&ParameterName=
Year&ResultFormat=xml

Parameter Details

TableID Parameter (Required, multiple values accepted, no default value)


 The TableID parameter is a unique table identifier. This parameter is required to query data and does accept
multiple comma separated values.

Year Parameter (Required, multiple values accepted, no default value, ’ALL‘ for all years)

 The Year parameter indicates what periods of data are requested. This parameter is required to query data and
does accept multiple comma separated values. Use the keyword ‘ALL’ to return all periods of data.

General Use

 Data will be returned for all data cells that fit the requested criteria. If the request contains parameter values
requesting data for which only part of a set is available, only the data matching the criteria will be returned. For
example, requesting ALL Years Use Tables evaluated in Purchasers Value will return data for only 2007 because
these tables are only published in benchmark years. Blanks will not be returned for missing data.
 If no data fit the selected criteria the user will receive the following error:

<Error APIErrorCode="205" APIErrorDescription="Error retrieving Input-Output data.">


<ErrorDetail Description="No data exist for selected criteria" />
</Error>

Appendix K: Page 2 of 2 February 11, 2020


Appendix L – Underlying Gross Domestic Product by Industry
(UnderlyingGDPbyIndustry)

The underlying gross domestic product by industry data are contained within a dataset called UnderlyingGDPbyIndustry.
BEA's industry accounts are used extensively by policymakers and businesses to understand industry interactions,
productivity trends, and the changing structure of the U.S. economy. The underlying GDP-by-industry dataset includes data
in both current and chained (real) dollars. The dataset contains estimates for value added, gross output, and intermediate
input statistics. This dataset is structurally similar to the GDPbyIndustry dataset (Appendix F), but contains additional
industry detail.

Please Note: Cautionary Note on use of underlying detail tables -- The Bureau of Economic Analysis does not
include these detailed estimates in the published tables because their quality is significantly less than that of the
higher level aggregates in which they are included.

Underlying Gross Domestic Product by Industry (UnderlyingGDPbyIndustry) Data Request


Multiple
“All”
Parameter Name Type Description Required Values Default
value
Accepted

TableID Integer The unique GDP by Yes Yes ALL N/A


Industry table identifier
(ALL for All)

Frequency String A-Annual Yes Yes A N/A

List of year(s) of data to


Year Integer Yes Yes ALL N/A
retrieve (ALL for All)
List of industries to
Industry String Yes Yes ALL N/A
retrieve (ALL for All)

Examples of Underlying GDP by Industry (UnderlyingGDPbyIndustry) Data Requests


Value Added by Industry data for all industries for years 2012 and 2013:

[Link]
Key&method=GetData&DataSetName=underlyingGDPbyIndustry&Year=2013,2012&Industry=ALL&tableID=210&Fr
equency=A&ResultFormat=xml

All data in all tables for the Agriculture industry in 2012.

[Link]
Key&method=GetData&DataSetName=underlyingGDPbyIndustry&Year=2012&Industry=11&tableID=ALL&Frequenc
y=A&ResultFormat=xml

Appendix L: Page 1 of 3 October 27, 2020


API Call [GETPARAMETERVALUES] to Obtain a List of Available Values &
Descriptions for Each Parameter
[Details of each are described in the section below.]

Parameter Name Parameter Value List


[Link]
TableID Key%20Y&method=GetParameterValues&DataSetName=underlyingGDPbyIndust
ry&ParameterName=TableID&ResultFormat=xml

[Link]
Frequency Key%20Y&method=GetParameterValues&DataSetName=underlyingGDPbyIndust
ry&ParameterName=Frequency&ResultFormat=xml

[Link]
Year Key%20Y&method=GetParameterValues&DataSetName=underlyingGDPbyIndust
ry&ParameterName=Year&ResultFormat=xml

[Link]
Industry Key%20Y&method=GetParameterValues&DataSetName=underlyingGDPbyIndust
ry&ParameterName=Industry&ResultFormat=xml

Parameter Details

TableID Parameter (Required, multiple values accepted, no default value, ‘ALL’ for all tables)
 The TableID parameter is a unique table identifier. This parameter is required to query data and does accept multiple
comma separated values. If all tables are required, use the ‘ALL’ keyword.
 The Descr in the GetParameterValues result will contain an (A) indicating that the table is published annually. No
quarterly data is available in the underlying GDP by industry dataset

Frequency Parameter (Required, multiple values accepted, no default value)

 The Frequency parameter indicates whether annual or quarterly data are to be returned. This parameter is required
to query data and does accept multiple comma separated values.
 All tables are published annual only (Frequency = A). No quarterly data is currently available in the underlying GDP by
industry dataset
 If a data request is submitted for quarterly data then the user will receive the following error:

<Error APIErrorCode="206" APIErrorDescription="Error retrieving GDP by Industry data.">


<ErrorDetail Description="Invalid frequency: Q" />
</Error>

Year Parameter (Required, multiple values accepted, no default value, ’ALL‘ for all years)

Appendix L: Page 2 of 3 October 27, 2020


 The Year parameter indicates what periods of data are requested. This parameter is required to query data and does
accept multiple comma separated values. Use the keyword ‘ALL’ to return all periods of data.
 Underlying GDP by industry data publications begin in 1997 to present
 If a data request is submitted for data before the earliest estimate period the user will receive the following errors:

<Error APIErrorDescription="Error retrieving GDP by Industry data." APIErrorCode="206">


<ErrorDetail Description="Invalid year: 1996"/>
</Error>

Industry Parameter (Required, multiple values accepted, no default value, ‘ALL‘ for all industries)

 The Industry parameter indicates what periods of data are requested. This parameter is required to query data and
does accept multiple comma separated values. Use the keyword ‘ALL’ to return all industries.
 The Descr in the GetParameterValues result will contain (A) if the industry is published annually.
 If a data request is submitted for an industry that is not published in the requested tables the user will receive the
following error:

<Error APIErrorCode="206" APIErrorDescription="Error retrieving GDP by Industry data.">


<ErrorDetail Description="Invalid industry: 11" />
</Error>

General Use

 Data will be returned for all data cells that fit the requested criteria. If the request contains parameter values
requesting data for which only part of a set is available, only the data matching the criteria will be returned. Blanks
will not be returned for missing data.
 If no data fit the selected criteria the user will receive the following error:

<Error APIErrorCode="206" APIErrorDescription="Error retrieving GDP by Industry data.">


<ErrorDetail Description="No data exist for selected criteria" />
</Error>

Appendix L: Page 3 of 3 October 27, 2020


Appendix M – IntlServTrade (International Services Trade)

The DataSetName is IntlServTrade. This dataset contains annual data on U.S. international trade in services.
These data are updated each October to reflect the International Transactions Accounts annual update released
in June. BEA's statistics on services supplied through affiliates by multinational enterprises are not included in
this dataset. Five parameters are used to retrieve data from the IntlServTrade dataset, as follows:

IntlServTrade (International Services Trade) Data Request Parameters

Multiple
Parameter “All”
Type Description Required Values Default
Name value
Accepted
TypeOfService String The type of service requested No Yes All All

TradeDirection String The trade direction requested No Yes All All

Affiliation String The affiliation requested No Yes All All

AreaOrCountry String The area or country requested No Yes All AllCountries

Year String The year requested No Yes All All

Examples of IntlServTrade (International Services Trade) Data Requests

Imports of services from Germany for 2014 and 2015

[Link]
Key&method=GetData&DataSetName=IntlServTrade&TypeOfService=AllServiceTypes&TradeDirection=I
mports&Affiliation=AllAffiliations&AreaOrCountry=Germany&Year=2014,2015&ResultFormat=xml

Exports of telecommunications services by U.S. parents to their foreign affiliates for all years

[Link]
Key&method=GetData&DataSetName=IntlServTrade&TypeOfService=Telecom&TradeDirection=Exports
&Affiliation=UsParents&AreaOrCountry=AllCountries&Year=All&ResultFormat=xml

Appendix M: Page 1 of 4 December 1, 2020


API Call [GETPARAMETERVALUES] to Obtain a List of Available Values &
Descriptions for Each Parameter
[Details of each are described in the section below.]
Parameter
Parameter Value List
Name
[Link]
TypeOfService Key&method=GetParameterValues&DataSetName=IntlServTrade&ParameterName=
TypeOfService&ResultFormat=xml
[Link]
TradeDirection Key&method=GetParameterValues&DataSetName=IntlServTrade&ParameterName=
TradeDirection&ResultFormat=xml
[Link]
Affiliation Key&method=GetParameterValues&DataSetName=IntlServTrade&ParameterName=
Affiliation&ResultFormat=xml
[Link]
AreaOrCountry Key&method=GetParameterValues&DataSetName=IntlServTrade&ParameterName=
AreaOrCountry&ResultFormat=xml
[Link]
Year Key&method=GetParameterValues&DataSetName=IntlServTrade&ParameterName=
Year&ResultFormat=xml

Parameter Details

TypeOfService Parameter (optional, multiple values allowed)


The TypeOfService parameter specifies the type of service being traded (e.g. travel, transport, or insurance
services).

Exactly one TypeOfService parameter value other than “All” must be provided in all data requests unless exactly
one AreaOrCountry parameter value other than “All” is requested. That is, multiple Indicators can only be
specified if a single AreaOrCountry parameter is specified.

TradeDirection Parameter (optional, multiple values allowed)


The TradeDirection parameter specifies the trade direction of the services transactions. There are four valid
parameter values other than “All”:
1. Exports – Exports
2. Imports – Imports
3. Balance – Balance (exports less imports)
4. SupplementalIns – Supplemental detail on insurance transactions

Affiliation Parameter (optional, multiple values allowed)


The Affiliation parameter specifies the trade direction for the services transactions. There are five valid
parameter values other than “All”:
1. AllAffiliations – The total for all trade, whether affiliated or unaffiliated

Appendix M: Page 2 of 4 December 1, 2020


2. Unaffiliated – Unaffiliated trade
3. Affiliated – Affiliated trade
4. UsParents – U.S. parents’ trade with their foreign affiliates
5. UsAffiliates – U.S. affiliates’ trade with their foreign parent groups

AreaOrCountry Parameter (optional, multiple values allowed)


The AreaOrCountry parameter specifies the counterparty area or country of the services transactions.
The default parameter value (“AllCountries”) returns the total for all countries, while “All” returns all data
available by area and country.

Exactly one AreaOrCountry parameter value must be provided in all data requests unless exactly one
TypeOfService parameter value other than “All” is requested. That is, a list of countries can only be specified if a
single TypeOfService is specified.

For information on geographic area definitions, see


[Link]

Year Parameter (optional, multiple values allowed)


The Year parameter specifies the year of the data requested.

IntlServTrade (International Services Trade) Dimensions Elements in Return Data


Parameter Name Ordinal Datatype IsValue Description

TypeOfService 1 String No The TypeOfService parameter value of the data item.

TradeDirection 2 String No The TradeDirection parameter value of the data item.

Affiliation 3 String No The Affiliation parameter value of the data item.

AreaOrCountry 4 String No The AreaOrCountry parameter value of the data item.

Year 5 String No The Year parameter value of the data item.

TimeSeriesId 6 String No A unique identifier for the time series of the data item.
A description of the transactions measured in the data
TimeSeriesDescription 7 String No
item.
A string containing the time period for the data item in
TimePeriod 8 String No
the form YYYY for annual data
A string indicating the base unit of measurement of the
CL_UNIT 9 String No data item. For example, “USD” is used when the
reported statistic is in U.S. dollars.
An integer representing the base-10 exponent of the
UNIT_MULT 10 String No multiplier used to interpret the data value. For
example “6” refers to millions (DataValue × 10 6 ).
An integer or decimal value of the statistic. May be
DataValue 11 Numeric No
blank.

Appendix M: Page 3 of 4 December 1, 2020


A NoteRef attribute is also included in all data elements and acts as a reference to one of the Notes
elements in the returned data. The NoteRef attribute may have multiple values represented by a comma -
delimited string. Any NoteRef attribute included in the data is guaranteed to have a corresponding Notes
element. The NoteRef attribute may be blank.

Appendix M: Page 4 of 4 December 1, 2020


Appendix N – Regional (income, product, and employment by state and local area)
The Regional dataset contains income and employment estimates from the Regional Economic
Accounts by state, county, and metropolitan area. All data accessible through the Regional Interactive Tables on
[Link] are available through this dataset. Additional information may be found at
[Link]

Selected state data tables were discontinued Sept. 27, 2024, and selected county tables were discontinued on
Nov. 14, 2024, due to budget constraints. Additional information is at [Link]
data-tables.

Regional Request Parameters

Method=GetData
Multiple
“All”
Parameter Name Type Description Required Values Default
value*
Accepted
Published table
TableName String Yes No
name

LineCode Integer Line code in table Yes No ALL

STATE
COUNTY
The state, county or MSA
GeoFips String Yes Yes MIC
MSA code (unless
LineCode=ALL)
PORT
DIV
CSA
TERR
PO code

ALL
Year String Year requested No Yes LAST5 LAST5
LAST10

Parameter Details for GetData method

TableName paramete r – ( required, single value)


TableName specifies a published table from the regional accounts. Exactly one TableName must be
provided.

Main
TableName Description Years Areas
SASUMMARY State annual income and product summary 1998 States

Appendix N: Page 1 of 9 March 13, 2025


TASUMMARY Summary estimates of current dollar GDP for U.S. Territories 2002 Territori
es

TASUMMARY2 Summary estimates of real GDP for U.S. Territories 2002 Territori
es

CAINC1 Personal Income Summary: Personal Income, Population, Per Capita 1969 Counties,
Personal Income Metros

CAINC30 Economic Profile 1969 Counties,


Metros

CAINC4 Personal Income by Major Component 1969 Counties,


Metros

CAINC5N Personal Income by Major Component and Earnings by NAICS 2001 Counties,
Industry Metros

CAINC5S Personal Income by Major Component and Earnings by SIC Industry 1969-2000 Counties,
Metros

CAINC6N Compensation of Employees by NAICS Industry 2001 Counties,


Metros

CAINC6S Compensation of Employees by SIC Industry 1998-2000 Counties,


Metros

CAINC91 Gross Flow of Earnings 1990 Counties

CAGDP1 Gross domestic product (GDP) summary 2001 Counties,


Metros

CAGDP2 Gross domestic product (GDP) by county and metropolitan area 2001 Counties,
Metros

CAGDP8 Chain-type quantity indexes for real GDP by county and 2001 Counties,
metropolitan area Metros

CAGDP9 Real GDP by county and metropolitan area 2001 Counties,


Metros

CAGDP11 Contributions to percent change in real GDP 2002 Counties,


Metros

MAIRPD Implicit Price Deflators by MSA 2008 MSAs

MARPI Real Personal Income by MSA 2008 MSAs

Appendix N: Page 2 of 9 March 13, 2025


MARPP Regional Price Parities by MSA 2008 MSAs

PAIRPD Implicit Price Deflators by Portion 2008 State


portions

PARPI Real Personal Income by Portion 2008 State


portions

PARPP Regional Price Parities by Portion 2008 State


portions

SAGDP1 Gross domestic product (GDP) by state summary 1998 States

SAGDP11N Contributions to percent change in real GDP 1998 States

SAGDP2N Gross domestic product (GDP) by state 1997 States

SAGDP3N Taxes on production and imports less subsidies 1997 States

SAGDP4N Compensation of employees 1997 States

SAGDP5N Subsidies 1997 States

SAGDP6N Taxes on production and imports 1997 States

SAGDP7N Gross operating surplus 1997 States

SAGDP8N Quantity indexes for real GDP by state 1997 States

SAGDP9N Real GDP by state 1997 States

SAINC1 Personal Income Summary: Personal Income, Population, Per Capita 1929 States
Personal Income

SAINC30 Economic Profile 1958 States

SAINC35 Personal Current Transfer Receipts 1929 States

SAINC4 Personal Income and Employment by Major Component 1929 States

SAINC40 Property Income 1958 States

SAINC50 Personal Current Taxes 1948 States

SAINC51 Disposable Personal Income Summary: Disposable Personal Income, 1948 States
Population, and Per Capita Disposable Personal Income

Appendix N: Page 3 of 9 March 13, 2025


SAINC5H Personal Income by Major Component and Earnings by Industry 1929-57 States
(Historical)

SAINC5N Personal Income by Major Component and Earnings by NAICS 1998 States
Industry

SAINC5S Personal Income by Major Component and Earnings by SIC Industry 1958-2001 States

SAINC6N Compensation of Employees by NAICS Industry 1998 States

SAINC6S Compensation of Employees by SIC Industry 1958 States

SAINC7H Wages and Salaries by Industry (Historical) 1929-57 States

SAINC7N Wages and Salaries by NAICS Industry 1998 States

SAINC7S Wages and Salaries by SIC Industry 1958-2001 States

SAINC91 Gross Flow of Earnings 1990 States

SAIRPD Implicit Price Deflators by state 2008 States

SARPI Real Personal Income by state 2008 States

SARPP Regional Price Parities by state 2008 States

SAPCE1 Personal consumption expenditures (PCE) by major type of product 1997 States

SAPCE2 Per capita personal consumption expenditures (PCE) by major type 1997 States
of product

SAPCE3 Personal consumption expenditures (PCE) by state by type of 1997 States


product

SAPCE4 Personal consumption expenditures (PCE) by state by function 1997 States

SQGDP1 Gross domestic product (GDP) by state summary 2005 States

SQGDP11 Contributions to percent change in real GDP 2005 States

SQGDP2 Gross domestic product (GDP) by state 2005 States

SQGDP8 Quantity indexes for real GDP by state 2005 States

SQGDP9 Real GDP by state 2005 States

Appendix N: Page 4 of 9 March 13, 2025


SQINC1 Personal Income Summary: Personal Income, Population, Per Capita 1948 States
Personal Income

SQINC35 Personal Current Transfer Receipts 1948 States

SQINC4 Personal Income by Major Component 1948 States

SQINC5H Personal Income by Major Component and Earnings by Industry 1948-57 States
(Historical)

SQINC5N Personal Income by Major Component and Earnings by NAICS 1998 States
Industry

SQINC5S Personal Income by Major Component and Earnings by SIC Industry 1958-2001 States

SQINC6N Compensation of Employees by NAICS Industry 1998 States

SQINC6S Compensation of Employees by SIC Industry 1958-2001 States

SQINC7H Wages and Salaries by Industry (Historical) 1948-57 States

SQINC7N Wages and Salaries by NAICS Industry 1998 States

SQINC7S Wages and Salaries by SIC Industry 1958-2001 States

SAACEmpRatio Arts Employment Ratio 2001 States

SAACCompRatio Arts Compensation Ratio 2001 States

SAACArtsEmp ACPSA Employment 2001 States

SAACArtsComp ACPSA Compensation 2001 States

SAACEmpLQ Arts Employment Location Quotient 2001 States

SAACCompLQ Arts Compensation Location Quotient 2001 States

SAACVARatio Arts Value Added Ratio 2001 States

SAACArtsVA ACPSA Value Added 2001 States

SAACVALQ Arts Value Added Location Quotient 2001


States

PRGDP1-1 Gross domestic product (GDP) GeoFips=


2012 72000

Appendix N: Page 5 of 9 March 13, 2025


PRGDP1-2 Real GDP GeoFips=
2012 72000

PRGDP1-3 Percent change from preceding year in real gross domestic product GeoFips=
2012 72000

PRGDP1-4 Contributions to percent change in real GDP GeoFips=


2012 72000

PRGDP2-1 Personal consumption expenditures by type GeoFips=


2012 72000

PRGDP2-2 Real personal consumption expenditures by type GeoFips=


2012 72000

PRGDP2-3 Percent change from preceding year in real personal consumption GeoFips=
expenditures by type 2012 72000

PRGDP2-4 Contributions to percent change in real PCE GeoFips=


2012 72000

PRGDP3-1 Exports and imports of goods and services GeoFips=


2012 72000

PRGDP3-2 Real exports and imports of goods and services GeoFips=


2012 72000

PRGDP3-3 Percent change from preceding year in real exports and imports of GeoFips=
goods and services by type of product 2012 72000

PRGDP3-4 Contributions to percent change in real exports and imports GeoFips=


2012 72000

PRGDP4-1-1 Gross domestic investment GeoFips=


2012 72000

PRGDP4-1-2 Real gross domestic investment GeoFips=


2012 72000

PRGDP4-1-3 Percent change from preceding year in real gross domestic GeoFips=
investment by type 2012 72000

PRGDP4-2-1 Private fixed investment by type GeoFips=


2012 72000

PRGDP4-2-2 Real private fixed investment by type GeoFips=


2012 72000

Appendix N: Page 6 of 9 March 13, 2025


PRGDP4-2-3 Percent change from preceding year in real private fixed investment GeoFips=
by type 2012 72000

PRGDP4-2-4 Contributions to percent change in real private fixed investment by GeoFips=


type 2012 72000

LineCode parameter – (required, single value)


LineCode corresponds to the statistic in a table. It can either be one value(ie.1,10,11), or ‘ALL’ to retrieve
all the statistics for one GeoFips.

GeoFips parameter – (required, multiple value)


GeoFips specifies geography. It can be all states (STATE), all counties (COUNTY), all Metropolitan
Statistical Areas (MSA), all Micropolitan Statistical Areas (MIC), all Metropolitan Divisions (DIV), all
Combined Statistical Areas (CSA), all metropolitan/nonmetropolitan portions (PORT), U.S Territories
(TERR), or state post office abbreviation for all counties in one state (e.g. NY). It can also be a list of ANSI
state-county codes or metropolitan area codes. For example, the counties in Connecticut and Delaware–
09001,09003,09005,09007,09009,09011,09013,09015,10001,10003,10005.

Only one GeoFips is allowed when LineCode parameter value is ‘ALL’.

State, county, and metropolitan statistical area FIPS codes can be obtained from Census at
[Link] A comprehensive list of MSAs and their component
counties can be accessed at [Link]

Year parameter – (optional, multiple value)


Year is either a list of comma delimited years, LAST5, LAST10, or ALL. Year will default to LAST5
years if the parameter is not specified.

Errors
An invalid parameter value will result in an error code of 40, “The dataset requested requires parameters that
were missing from the request” plus a detailed message that explains the invalid value(s) entered.
Examples:
- For Invalid TableName a detailed message with “TableName entered is invalid” will display.
- When two or more parameter values are incompatible a detailed message will display “TableName entered
is incompatible with the entered GeoFips, LineCode and Year”.

- In the case of incompatible entries, the error message will tell the user which parameters are incompatible
and suggestions of the compatible values will be listed.

Examples of Regional Getdata method Requests


Personal income for 2012 and 2013 for all counties, in JSON format
[Link]
Key&method=GetData&datasetname=Regional&TableName=CAINC1&LineCode=
1&Year=2012,2013&GeoFips=COUNTY&ResultFormat=json

Real GDP for all states, all years, in XML format


[Link]
Appendix N: Page 7 of 9 March 13, 2025
method=GetData&datasetname=Regional&TableName=SAGDP9N&LineCode=2&Y
ear=ALL&GeoFips=STATE&ResultFormat=xml

Method=GetParameterValuesFiltered

API Call [GETPARAMETERVALUESFILTERED] to Obtain a List of Available Values & Descriptions for Each
Parameter, Filtered by Another Parameter [Examples below]

Target Filtered
Parameter Parameter Parameter Value List Explanation
Name Names
[Link]
36Character-
List Years for given
Year TableName Key&method=GetParameterValuesFiltered&datasetname
TableNames
=Regional&TargetParameter=Year&TableName=CAINC5N
,CAINC25N&ResultFormat=xml
[Link]
36Character- List of GeoFips for a
TableName
GeoFips Key&method=GetParameterValuesFiltered&datasetname given TableName and
LineCode
=Regional&TargetParameter=GeoFips&TableName=CAIN LineCode
C4&LineCode=10&ResultFormat=xml

[Link]
36Character- List of TableNames for
Year
TableName Key&method=GetParameterValuesFiltered&datasetname a given Year and
Geofips
=Regional&TargetParameter=TableName&GeoFips=0000 GeoFips
0&Year=2014&ResultFormat=xml

[Link]
36Character-
List of LineCodes for a
LineCode TableName Key&method=GetParameterValuesFiltered&datasetname
TableName
=Regional&TargetParameter=LineCode&TableName=SAI
NC4&ResultFormat=json

Parameter Details for GetParameterValuesFiltered method when used as filtered


parameters
TableName parameter
TableName specifies a published table from the regional accounts. Unlike with the GetData method the
GetParameterValuesFiltered method allows the user to filter the data by a list of comma-delimited values for
TableName.

Appendix N: Page 8 of 9 March 13, 2025


LineCode parameter
LineCode corresponds to the statistic in a table. Unlike with the GetData method it can be one value or a list
of comma-delimited LineCodes.
The available LineCodes are queried using the GetParameterValuesFiltered method. For example:
[Link]
Key&method=GetParameterValuesFiltered&datasetname=Regional&TargetParameter=LineCode&TableNa
me=SAINC5N&ResultFormat=json

GeoFips parameter
GeoFips specifies geography. It can be all states (STATE), all counties (COUNTY), all Metropolitan
Statistical Areas (MSA), or state post office abbreviation for all counties in one state (e.g. NY). It can also be a
list of ANSI state-county codes or metropolitan area codes. For example, the counties in Connecticut and
Delaware–
09001,09003,09005,09007,09009,09011,09013,09015,10001,10003,10005
State, county, and metropolitan statistical area FIPS codes can be obtained from Census at
[Link] A comprehensive list of MSAs and their component
counties can be accessed at [Link]

Year parameter
Year is either a single value, a list of comma-delimited years, or ALL

Errors
An invalid TableName LineCode, GeoFips or Year will result in an error code of 203, “No parameter values
match the filtered list requested” plus a detailed message that explains the invalid value(s) entered.
Examples:
- For Invalid LineCode a detailed message with “LineCode entered is invalid” will display.
- When there are no available GeoFips data for the entered LineCode a detailed message with “Values of
GeoFips and LineCode are incompatible” will display, followed by a suggestion of compatible values.

Additional information
Explanation of the estimates, including a schedule of the release of new regional data and Income and Product
methodologies can be found on our website: [Link] Definitions of the estimates can be accessed
at our glossary of regional definitions, at [Link]

Appendix N: Page 9 of 9 March 13, 2025

You might also like