Data API

The BLS Public Data Application Programming Interface (API) is an application designed to allow third party programmers, developers, and organizations to retrieve published historical time series data in JSON data-interchange format or as an Excel spreadsheet. Using Public Data API signatures, users can consume and manipulate raw data from all of the Bureau’s surveys to create a wide range of applications that conform to W3C standards and accepted practices. The BLS Public Data API does not require registration and is open for public use. Sample code is provided for developers and programmers for the most popular languages currently available. Feedback is encouraged and will aid in further enhancement and development of the Bureau’s Public Data API.

For more information about the BLS Public Data API, please visit the BLS Public Data API Developer's site.

Version 2.4 (10/05/2020)

Release Notes:

• New query parameter “aspects” that retrieves the aspect associated with a data point for a given BLS series ID.
• Aspects can be retrieved through GET & POST request including excel requests.

Version 2.3 (2/28/2018)

Release Notes:

• New query parameter "latest" that retrieves the most recent data point for a given BLS series ID.
• If the results of an API request include the most recent data point for a given BLS series ID, then the data point will be flagged as "latest" in the JSON response.
• Metadata for a BLS series ID now includes the survey abbreviation.
• Adds a /surveys URL endpoint that returns a list of all BLS surveys with associated metadata or the metadata for a single survey.
• Adds a /popular URL endpoint that returns series IDs for the 25 most popular BLS and survey-specific series.

Version 2.2 (11/3/2016)

Release Notes:

• API 2.2 organizes JSON results in descending order, with the most recent data first.
• The Excel output for the API will include the annualaverage, if the annualaverage parameter has been set to "true."
• Users should now format all API request parameters in lowercase format so that they are consistent.

Version 2.1 (02/09/2016)

Release Notes:

• API 2.1 supports x-www-form-urlencoded content type format for the request body.
• API 2.1 supports excel spreadsheet (XLSX) as a response format.
• Implemented fix to address daily query limit for registered users not being reset in some instances.

Version 2.0 (10/16/2014)

Release Notes:

• User registration is now required for use of the Public Data API and its new features. Users must provide an email and organization name during registration.
• API 2.0 returns up to 20 years of data for up to 50 time series, with a daily limit of 500 queries.
• Net and percent calculations are available for one month, two months, six months, twelve months.
• Annual averages are available.
• Series description information (catalog) is available for a limited number of series. (Only surveys included in the BLS Data Finder tool are available for catalog information.)

Known Limitations:

• Users must have knowledge of BLS Series IDs to successfully complete a request.
• The API will only return observational values and footnotes. It does not return metadata.
• There is a maximum of 50 time series in a single request.
• Users may request a maximum of 500 queries daily.
• Users may request a maximum of 20 years of data.

Version 1.0 (8/19/2013)

Release Notes:

• The API returns up to 10 years of data for up to 25 time series.
• Data is available for all BLS surveys.

Known Limitations:

• Users must have knowledge of BLS Series IDs to successfully complete a request.
• There is a maximum of 25 time series in a single request.
• The API will only return observational values and footnotes. It does not return metadata.
• The API will not return calculations performed by the BLS.
• Users may request a maximum of 10 years of data.

Addendum (9/30/2013):

• There is a one day lag between published data and its availability for retrieval from the API. For additional information on release dates and times see the Release Calendar.

 

For more information about the BLS Public Data API, please visit the BLS Public Data API Developer's site.

 

Last Modified Date: October 5, 2020