Bea Web Service Api User Guide

User Manual: Pdf

Open the PDF directly: View PDF .
Page Count: 54

Download
Open PDF In Browser	View PDF

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 http://www.bea.gov/api/signup/ . To register, API users must
provide their name (or organization name), a valid email address, 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.
The URI 1 of the API is: http://www.bea.gov/api/data. All API access is through this URI; no other paths are
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:
http://www.bea.gov/api/data?&UserID=Your-36Character-Key&method=GETDATASETLIST&
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 three API methods that return meta-data about the API – corresponding to
datasets, parameters, and valid parameter values. There is one method that returns data.

Uniform Resource Identifier

1|Page

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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:
http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&method=GetData&datasetname=RegionalData&KeyCode=PCPI_CI&GeoFIPS=STATE&Year=2010&R
esultFormat=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:
http://www.bea.gov/api/data?&UserID=Your-36CharacterKey&method=GETDATASETLIST&ResultFormat=XML&
This request would return a list of the available datasets in JSON format:
http://www.bea.gov/api/data?&UserID=Your-36CharacterKey&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:

In XML form, the root node is always , followed by the child node . The node
contains children that echo the parameters passed in the request. The root node, ,
then has another child node, , containing the results of the request. The Results content is different
2
3

Java Script Object Notation
Extensible Markup Language

2|Page

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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":"METHOD",
"ParameterValue":"GETDATASETLIST"
},
{
"ParameterName":"ResultFormat",
"ParameterValue":"JSON"
}
]
},
"Results":{
"Dataset":[
{
"DatasetName":"RegionalData",
"DatasetDescription":"Retrieves various Regional datasets"
},
{
"DatasetName":"NIPA",
"DatasetDescription":"Standard NIPA tables"
}
]
}
}
}

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:

Meta-Data API Methods
The API contains three methods for retrieving meta-data as follows:
GetDataSetList – retrieves a list of the datasets currently offered.
Required Parameters: UserID, Method
Optional Parameters: ResultFormat
Result: Dataset node with DatasetName and DatasetDescription attributes.
3|Page

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Example Request:
http://www.bea.gov/api/data?&UserID=Your-36CharacterKey&method=GETDATASETLIST&ResultFormat=XML&
Example Return:

GetParameterList – 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 them
individually.
Example Request:
http://www.bea.gov/api/data?&UserID=Your-36CharacterKey&method=getparameterlist&datasetname=RegionalData&
Example Return:

4|Page

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

In this example, the parameters for the “RegionalData” dataset are being requested. The results indicate that the
dataset has three parameters: KeyCode, GeoFIPS, and Year.
KeyCode is a string typed parameter that would be used to specify which statistic is being requested. We can’t
tell from this what the valid KeyCodes 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).
GeoFIPS is a string typed parameter described as the GeoFIPS code. GeoFIPS is not required, and if it is not
supplied, the default value used is “STATE”. Multiple values are accepted, and there not a special value
meaning “all”.
Year is an integer typed parameter described as “Year”. It is not required in a request, and if is not included, the
default value used is “ALL”. Because this is also the AllValue value, the effect of not including the parameter
in a request would be to default to all available years.
GetParameterValues – 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:
http://bea.gov/api/data?&UserID=Your-36CharacterKey&method=GetParameterValues&datasetname=RegionalData&ParameterName=keycode&

Example Return:

5|Page

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

To summarize, the API includes three methods that retrieve meta-data about the statistics that are available: GetDatasetList, GetParameterList, and
GetParameterValues.

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)

6|Page

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Optional Parameters: ResultFormat, additional optional parameters (depending on the dataset)
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:
http://www.bea.gov/api/data?&UserID=Your-36CharacterKey&method=GetData&datasetname=RegionalData&KeyCode=PCPI_CI&GeoFIPS=STATE&Year=2009&Resul
tFormat=XML&

In this example, the GetData method is used to return the dataset named RegionalData. The KeyCode
parameter is used to request statistic for “Per Capita personal income (county annual income)” – as shown in the
ParameterList meta-data above. The GeoFIPS parameter value is “STATE” – meaning the data for all states is
requested. Finally, a single year’s data is requested – 2009.
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 commaseparated list.
Example Return:

7|Page

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

8|Page

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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 also several Data nodes having a NoteRef attribute with the value “*”, and there are several Notes
nodes having the matching NoteRef attribute (“*”). This should be interpreted to mean that the Notes nodes
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.

9|Page

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Appendix A – RegionalData (statistics by state, county, and MSA)
The RegionalData dataset contains estimates from the Regional Economic Accounts. These include estimates of
GDP by state and metropolitan area; estimates of personal income and employment by state, metropolitan area,
and county; and regional price parities by state and MSA.

RegionalData Request Parameters
Parameter Name

Type

Description

Required

Multiple
Values
Accepted

KeyCode

String

The code for the
statistic requested

Yes

“All”
value

Default

STATE

ALL

GeoFips

String

The state, county or
MSA code

Yes

STATE
or
COUNTY
or
MSA

Year

String

Year requested

Yes

ALL

Examples of RegionalData Requests
Personal income for 2011 and 2012 for all counties, in JSON format
http://bea.gov/api/data/?UserID=Your-36CharacterKey&method=GetData&datasetname=RegionalData&KeyCode=TPI_CI&Year=2012,2011&Ge
oFips=COUNTY&ResultFormat=json

