Frequently Asked Questions (FAQs)

What is an API?
An API (Application Programming Interface) is a tool that allows third party developers and organizations to access and manipulate data. The BLS Public Data API allows such users to access and manipulate published BLS survey data.

What is JSON?
JSON (JavaScript Object Notation) is a user-friendly, text-based data-interchange format of communication, used primarily to transmit data between applications and servers over network connections. It is an independent language, and there are parsers available for many languages, including Java, Ruby/Ruby on Rails, and Unix Command Line, for which we have provided sample code.

What is REST?
REST (Representational state transfer) is a type of software architecture, in which clients send requests to servers, and servers return responses after processing requests. It is the most commonly used architecture for APIs. The BLS Public Data API uses REST architecture.

Which API Signature do I use?
If you would like to return data for a single timeseries, you should use the Single Series signature. If you would like to return data for multiple timeseries, you should use the Multiple Series signature. The Single Series and Multiple Series signatures will return a three-year period of data by default.
If you would like to return data for a set period of time, you should use the One or More Series, Specifying Years signature.

I don't know the series ID(s) for the data I want to access. How do I find the ID(s)?
The BLS Public Data API requires users to know the series ID to request data. We do not currently have a catalogue of series IDs, but all BLS series IDs follow a similar format.

Why doesn't my JSON response include metadata?
At this time, the BLS Public Data API only returns raw data from BLS surveys; it does not include metadata.

If you have not formatted your series ID or your request correctly, you may receive an error message. For example:

{"status":"REQUEST_SUCCEEDED","responseTime":104,"message":["Invalid Series for Series 
laucn21219003!"], "Results":[{"series": [{"seriesID":"laucn21219003!","data":[]}]

We have provided solutions for some of the most common error messages.

I received a "Series does not exist" error. What does this mean?
Please check to make sure that you typed your series ID in the correct format. Your series ID must include all capital letters and must not have any special characters.

I received a "Database is locked for Series" error. What does this mean?
The data you requested is currently not available.

I received a "No Data Available for Series" error. What does this mean?
You have requested data for a year that is not in our database. Please adjust your request.

How do I format the year for my request?
If you would like to specify a time frame in your request, you must include a startyear and an endyear within the request. Each four-digit year should be formatted in numeric characters –YYYY (e.g. "2013", not "aaaa" or "13"). Your request must not exceed a 10 year period.

I received a "415 Unsupported Media Type" error. What does this mean?
If you are sending a JSON request, you must set your HTTP Content-Type to "application/json". You can do this using our sample code.

I received an HTTP status/response code with my request. What does the code mean?
  • 200: Your request was successful.
  • 202: Your request is processing.
  • 400: Your request did not follow the correct syntax.
  • 401: You're not authorized to make this request.
  • 404: Your request was not found and/or does not exist.
  • 429: You have made too many requests.
  • 500: The server has encountered an unexpected condition, and the request cannot be completed.
Do I have to register to use the BLS Public Data API?
The BLS Public Data API is available to the public. You do not have to register to use it.

I didn't have sample code for my language.
We have provided examples of sample code for the most common languages, including Java, Unix Command Line, and Ruby/Ruby on Rails. If you would like to see an example of sample code in a different language than those provided, please leave a comment.


Didn't see your question? If you would like to give us feedback, please leave a comment. We look forward to hearing from you.


Last Modified Date: December 6, 2013