How-To Guide: BLS Public Data API

Multiple Series

If you need to compare information for multiple series IDs, you can send up to 50 series IDs in a single POST request, with or without parameters.

Sending A RESTful Signature

When sending a signature with multiple series IDs, you should set the header to Content-Type=application/x-www-form-urlencoded. In the payload, the seriesID attribute will have the seriesIDs separated by commas. See the code example below:

		var baseURL = 'http://api.bls.gov/publicAPI/v2/timeseries/data/';
		var seriesIDs = ['OEUN000000054192027402104', 'OEUN000000054192027402103'];
		var signature = "seriesid=";
		for (var i = 0; i = seriesIDs.length; i++) {
			signature += seriesIDs[i] + ',';
		}
		signature = signature.substring(0,signature.length-1);
		
		var req = new XMLHttpRequest();
		req.open("POST", baseURL, false);
		req.setRequestHeader('Content-Type', 'application/x-www-form-urlencoded');
		req.send(signature);
		var results = JSON.parse(req.responseText);
		

In this example, we are requesting the annual wage and hourly wage data for photographers nationally, both from the same program. Notice that we specified request as POST and set the content type. In the http request that we opened, we specified the base URL but did not add the signature on in this place; instead, we used req.send(signature) to send it because it's a POST request not a GET request.

Sending a JSON Object

The other option for sending data with multiple series is a JSON object. In this case, you need to set the header to Content-Type= application/json. The JSON object should be formatted with seriesID as an array of IDs and a number of other fields. These include startyear as a string, endyear as a string, catalog as a string, calculations as a boolean, and annualaverage as a boolean. Finally, your registration key will go in the JSON object. calculations and annualaverage are false by default.

• "startyear": the starting year of the requested data.
• "endyear": the ending year of the requested data. If you don't use a registration key, you'll be limited to a 10-year span of time in your query.
• "catalog": catalog data about the series.
• "calculations": these calculations are the changes (percent as well as net changes). These calculations, if available, will be provided for time frames of 1, 3, 6, 12 months. This feature is new in Version 2.0 of the API.
• "annualaverage": if available, you can set this field to true to get annual averages of the requested data. This feature is also new in Version 2.0.
• "registrationkey": if you want to use calculations or annualaverages, you must include your registration key (as queries without a registration key are restricted to version 1.0 of the API). The limit for number of series IDs in a query is 50 with a registration key but only 25 without.

See the following for an example JSON object:

		{"seriesid":["OEUN000000054192027402104", "OEUN000000054192027402103"], 
		"startyear":"2000", 
		"endyear":"2010", 
		"catalog":true, 
		"calculations":false, 
		"annualaverage":false, 
		"registrationKey":"f6be152aed67442d986955e52e5419d0" }
		

See the following for example code to send this request:

		var myRequest = '{"seriesid":["OEUN000000054192027402104", "OEUN000000054192027402103"], ' +
						' "startyear":"2000", ' +
						' "endyear":"2010", ' +
						' "catalog":true, ' +
						' "calculations":false, ' +
						' "annualaverage":false, ' +
						' "registrationKey":"f6be152aed67442d986955e52e5419d0" }';
		var baseURL = 'http://api.bls.gov/publicAPI/v2/timeseries/data/';
		
		var req = new XMLHttpRequest();
		req.open("POST", baseURL, false);
		req.setRequestHeader('Content-Type', 'application/json');
		req.send(myRequest);
		var results = JSON.parse(req.responseText);