Real GDP for all years, all states, in XML format
http://bea.gov/api/data/?UserID=Your-36CharacterKey&method=GetData&datasetname=RegionalData&KeyCode=GDP_SP&Year=ALL&GeoFips=
STATE&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
GeoFips

10 | P a g e

Parameter Value List
http://bea.gov/api/data/?UserID=Your-36CharacterKey&method=GetParameterValues&datasetname=RegionalData&ParameterNa
me=GeoFips&ResultFormat=xml
T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Year
KeyCode

http://bea.gov/api/data/?UserID=Your-36CharacterKey&method=GetParameterValues&datasetname=RegionalData&ParameterNa
me=Year&ResultFormat=xml
http://bea.gov/api/data/?UserID=Your-36CharacterKey&method=GetParameterValues&datasetname=RegionalData&ParameterNa
me=KeyCode&ResultFormat=xml

Summary of available data
Statistics newly available to the API are highlighted

KeyCode

Classification

Statistic

BeginYear

GDP_SP

state annual product

GDP in current dollars

1997

RGDP_SP

state annual product

Real GDP in chained dollars

1997

PCRGDP_SP

state annual product

Per capita real GDP

1997

COMP_SP

state annual product

Compensation of employees

1997

TOPILS_SP

state annual product

Taxes on production and
imports less subsidies

1997

GOS_SP

state annual product

Gross operating surplus

1997

SUBS_SP

state annual product

Subsidies

1997

TOPI_SP

state annual product

Taxes on production and
imports

1997

GDP_MP

MSA annual product

GDP in current dollars

2001

RGDP_MP

MSA annual product

Real GDP in chained dollars

2001

PCRGDP_MP

MSA annual product

Per capita real GDP

2001

TPI_SI

state annual income

Total personal income

1929

11 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

POP_SI
PCPI_SI
NFPI_SI
FPI_SI
EARN_SI

state annual income
state annual income
state annual income
state annual income
state annual income

CGSI_SI

state annual income

AR_SI

state annual income

NE_SI

state annual income

DIR_SI

state annual income

PCTR_SI

state annual income

WS_SI

state annual income

SUPP_SI

state annual income

PROP_SI

state annual income

EMP000_SI

state annual income

EMP100_SI
EMP200_SI
PJEARN_SI
PJWS_SI
PJCOMP_SI
DPI_SI

state annual income
state annual income
state annual income
state annual income
state annual income
state annual income

PCDPI_SI

state annual income

PCNE_SI

state annual income

PCTRAN_SI

state annual income

PCINCMAIN_SI

state annual income

PCUNIC_SI

state annual income

PCRET_SI

state annual income

PCDIR_SI

state annual income

TPI_CI
POP_CI

county annual income
county annual income

12 | P a g e

Population
Per capita personal income
Nonfarm personal income
Farm income
Earnings by place of work
Contributions for government
social insurance
Adjustment for residence
Net earnings by place of
residence
Dividends, interest, and rent
Personal current transfer
receipts
Wages and salaries
Supplements to wages and
salaries
Proprietors’ Income
Total employment (full and
part time)
Wage and salary employment
Proprietors’ employment
Average earnings per job
Average wage per job
Average compensation per job
Disposable personal income
Per capita disposable personal
income (dollars)
Per capita net earnings
Per capita personal current
transfer receipts
Per capita income
maintenance
Per capita unemployment
insurance compensation
Per capita retirement and
other
Per capita dividends, interest,
and rent

1929
1929
1929
1929
1929

Total personal income
Population

1969
1969

T u e s d a y ,

S e p t e m b e r

1929
1948
1929
1929
1929
1929
1929
1929
1969
1969
1969
1969
1969
1998
1948
1948
1958
1958
1958
1958
1958
1958

3 0 ,

2 0 1 4

PCPI_CI
NFPI_CI
FPI_CI
EARN_CI

county annual income
county annual income
county annual income
county annual income

CGSI_CI

county annual income

AR_CI

county annual income

NE_CI

county annual income

DIR_CI

county annual income

PCTR_CI

county annual income

WS_CI

county annual income

SUPP_CI

county annual income

PROP_CI

county annual income

EMP000_CI

county annual income

EMP100_CI
EMP200_CI
PJEARN_CI
PJWS_CI
PJCOMP_CI
PCNE_CI

county annual income
county annual income
county annual income
county annual income
county annual income
county annual income

PCTRAN_CI

county annual income

PCINCMAIN_CI

county annual income

PCUNIC_CI

county annual income

PCRET_CI

county annual income

PCDIR_CI

county annual income

TPI_MI
POP_MI
PCPI_MI
NFPI_MI
FPI_MI
EARN_MI

MSA annual income
MSA annual income
MSA annual income
MSA annual income
MSA annual income
MSA annual income

13 | P a g e

Per capita personal income
Nonfarm personal income
Farm income
Earnings by place of work
Contributions for government
social insurance
Adjustment for residence
Net earnings by place of
residence
Dividends, interest, and rent
Personal current transfer
receipts
Wages and salaries
Supplements to wages and
salaries
Proprietors' Income
Total employment (full and
part time)
Wage and salary employment
Proprietors’ employment
Average earnings per job
Average wage per job
Average compensation per job
Per capita net earnings
Per capita personal current
transfer receipts
Per capita income
maintenance
Per capita unemployment
insurance compensation
Per capita retirement and
other
Per capita dividends, interest,
and rent

