辅导 program、讲解 Python/C++语言编程

Page 1 of 15 November 12, 2024
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 . 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.
The URI 0F
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:
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
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, apps.bea.gov, to host all
dynamic, database-driven web applications referenced from the primary domain, www.bea.gov.
While API registration and documentation links remain on the primary domain, the URI for the API is
accessed on the apps.bea.gov subdomain, as shown below.
NOTES:
Page 2 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:
http://apps.bea.gov/api/data/?UserID=Your-36Character 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 XML3
. 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://apps.bea.gov/api/data?UserID=Your-36Character Key&method=GETDATASETLIST&ResultFormat=XML
This request would return a list of the available datasets in JSON format:
http://apps.bea.gov/api/data?&UserID=Your-36Character 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:

2 Java Script Object Notation 3 Extensible Markup Language
Page 3 of 15 November 12, 2024
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
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 4 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:

API Calling Limits (rate limiting)
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.
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.
Example Error Response in XML Format:

...

Page 5 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.
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 (https://www.bea.gov/news/schedule). 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 Li st – retrieves a list of the datasets currently
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
… … …
Example Header Response:
Page 6 of 15 November 12, 2024
offered. Required Parameters: UserID, Method
Optional Parameters: ResultFormat
Result: Dataset node with DatasetName and DatasetDescription
attributes. Example Request:
http://apps.bea.gov/api/data?&UserID=Your-
36Character Key&method=GETDATASETLIST&ResultFormat=XML
&ResultFormat=XML&
Example Return:

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
(https://apps.bea.gov/developers), we also encourage users to periodically call the above
GETDATASETLIST discover new datasets.
G et P a ra m et er Li 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 7 of 15 November 12, 2024
them individually.
Example Request 1:
https://apps.bea.gov/api/data?&UserID=Your-36Character Key&method=getparameterlist&datasetname=Regional&ResultFormat=XML
Example Return 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)" />
ParameterDescription="Income or employment table to retrieve" />
ParameterDescription="Line code for a statistic or industry"/>
ParameterDataType="string" />

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:
https://apps.bea.gov/api/data?&UserID=Your-36Character-Key&method=getparameterlist&datasetname=
IntlServTrade&ResultFormat=XML
Example Return 2:

Page 8 of 15 November 12, 2024

ParameterIsRequiredFlag="0" ParameterDescription="The type of service requested" ParameterDataType="string"/>
ParameterIsRequiredFlag="0" ParameterDescription="The type of trade direction requested"
ParameterDataType="string"/>
ParameterIsRequiredFlag="0" ParameterDescription="The affiliation requested" ParameterDataType="string"/> ParameterIsRequiredFlag="0" ParameterDescription="The area or country requested" ParameterDataType="string"/> ParameterIsRequiredFlag="0" ParameterDescription="The year requested" ParameterDataType="string"/>

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 alu 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:
https://apps.bea.gov/api/data?&UserID=Your-36Character Key&method=GetParameterValues&datasetname=INTLSERVTRADE&ParameterName=Tra
deDirection&ResultFormat=XML
Example Return 1:

Example Request 2:
https://apps.bea.gov/api/data?&UserID=Your-36Character Key&method=GetParameterValues&datasetname=Regional&ParameterName=TableName&ResultFormat=
XML
Page 9 of 15 November 12, 2024
Example Return 2:

Page 10 of 15 November 12, 2024

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.
GetParameterValuesFiltered – 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:
http://apps.bea.gov/api/data?&UserID=Your-36Character Key&method=GetParameterValuesFiltered&datasetname=Regional&TargetParameter=LineCode&TableN
ame=SAINC1&ResultFormat=XML
Example return:

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:
http://apps.bea.gov/api/data/?UserID=Your-36Character Key&method=GetParameterValuesFiltered&datasetname=Regional&TargetParameter=Year&TableName
=CAINC5N&GeoFips=01001&ResultFormat=XML
Example return:
Page 11 of 15 November 12, 2024