BLS Public Data API Signatures (Version 2.0)

The BLS Public Data API utilizes the following three signatures:

All signatures must include an HTTP type, a RESTful URL, and at least one series ID. The series ID(s) can include underscore (_), dash (-) and hash (#) but must not include lower case letters or special characters. All requests specifying years must include a four-digit start year and an end year in numeric format – YYYY (e.g. 2013, not 13).

The following are sample responses for each of API signature with added white spaces for easier readability.

Single Series

Use this signature to retrieve data for a single time series for the past three years. Be sure to include the specific series ID at the end of the URL. Parameters are optional.:

 

HTTP Type: GET
URL (JSON): https://api.bls.gov/publicAPI/v2/timeseries/data/
URL for Excel output: https://api.bls.gov/publicAPI/v2/timeseries/data/.xlsx
Payload: series_id
Example Payload:
LAUCN040010000000005

 

Sample JSON Response:

{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 16,
  "message": [
    
  ],
  "Results": [
    {
      "series": [
        {
          "seriesID": "LAUCN040010000000005",
          "data": [
            {
              "year": "2013",
              "period": "M11",
              "periodName": "November",
              "value": "16393",
              "footnotes": [
                {
                  "code": "P",
                  "text": "Preliminary."
                }
              ]
            },
            {
              "year": "2013",
              "period": "M10",
              "periodName": "October",
              "value": "16536",
              "footnotes": [
                {
                 ...
                 }
              ]
            }
          ]
        }
      ]
    }
  ]
}

 

Multiple Series

Use this signature to retrieve data for more than one timeseries for the past three years. Registered users can include up to 50 series IDs, each separated with a comma, in the body of a request.

 

HTTP Type: POST
URL (JSON): https://api.bls.gov/publicAPI/v2/timeseries/data/
URL (Excel): https://api.bls.gov/publicAPI/v2/timeseries/data.xlsx
Header: Content-Type= application/json
Payload (JSON): {"seriesid":["Series1",..., "SeriesN"], "startyear":"yearX", "endyear":"yearY",
"catalog":true|false, "calculations":true|false, "annualaverage":true|false,
"registrationkey":"000f4e000f204473bb565256e8eee73e" }
Example Payload:
{"seriesid":["LAUCN040010000000005", "LAUCN040010000000006",
"OEUN000000056--5747213213"]}


 

Sample Response:

{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 37,
  "message": [ ],
  "Results": [
    {
      "series": [
        {
          "seriesID": "LAUCN040010000000005",
          "data": [
            {
              "year": "2013",
              "period": "M11",
              "periodName": "November",
              "value": "16393",
              "footnotes": [
                {
                   "code": "P",
                   "text": "Preliminary."
                }
              ],
              . . .
        {
          "seriesID": "LAUCN040010000000006",          
          "data": [            
            {              
              "year": "2013",              
              "period": "M11",              
              "periodName": "November",              
              "value": "20155",              
              "footnotes": [                
                {                  
                  "code": "P",                  
                  "text": "Preliminary."                
                }              
               ],
          . . .
    }


HTTP Type: POST
URL (JSON): https://api.bls.gov/publicAPI/v2/timeseries/data/
URL (Excel): https://api.bls.gov/publicAPI/v2/timeseries/data.xlsx
Header: Content-Type=application/x-www-form-urlencoded
Payload: seriesid=series1,series2 ...
Example Payload without Perameters:
seriesid=OEUN000000056--5747213213,LUU0202891000,
OEUN000000056--5747213213
Example Payload with Perameters:
seriesid=OEUN000000056--5747213213,LUU0202891000,
OEUN000000056--5747213213
&registrationkey=1eccaa39bf3c407db057ec5c43520723
&catalog=true&startyear=2010&endyear=2014
&calculations=true&annualaverage=true


 

Sample of a JSON Response:

{
  "status": "REQUEST_SUCCEEDED",
  "responseTime": 37,
  "message": [ ],
  "Results": [
    {
      "series": [
        {
          "seriesID": "LAUCN040010000000005",
          "data": [
            {
              "year": "2013",
              "period": "M11",
              "periodName": "November",
              "value": "16393",
              "footnotes": [
                {
                   "code": "P",
                   "text": "Preliminary."
                }
              ],
              . . .
        {
          "seriesID": "LAUCN040010000000006",          
          "data": [            
            {              
              "year": "2013",              
              "period": "M11",              
              "periodName": "November",              
              "value": "20155",              
              "footnotes": [                
                {                  
                  "code": "P",                  
                  "text": "Preliminary."                
                }              
               ],
          . . .
    }




 

One or More Series with Optional Parameters

Use this signature to retrieve data for one or more timeseries within a set time frame of up to 20 years. This signature also provides the option of retrieving calculations; annual averages; and catalog data. To retrieve these optional parameters, users must include their assigned registration key. Unless otherwise specified, the catalog, calculations, and annualaverage values will default to false.

Users should also include at least one series ID, the start year, and the end year in the body of the request. If you include multiple series IDs, be sure to separate each with a comma.

 

HTTP Type: POST
URL: https://api.bls.gov/publicAPI/v2/timeseries/data/
URL with parameters (JSON): https://api.bls.gov/publicAPI/v2/timeseries/data/
?registrationkey=000f4e000f204473bb565256e8eee73e&
catalog=true&startyear=2010&endyear=2014&calculations=true &annualaverage=true
URL for Excel output with parameters: https://api.bls.gov/publicAPI/v2/timeseries/data/
.xlsx?registrationkey=000f4e000f204473bb565256e8eee73e&
catalog=true&startyear=2010&endyear=2014&calculations=true&annualaverage=true
Payload: JSON Payload:
{"seriesid":["Series1",..., "SeriesN"],
"startyear":"yearX", 
 "endyear":"yearY",
"catalog":true|false,
"calculations":true|false,
"annualaverage":true|false,
"registrationkey":"995f4e779f204473aa565256e8afe73e"
}
Example Payload:
: {"seriesid":["LAUCN040010000000005", "LAUCN040010000000006"],  "startyear":"2010",
   "endyear":"2012",  "catalog":false,
"calculations":true,  "annualaverage":true,
  "registrationkey":"000f4e000f204473bb565256e8eee73e "  }
Example Payload with Parameters:
{"seriesid":["LAUCN040010000000005", "LAUCN040010000000006"],
"startyear":"2010",   "endyear":"2012",  "catalog":false,
"calculations":true,  "annualaverage":true,
"registrationkey":"995f4e779f204473aa565256e8afe73e"  }


Sample Response:

{
 "status": "REQUEST_SUCCEEDED",
  "responseTime": 706,
  "message": [ ],
  "Results": [
    {
      "series": [
        {
          "seriesID": "LAUCN040010000000005",
          "data": [
            {
              "year": "2012",
              "period": "M13",
              "periodName": "Annual",
              "value": "17656",
              "footnotes": [
                {
                  
                }
              ],
             "calculations": {
              "net_changes": {
                "1": "0.6",
                "3": "-0.2",
                "6": "-2.0",
                "12": "-1.2"
              },
              "pct_changes": {
                "1": "13.3",
                "3": "-3.8",
                "6": "-28.2",
                "12": "-19.0"
              }
            }
          },
               . . .
}


To help you get started, sample code for some of the most popular programming languages has been written:

API Version 2.0         API Version 1.0
 

 

Last Modified Date: November 3, 2016