1969
1969
1969
1969

Total personal income
Population
Per capita personal income
Nonfarm personal income
Farm income
Earnings by place of work

1969
1969
1969
1969
1969
1969

T u e s d a y ,

S e p t e m b e r

1969
1969
1969
1969
1969
1969
1969
1969
1969
1969
1969
1969
1969
2001
1969
1969
1969
1969
1969
1969

3 0 ,

2 0 1 4

CGSI_MI

MSA annual income

AR_MI

MSA annual income

NE_MI

MSA annual income

DIR_MI

MSA annual income

PCTR_MI

MSA annual income

WS_MI

MSA annual income

SUPP_MI

MSA annual income

PROP_MI

MSA annual income

EMP000_MI

MSA annual income

EMP100_MI
EMP200_MI
PJEARN_MI
PJWS_MI
PJCOMP_MI
PCNE_MI

MSA annual income
MSA annual income
MSA annual income
MSA annual income
MSA annual income
MSA annual income

PCTRAN_MI

MSA annual income

PCINCMAIN_MI

MSA annual income

PCUNIC_MI

MSA annual income

PCRET_MI

MSA annual income

PCDIR_MI

MSA annual income

TPI_QI
NFPI_QI
FPI_QI
EARN_QI

state quarterly income
state quarterly income
state quarterly income
state quarterly income

CGSI_QI

state quarterly income

AR_QI

state quarterly income

NE_QI

state quarterly income

DIR_QI
PCTR_QI

state quarterly income
state quarterly income

14 | P a g e

Contributions for government
social insurance
Adjustment for residence
Net earnings by place of
residence
Dividends, interest, and rent
Personal current transfer
receipts
Wages and salaries
Supplements to wages and
salaries
Proprietors’ income
Total employment (full and
part time)
Wage and salary employment
Proprietors’ employment
Average earnings per job
Average wage per job
Average compensation per job
Per capita net earnings
Per capita personal current
transfer receipts
Per capita income
maintenance
Per capita unemployment
insurance compensation
Per capita retirement and
other
Per capita dividends, interest,
and rent

1969
1969
1969
1969
1969
1969
1969
1969
1969
1969
1969
1969
1969
2001
1969
1969
1969
1969
1969
1969

Total personal income
Nonfarm personal income
Farm income
Earnings by place of work
Contributions for government
social insurance
Adjustment for residence
Net earnings by place of
residence
Dividends, interest, and rent
Personal current transfer
T u e s d a y ,

S e p t e m b e r

1948
1948
1948
1948
1948
1948
1948
1948
1948
3 0 ,

2 0 1 4

receipts
WS_QI

state quarterly income

SUPP_QI

state quarterly income

PROP_QI

state quarterly income

RPI_SI

state regional price parities

RPCPI_SI

state regional price parities

RPPIPD_SI
RPPALL_SI
RPPGOODS_SI
RPPRENTS_SI
RPPOTHER_SI

state regional price parities
state regional price parities
state regional price parities
state regional price parities
state regional price parities

RPI_MI

MSA regional price parities

RPCPI_MI

MSA regional price parities

RPPIPD_MI
RPPALL_MI
RPPGOODS_MI
RPPRENTS_MI
RPPOTHER_MI

MSA regional price parities
MSA regional price parities
MSA regional price parities
MSA regional price parities
MSA regional price parities

Wages and salaries
Supplements to wages and
salaries
Proprietors’ income

1948

Real personal income
Per capita real personal
income
Implicit regional price deflator
RPPs: All items
RPPs: Goods
RPPs: Services: Rents
RPPs: Services: Other

2008

Real personal income
Per capita real personal
income
Implicit regional price deflator
RPPs: All items
RPPs: Goods
RPPs: Services: Rents
RPPs: Services: Other

2008

1948
1948

2008
2008
2008
2008
2008
2008

Parameter Details
KeyCode parameter – (required, single value)
KeyCode specifies a statistic drawn from the regional income and product accounts public tables. Exactly one
KeyCode must be provided.
GeoFips parameter – (optional, multiple value)
GeoFips specifies geography. It can be all states (STATE), all counties (COUNTY), or all MSAs (MSA). It can
also be a list of ANSI state-county codes or metropolitan statistical area codes. For example, the counties in
Connecticut and Delaware–
09001,09003,09005,09007,09009,09011,09013,09015,10001,10003,10005
GeoFips will default to all states, counties, or MSAs, if not specified. State, county, and metropolitan statistical
area FIPS codes can be obtained from Census at http://www.census.gov/geo/www/ansi/ansi.html. A
15 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

comprehensive list of MSAs and their component counties can be accessed here
http://www.bea.gov/regional/docs/msalist.cfm.
Year parameter – (optional, multiple value)
Year is either a list of years, or ALL. Year will default to all available years if the parameter is not specified.
Errors
An invalid KeyCode will result in an error code of 99, unknown error.
An invalid GeoFips or Year will result in an error code of 101, no data returned.
Additional information
Explanation of the estimates, including a schedule of the release of new regional data, can be found in the
regional section of our website: http://bea.gov/regional/. Definitions of the estimates can be accessed at our
glossary of regional definitions, at http://bea.gov/regional/definitions/. Regional Product and Income
Methodologies can be found at http://bea.gov/regional/methods.cfm.

