SASEBLS Interface Engine

You can query the Bureau of Labor Statistics (BLS) databases to retrieve the observations or data values for a list of economic time series by specifying the series ID of each time series that you want to read into SAS and by specifying your unique BLS API key. To obtain your own unique API key, visit the BLS website at the following URL:

https://data.bls.gov/registrationEngine/

The BLS API key is a 32-character alphanumeric lowercase string, such as ‘abcdefghijklmnopqrstuvwxyz123456’, and is represented by ’XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX’ in the USER= option in the following example. In addition, the example URLs in this section and in the section Details: SASEBLS Interface Engine use the same BLS API key as the argument your_bls_apikey.

Now that you are informed about the terms of service of the BLS data, you can use your BLS API registration key to access the BLS data, as shown in the following example.

The following statements enable you to access the three different time series from the Consumer Price Index (CPI) database: 'CUUR0000SA0' from the CPI-U (Urban consumers, US city average, all items), 'CWUR0000SA0' from the CPI-W (Urban wage earners, US city average, all items), and 'SUUR0000SA0' from the C-CPI-U (Chained CPI, all urban consumers). These three time series are listed in the following SAS DATA step and shown in Figure 1:

options validvarname=any;

DATA inseries;
   length seriesid $ 17;             /* Allow up to 17 bytes for series names */
   seriesid = 'CUUR0000SA0'; output; /* CPI-U, Urban consumers, US city avg */
   seriesid = 'CWUR0000SA0'; output; /* CPI-W, Wage earners, US city avg */
   seriesid = 'SUUR0000SA0'; output; /* C-CPI-U, Chained CPI, all urban consumers*/
RUN;

title 'Retrieve Data for Three Consumer Price Index Time Series';
libname _all_ clear;

libname bls sasebls "%sysget(BLS)"
   USER='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
   SETNAME=CPI
   INSET=inseries
   PAYPATH="%sysget(BLS)payload"
   STARTYEAR='2020'
   ENDYEAR='2021'
   FREQ=month
   OUTJSON=cpigs
   FORMAT=json;

data cpi_gsa;
   set bls.cpigs ;
run;

proc contents data=cpi_gsa; run;
proc print data=cpi_gsa; run;

The JSON data that the BLS website returns are placed in a file named by the OUTJSON= option—in this case, CPIGS.json. Note that the JSON file extension is excluded from the file name that is specified in the OUTJSON= option. When the SET statement is executed, the JSON data are read into a SAS data set named cpigs.sas7bdat, which resides in the location that is specified inside the string enclosed in double quotation marks in the SASEBLS LIBNAME statement. So, in the preceding example, if the BLS environment variable is set to /sasusr/bls/test/, then the SAS data set that is created from reading the downloaded JSON file is placed into the following file:

/sasusr/bls/test/cpigs.sas7bdat

An equivalent LIBNAME statement that does not use any environment variables could be as follows:

libname bls sasebls "/sasusr/bls/test/"
   USER='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
   SETNAME=CPI
   INSET=inseries
   PAYPATH="/sasusr/bls/test/payload"
   STARTYEAR='2020'
   ENDYEAR='2021'
   FREQ=month
   OUTJSON=cpigs
   FORMAT=json;

You could also use either a SAS macro variable or a system environment variable to store the value of your BLS API registration key so that the key does not appear explicitly in your SAS code. The SETNAME= option names the BLS data set that you are retrieving data from. The INSET= option specifies SAS input data set that contains the list of time series that you want to retrieve. This option accepts a string that names the SAS data set containing a list of one or more time series that you select (keep) in the resulting SAS data set. The SASEBLS interface engine creates a file named by the PAYPATH= option—in this case, '/sasusr/bls/test/payload.txt'. When you specify the pay path, do not add the .txt file extension; the SASEBLS engine automatically adds it. The result, CPI_GSA, is named in the DATA step and is shown in Figure 1. It is more efficient to use the DATA step to store your BLS data in a SAS data set and then refer to the SAS data set directly in your PROC PRINT or PROC SGPLOT statement, but you can also refer to the SASEBLS libref directly, as in the following statements:

proc print data=bls.cpigs; run;

This statement uses the member name, CPIGS, in the PROC PRINT statement; this usage corresponds to specifying the OUTJSON=CPIGS option. Although using this code might seem easier, it is not as efficient, because every time you use the SASEBLS libref, the BLS interface reads the entire JSON file again into SAS. It is better to refer to the SAS data set repeatedly than to invoke the interface engine repeatedly. For another example that uses more SASEBLS LIBNAME statement options, see the section Details: SASEBLS Interface Engine.