16 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Appendix B – NIPA (National Income and Product Accounts)
The NIPA dataset contains data from the standard set of NIPA tables as published in the Survey of Current
Business. Availability of updated NIPA data follows the BEA News Release schedule as posted on the BEA
web site. The NIPA dataset may be unavailable for a few minutes preceding the monthly GDP release while
data is being updated (as it is for all other methods of acquiring newly released data). Four parameters are used
to retrieve data from the NIPA dataset, as follows:
Name
Type
Description
Is Required
Multiple
“All” value
Values
Accepted
TableID
Integer The standard NIPA Yes
No
N/A
table identifier
Frequency
String
A - Annual, QYes
Yes
N/A
Quarterly, MMonthly
Year
integer List of year(s) of
Yes
Yes
“X”
data to retrieve
ShowMillions String
A flag indicating
No
No
N/A
that million-dollar
data should be
returned
TableID Parameter
The TableID parameter is an integer that refers to a specific NIPA table. As shown above, the parameter is
required, and only one NIPA table can be requested in each GetData submission. The list of valid TableIDs
may change depending on the monthly news release cycles. For example, after the monthly GDP release and
before the following Personal Income release, a few of the Personal Income tables are temporarily unavailable.
The full list of valid NIPA TableIDs is as follows:

17 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

18 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

19 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

20 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Note that the description of each table also indicates the frequencies that are available for each table –
A=Annual, Q=Quarterly, M=Monthly
Requesting an invalid TableID returns this error:

Omitting the TableID parameter returns this error:

Frequency Parameter
The Frequency parameter is a string that refers to the time series for the requested NIPA table. As shown
above, the parameter is required, and multiple frequencies can be requested in each GetData submission.
Multiple frequencies are requested by specifying them as a comma-delimited string, e.g. “A,Q,M”. When data
is requested for frequencies that don’t exist for a particular NIPA table, only data that exists is returned.
The full list of valid frequencies is as follows:

If an invalid frequency is supplied in the GetData request (e.g. “Z”), this error is returned:

21 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

If only frequencies that don’t exist for a particular table are requested, this error is returned:

Omitting the Frequency parameter returns this error:

Year Parameter
The Year parameter is an integer that specifies the year(s) of data for the requested NIPA table. As shown
above, the parameter is required, and multiple years can be requested in each GetData submission. Multiple
years are requested by specifying them as a comma-delimited string, e.g. “2000,2001,2002”. When data is
requested for years that don’t exist for a particular NIPA table, only data that exists is returned. For example, if
years in the future are requested – like “2013,2014,2015”, the most recent available data is returned starting
with 2013. If the request supplies the special value “X” for the Year parameter, all available years of data are
returned. Note that using the “X” value for all years can return large amounts of data, and should be avoided
when the actual required years are known.
If only years that don’t exist for a particular table are requested, this error is returned:

Omitting the Year parameter returns this error:

Using the GetParameterValues meta-data retrieval method for the Year parameter returns a list of the valid year
ranges for each NIPA table. Each NIPA table may have a different range of years available for different
frequencies, so the valid combinations of years and frequencies are shown for each NIPA table. For example,
Table 1 (at the time of this writing) has annual data from 1930 through 2011, Quarterly data from 1947 through
2012, and no monthly data as indicated in this example return data from the GetParameterValues method:

22 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

23 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

ShowMillions Parameter
The ShowMillions parameter is a string indicates whether data for the requested NIPA table should be returned
in million-dollar units. As shown above, the parameter is optional. Million-dollar estimate data doesn’t exist
for all tables, and data is returned in million-dollar units only if available. When million-dollar data doesn’t
exist for a table, data is returned as if million-dollar data was not requested. In addition, requests for milliondollar data are always returned with a cautionary footnote about million-dollar estimates.
The valid values for the ShowMillions parameter are:

Invalid values for the ShowMillions parameter (e.g. “Z” or “cupcake”) are ignored.

NIPA Dataset Result Data
The NIPA dataset returns data in the standard form described in the API User documentation. In XML form,
the main structure of a result is:

The Request node of the result contains the parameters supplied to the request. For purposes of this example,
the parameters are:

The result returned from this request would be:

24 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

All requests for the NIPA dataset will return similar results, including the elements that describe the
dimensions, data, and footnotes (Dimensions, Data, and Notes).
Dimensions Elements
The dimensions included in the returned data are:
Ordinal
1
2
3
4
5
6
7
8

Name
TableID
SeriesCode
LineNumber
LineDescription
TimePeriod
CL_UNIT
UNIT_MULT
DataValue
NoteRef 4

Datatype
numeric
string
numeric
No
string
string
numeric
numeric
string

IsValue
No
No
No
No
No
No
No
Yes
No

The Noteref attribute included in the data is not shown as one of the dimension elements. Noterefs may appear as an attribute of any
element in the result data (except other Noterefs), and refer to a particular NoteRef element.

25 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

LineNumber – The line number of the data item as shown in published print versions of the published NIPA
table.
LineDescription – The “stub” or description of the statistic in the published NIPA table.
TimePeriod – A string containing the time period for the data item in the form YYYY for annual data,
YYYYQn for quarterly data (where n is the quarter digit), and YYYYMnn for monthly data (where nn is 2
digits representing the month – i.e. ‘01’ through ‘12’).
CL_UNIT – A string containing “USD” when the reported statistic is in U.S. dollars, or “PC” when the reported
statistic is a percent, index, or contribution.
UNIT_MULT – An integer representing the base-10 exponent of the multiplier used to interpret the data value.
For example “6” refers to millions (DataValue X 106) and “9” refers to billions (DataValue X 109).
DataValue – An integer or decimal value of the statistic. Always a numeric value, but may contain embedded
commas.
NoteRef – a reference to one of the Notes elements. Noteref in a data element always corresponds to the Noteref
in a Notes element. The Noteref attribute may have multiple values represented by a comma-delimited string.
This attribute can appear in any data element, or in the Results element. 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 footnote
references that apply to specific lines/series/timeperiods may be included in the comma-delimited Noteref string
value.

26 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Appendix C – NIUnderlyingDetail (National Income and Product Accounts)
The NIUnderlyingDetail dataset contains detailed estimate data from underlying NIPA series that appear in the
national income and product account (NIPA) tables as published in the Survey of Current Business. Three
parameters are used to retrieve data from the NIUnderlyingDetail dataset, as follows:
Name
Type
Description
Is Required
Multiple
“All” value
Values
Accepted
TableID
Integer The standard NIPA Yes
No
N/A
table identifier
Frequency
String
A - Annual, QYes
Yes
N/A
Quarterly, MMonthly
Year
integer List of year(s) of
Yes
Yes
“X”
data to retrieve
TableID Parameter
The TableID parameter is an integer that refers to a specific NIPA table. As shown above, the parameter is
required, and only one Underlying Detail table can be requested in each GetData submission.
The full list of valid Underlying Detail TableIDs is as follows:

27 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Note that the description of each table also indicates the frequencies that are available for each table –
A=Annual, Q=Quarterly, M=Monthly.
Requesting an invalid TableID returns this error:

Omitting the TableID parameter returns this error:

Frequency Parameter
The Frequency parameter is a string that refers to the time series for the requested Underlying Detail table. As
shown above, the parameter is required, and multiple frequencies can be requested in each GetData submission.
Multiple frequencies are requested by specifying them as a comma-delimited string, e.g. “A,Q,M”. When data
is requested for frequencies that don’t exist for a particular Underlying Detail table, only data that exists is
returned.
The full list of valid frequencies is as follows:

If an invalid frequency is supplied in the GetData request (e.g. “Z”), this error is returned:

If only frequencies that don’t exist for a particular table are requested, this error is returned:

28 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Omitting the Frequency parameter returns this error:

Year Parameter
The Year parameter is an integer that specifies the year(s) of data for the requested Underlying Detail table. As
shown above, the parameter is required, and multiple years can be requested in each GetData submission.
Multiple years are requested by specifying them as a comma-delimited string, e.g. “2000,2001,2002”. When
data is requested for years that don’t exist for a particular Underlying Detail table, only data that exists is
returned. For example, if years in the future are requested – like “2013,2014,2015”, the most recent available
data is returned starting with 2013. If the request supplies the special value “X” for the Year parameter, all
available years of data are returned. Note that using the “X” value for all years can return large amounts of
data, and should be avoided when the actual required years are known.
If only years that don’t exist for a particular table are requested, this error is returned:

Omitting the Year parameter returns this error:

Using the GetParameterValues meta-data retrieval method for the Year parameter returns a list of the valid year
ranges for each UNDERLYING DETAIL table. Each UNDERLYING DETAIL table may have a different
range of years available for different frequencies, so the valid combinations of years and frequencies are shown
for each UNDERLYING DETAIL table. For example, Table 1 (at the time of this writing) has no annual data,
Quarterly data from 1967 through 1997, and monthly data from 1967 through 1997 as indicated in this example
return data from the GetParameterValues method:

29 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

UNDERLYING DETAIL Dataset Result Data
The UNDERLYING DETAIL dataset returns data in the standard form described in the API User
documentation. In XML form, the main structure of a result is:

The Request node of the result contains the parameters supplied to the request. For purposes of this example,
the parameters are:

30 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

The result returned from this request would be:

31 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

All requests for the Underlying Detail dataset will return similar results, including the elements that describe the
dimensions, data, and footnotes (Dimensions, Data, and Notes).
Dimensions Elements
The dimensions included in the returned data are:
Ordinal
1
2
3
4
5
6
7
8

Name
TableID
SeriesCode
LineNumber
LineDescription
TimePeriod
CL_UNIT
UNIT_MULT
DataValue
NoteRef 5

Datatype
numeric
string
numeric
No
string
string
numeric
numeric
string

IsValue
No
No
No
No
No
No
No
Yes
No

32 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

LineNumber – The line number of the data item as shown in published print versions of the published
Underlying Detail table.
LineDescription – The “stub” or description of the statistic in the published Underlying Detail table.
TimePeriod – A string containing the time period for the data item in the form YYYY for annual data,
YYYYQn for quarterly data (where n is the quarter digit), and YYYYMnn for monthly data (where nn is 2
digits representing the month – i.e. ‘01’ through ‘12’).
CL_UNIT – A string containing “USD” when the reported statistic is in U.S. dollars, or “PC” when the reported
statistic is a percent, index, or contribution.
UNIT_MULT – An integer representing the base-10 exponent of the multiplier used to interpret the data value.
For example “6” refers to millions (DataValue X 106) and “9” refers to billions (DataValue X 109).
DataValue – An integer or decimal value of the statistic. Always a numeric value, but may contain embedded
commas.
NoteRef – a reference to one of the Notes elements. Noteref in a data element always corresponds to the Noteref
in a Notes element. The Noteref attribute may have multiple values represented by a comma-delimited string.
This attribute can appear in any data element, or in the Results element. Any Noteref attribute included in the
data is guaranteed to have a corresponding Notes element. For the Underlying Detail dataset, every data
element includes at least one Noteref that corresponds to a Note element containing the title of the table.
Additional footnote references that apply to specific lines/series/timeperiods may be included in the commadelimited Noteref string value.

33 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Appendix D – Fixed Assets
The FixedAssets 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
TableID
Integer The standard Fixed Yes
No
N/A
Assets table
identifier
Year
integer List of year(s) of
Yes
Yes
“X”
data to retrieve
TableID Parameter
The TableID parameter is an integer that refers to a specific Fixed Assets table. As shown above, the parameter
is required, and only one Fixed Assets table can be requested in each GetData submission.
The full list of valid Fixed Assets TableIDs is as follows:

34 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Note that the description of each table also indicates that only annual data is available.
Requesting an invalid TableID returns this error:

35 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Omitting the TableID parameter returns this error:

Year Parameter
The Year parameter is an integer that specifies the year(s) of data for the requested Fixed Assets table. As
shown above, the parameter is required, and multiple years can be requested in each GetData submission.
Multiple years are requested by specifying them as a comma-delimited string, e.g. “2000,2001,2002”. When
data is requested for years that don’t exist for a particular Fixed Assets table, only data that exists is returned.
For example, if years in the future are requested – like “2013,2014,2015”, the most recent available data is
returned starting with 2013. If the request supplies the special value “X” for the Year parameter, all available
years of data are returned. Note that using the “X” value for all years can return large amounts of data, and
should be avoided when the actual required years are known.
If only years that don’t exist for a particular table are requested, this error is returned:

Omitting the Year parameter returns this error:

Using the GetParameterValues meta-data retrieval method for the Year parameter returns a list of the valid year
ranges for each Fixed Assets table. Each Fixed Assets table may have a different range of years. For example,
Table 1 (at the time of this writing) has annual data from 1925 through 2012 available as indicated in this
example return data from the GetParameterValues method:

36 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

37 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Fixed Assets Dataset Result Data
The Fixed Assets dataset returns data in the standard form described in the API User documentation. In XML
form, the main structure of a result is:

The Request node of the result contains the parameters supplied to the request. For purposes of this example,
the parameters are:

The result returned from this request would be:

38 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

All requests for the Fixed Assets dataset will return similar results, including the elements that describe the
dimensions, data, and footnotes (Dimensions, Data, and Notes).
Dimensions Elements
The dimensions included in the returned data are:
Ordinal
1
2
3
4
5
6
7
8

Name
TableID
SeriesCode
LineNumber
LineDescription
TimePeriod
CL_UNIT
UNIT_MULT
DataValue
NoteRef 6

Datatype
numeric
string
numeric
No
string
string
numeric
numeric
string

IsValue
No
No
No
No
No
No
No
Yes
No

Within the set of “Data” elements returned in the result, each of the dimensions is represented as an attribute
(name/value pair). All the dimensions (attributes) have a single value, except the Noteref dimension, which can
have multiple values represented as a comma-delimited string. The dimensions (attributes) are defined as
follows:
TableID – The standard Fixed Assets table ID as submitted in the request (an integer).
SeriesCode – A string containing the a unique identifier for the line item in the published Fixed Assets table.
LineNumber – The line number of the data item as shown in published print versions of the published Fixed
Assets table.
LineDescription – The “stub” or description of the statistic in the published Fixed Assets table.
TimePeriod – A string containing the time period for the data item in the form YYYY for annual data.
CL_UNIT – A string containing “USD” when the reported statistic is in U.S. dollars, or “PC” when the reported
statistic is a percent, index, or contribution.
UNIT_MULT – An integer representing the base-10 exponent of the multiplier used to interpret the data value.
For example “6” refers to millions (DataValue X 106) and “9” refers to billions (DataValue X 109).

39 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

DataValue – An integer or decimal value of the statistic. Always a numeric value, but may contain embedded
commas.
NoteRef – a reference to one of the Notes elements. Noteref in a data element always corresponds to the Noteref
in a Notes element. The Noteref attribute may have multiple values represented by a comma-delimited string.
This attribute can appear in any data element, or in the Results element. Any Noteref attribute included in the
data is guaranteed to have a corresponding Notes element. For the Fixed Assets dataset, every data element
includes at least one Noteref that corresponds to a Note element containing the title of the table. Additional
footnote references that apply to specific lines may be included in the comma-delimited Noteref string value.

40 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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
Type

Description

Required

Multiple
Values
Accepted

DirectionOfInvestment

String

Outward = US direct
investment abroad
Inward = Foreign
investment in the US

Yes

Not
accepted

SeriesID

Integer

Data Series Identifier

Yes

All

Classification

String

Yes

Year

String

Yes

Not
accepted
All

Country

String

Yes

All

Industry

String

Yes

All

GetFootnotes

String

Not
accepted

Parameter Name

Results by country
and/or industry
Time Period
Geographic Area
Code
Industry Code
Yes = Include
footnotes
No = Exclude footnotes

“All”
value

Default

All

Examples of Direct Investment (DI) Data Requests
U.S. direct investment position in China and Asia for 2011 and 2012
http://www.bea.gov/api/data/?&SeriesId=30&UserID= Your-36CharacterKey&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

41 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

http://www.bea.gov/api/data/?&SeriesId=22,23,24,25,26,27&UserID= Your-36CharacterKey&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
Parameter Name

Type

DirectionOfInvestment

String

OwnershipLevel

Binary

NonBankAffiliatesOnly

Binary

SeriesID

Integer

Classification

String

Year

String

Country

String

Industry

String

State

String

GetFootnotes

String

Description
Outward, Inward,
State, Parent
0 = Majority-Owned
Affiliates
1 = All Affiliates
0 = Both Bank and
NonBank Affiliates
1 = Nonbank
Affiliates
Data Series
Identifier
Results by country
and/or industry
Time Period
Geographic Area
Code
Industry Code
Two-digit State FIPS
Code
Yes = Include
footnotes
No = Exclude
footnotes

Required

Multiple
Values
Accepted

“All”
value

Yes

Not
accepted

Yes

Not
accepted

Yes

Not
accepted

Yes

All

Yes

Not
accepted
All

Yes

All

Yes

All

Not
accepted

Default

All

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
http://www.bea.gov/api/data/?&UserID= Your-36CharacterKey&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

42 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

http://www.bea.gov/api/data/?&UserID= Your-36CharacterKey&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

DirectionOfInvestment

http://www.bea.gov/api/data/?&UserID= Your-36Character-Key
Y&method=GetParameterValues&DataSetName=MNE&ParameterName=Dir
ectionOfInvestment&ResultFormat=xml

OwnershipLevel

http://www.bea.gov/api/data/?&UserID= Your-36Character-Key
&method=GetParameterValues&DataSetName=MNE&ParameterName=Ow
nershipLevel&ResultFormat=xml

NonBankAffiliatesOnly

http://www.bea.gov/api/data/?&UserID= Your-36Character-Key
&method=GetParameterValues&DataSetName=MNE&ParameterName=Non
bankAffiliatesOnly&ResultFormat=xml

SeriesID

http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&method=GetParameterValues&DataSetName=MNE&ParameterName=
SeriesID&ResultFormat=xml

Classification

http://www.bea.gov/api/data/?&UserID= Your-36Character-Key
&method=GetParameterValues&DataSetName=MNE&ParameterName=Clas
sification&ResultFormat=xml

Year

http://www.bea.gov/api/data/?&UserID= Your-36Character-Key
&method=GetParameterValues&DataSetName=MNE&ParameterName=Yea
r&ResultFormat=xml

Country

http://www.bea.gov/api/data/?&UserID= Your-36Character-Key
&method=GetParameterValues&DataSetName=MNE&ParameterName=cou
ntry&ResultFormat=xml

Industry

http://www.bea.gov/api/data/?&UserID= Your-36Character-Key
&method=GetParameterValues&DataSetName=MNE&ParameterName=Ind
ustry&ResultFormat=xml

State

http://www.bea.gov/api/data/?&UserID= Your-36Character-Key
&method=GetParameterValues&DataSetName=MNE&ParameterName=stat
e&ResultFormat=xml

GetFootnotes

http://www.bea.gov/api/data/?&UserID= Your-36Character-Key
&method=GetParameterValues&DataSetName=MNE&ParameterName=Get
Footnotes&ResultFormat=xml

43 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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)
1. ‘Country’ – Returns a total value by country only
2. ‘Industry’ – Returns a total value by industry only
44 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

3. ‘CountryByIndustry’ – Returns values for a country broken out by industry (where available)
4. ‘IndustryByCountry’ – Returns values for an industry broken out by country (where available)
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 allindustries 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 2007 and earlier years), property, plant, and
equipment.
Refer to the GETPARAMETERVALUES API call above for the list of the two-digit Federal Information
Processing Standards (FIPS) codes, or the FIPS codes found at this link:
http://www.epa.gov/envirofw/html/codes/state.html. 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

45 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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
Parameter Name

Type

Description

Required

Multiple
Values
Accepted

“All”
value

Default

TableID

Integer

The unique GDP by
Industry table identifier
(ALL for All)

Yes

ALL

N/A

Frequency

String

A - Annual, Q-Quarterly

Yes

A,Q

N/A

Year

Integer

Yes

ALL

N/A

Industry

String

Yes

ALL

N/A

List of year(s) of data to
retrieve (ALL for All)
List of industries to
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:
http://www.bea.gov/api/data/?&UserID=%20Your-36CharacterKey&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.
http://www.bea.gov/api/data/?&UserID=%20Your-36CharacterKey&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
46 | P a g e

Parameter Value List

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

TableID
Frequency
Year
Industry

http://www.bea.gov/api/data/?&UserID=%20Your-36CharacterKey%20Y&method=GetParameterValues&DataSetName=GDPbyIndustry&Param
eterName=TableID&ResultFormat=xml
http://www.bea.gov/api/data/?&UserID=%20Your-36CharacterKey%20Y&method=GetParameterValues&DataSetName=GDPbyIndustry&Param
eterName=Frequency&ResultFormat=xml
http://www.bea.gov/api/data/?&UserID=%20Your-36CharacterKey%20Y&method=GetParameterValues&DataSetName=GDPbyIndustry&Param
eterName=Year&ResultFormat=xml
http://www.bea.gov/api/data/?&UserID=%20Your-36CharacterKey%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:

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.

47 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

• 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:

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:

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:

48 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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
Parameter Name

Type

Indicator

String

AreaOrCountry

String

Frequency

String

Year

String

Description
The indicator code
for the type of
transaction
requested
The area or country
requested
A - Annual, QSA Quarterly seasonally
adjusted, QNSA Quarterly not
seasonally adjusted
Year requested

Required

Multiple
Values
Accepted

“All”
value

Default

Yes

All

Yes

All

AllCountries

Yes

All

Yes

All

Examples of ITA (International Transactions) Data Requests
Balance on goods with China for 2011 and 2012
http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&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
http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&method=GetData&DataSetName=ITA&Indicator=PfInvAssets&AreaOrCountry=AllCountries&Frequency=Q
NSA&Year=2013&ResultFormat=xml

49 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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

Indicator

http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&method=GetParameterValues&DataSetName=ITA&ParameterName=Indica
tor&ResultFormat=xml

AreaOrCountry
Frequency
Year

http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&method=GetParameterValues&DataSetName=ITA&ParameterName=AreaO
rCountry&ResultFormat=xml
http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&method=GetParameterValues&DataSetName=ITA&ParameterName=Frequ
ency&ResultFormat=xml
http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&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 http://www.bea.gov/iTable/iTableHtml.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
http://www.bea.gov/international/bp_web/geographic_area_definitions.cfm

Frequency Parameter – (optional, multiple values allowed)

50 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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

Indicator

String

AreaOrCountry

String

Frequency

String

Year

String

TimeSeriesId

String

TimeSeriesDescription

String

TimePeriod

String

CL_UNIT

String

UNIT_MULT

String

DataValue

Numeric

Description
The Indicator parameter value of the data
item.
The AreaOrCountry parameter value of the
data item.
The Frequency parameter value of the data
item.
The Year parameter value of the data item.
A unique identifier for the time series of the
data item.
A description of the transactions measured in
the data item.
A string containing the time period for the
data item in the form YYYY for annual data
and YYYYQn for quarterly data (where n is the
quarter digit)
A string indicating the base unit of
measurement of the 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 multiplier used to interpret
the data value. For example “6” refers to
millions (DataValue × 106).
An integer or decimal value of the statistic.
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.

51 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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
Parameter Name

Type

Description

Required

Multiple
Values
Accepted

TypeOfInvestment

String

Type of investment

Yes

All

Component

String

Yes

All

Frequency

String

Yes

All

Year

String

Yes

All

Component of
changes in position
A - Annual, QNSA Quarterly not
seasonally adjusted
Year requested

“All”
value

Default

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
http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&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
http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&method=GetData&DataSetName=IIP&TypeOfInvestment=FinLiabsFoa&Component=Pos&Frequency=QNSA
&Year=2013&ResultFormat=xml

52 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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

TypeOfInvestment

http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&method=GetParameterValues&DataSetName=IIP&ParameterName=TypeOf
Investment&ResultFormat=xml

Component
Frequency
Year

http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&method=GetParameterValues&DataSetName=IIP&ParameterName=Compo
nent&ResultFormat=xml
http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&method=GetParameterValues&DataSetName=IIP&ParameterName=Freque
ncy&ResultFormat=xml
http://www.bea.gov/api/data/?&UserID=Your-36CharacterKey&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
http://www.bea.gov/iTable/iTableHtml.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 financialaccount 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.
53 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

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

TypeOfInvestment

String

Component

String

Frequency

String

Year

String

TimeSeriesId

String

TimeSeriesDescription

String

TimePeriod

String

CL_UNIT

String

UNIT_MULT

String

DataValue

Numeric

Description
The TypeOfInvestment parameter value of
the data item.
The Component parameter value of the data
item.
The Frequency parameter value of the data
item.
The Year parameter value of the data item.
A unique identifier for the time series of the
data item.
A description of the transactions measured in
the data item.
A string containing the time period for the
data item in the form YYYY for annual data
and YYYYQn for quarterly data (where n is the
quarter digit)
A string indicating the base unit of
measurement of the 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 multiplier used to interpret
the data value. For example “6” refers to
millions (DataValue × 106).
An integer or decimal value of the statistic.
May be blank.

54 | P a g e

T u e s d a y ,

S e p t e m b e r

3 0 ,

2 0 1 4

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.5
Linearized                      : Yes
Author                          : Walt Kampas
Company                         : Microsoft
Create Date                     : 2014:10:16 16:16:16-04:00
Modify Date                     : 2014:10:17 09:56:28-04:00
Source Modified                 : D:20141016201520
Tagged PDF                      : Yes
XMP Toolkit                     : Adobe XMP Core 5.2-c001 63.139439, 2010/09/27-13:37:26
Metadata Date                   : 2014:10:17 09:56:28-04:00
Creator Tool                    : Acrobat PDFMaker 10.1 for Word
Document ID                     : uuid:6fa33fc1-78c9-4f2b-9616-cc93151fa10a
Instance ID                     : uuid:0656ecb7-da60-4895-be76-e760c0f337bc
Subject                         : 2
Format                          : application/pdf
Creator                         : Walt Kampas
Producer                        : Adobe PDF Library 10.0
Page Layout                     : OneColumn
Page Count                      : 54

EXIF Metadata provided by EXIF.tools

Bea Web Service Api User Guide

Navigation menu

Versions of this User Manual:

Views

Navigation