SASEUSCB Interface Engine

You can query the US Census Bureau (USCB) 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 USCB API key. To obtain your own unique API key, start by visiting the USCB website:

https://www.census.gov/data/developers.html

Then click on the Request a Key box at the lower left of that page. Alternatively, you can go directly to the following site:

https://api.census.gov/data/key_signup.html

The USCB API key is a 40-character alphanumeric lowercase string, such as ‘abcdefghijklmnopqrstuvwxyz12345612345678’, 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: SASEUSCB Interface Engine use the same USCB API key as the argument your_uscb_apikey.

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

The following statements enable you to access monthly time series from the EITS (Economic Indicator Time Series) ADVM3 (Advanced Report on Durable Goods) database. The time series for defense aircraft and parts (CATEGORY=DAP) that are selected from the time period starting September 2012 (STARTDATE=’2012-09’) and ending April 2013 (ENDDATE=’2013-04’) are retrieved by using the following SAS DATA step and shown in Figure 1:

options validvarname=any;

title 'Retrieve Monthly Data from EITS ADVM3 (Advanced Report on Durable Goods)';
libname _all_ clear;

libname uscb saseuscb "%sysget(USCB)"
   user='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
   setname=eits_advm3
   for='us:*'
   category=DAP
   startdate='2012-09'
   enddate='2013-04'
   outjson=ADVM3
   format=json;

data my_gsa;
   set uscb.ADVM3 ;
run;

proc contents data=my_gsa; run;
proc print data=my_gsa; run;

The JSON data that the USCB website returns are placed in a file that is named by the OUTJSON= option—in this case, ADVM3.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 ADVM3.sas7bdat, which resides in the location that is specified inside the string enclosed in double quotation marks in the SASEUSCB LIBNAME statement. So, in the preceding example, if the USCB environment variable is set to /sasusr/uscb/test/, then the SAS data set that is created by reading the downloaded JSON file is placed in the following file: /sasusr/uscb/test/ADVM3.sas7bdat.

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

libname uscb saseuscb "/sasusr/uscb/test/"
   user='XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
   setname=eits_advm3
   for='us:*'
   category=DAP
   startdate='2012-09'
   enddate='2013-04'
   outjson=ADVM3
   format=json;

You could also use either a SAS macro variable or a system environment variable to store the value of your USCB API registration key so that the key does not appear explicitly in your SAS code. The SETNAME= option names the USCB data set that you are retrieving data from.

The result, MY_GSA, is named in the DATA step and shown in Figure 1. It is more efficient to use the DATA step to store your USCB 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 SASEUSCB libref directly, as in the following statement:

proc print data=uscb.ADVM3; run;

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

The variable name for each ADVM3 time series is made up of three parts, separated by underscores ('_'): the category code, the data type code, and an 'S' for seasonal data or a 'U' for nonseasonal data. See Table 7 and Table 8 for the complete list of categories and data type codes, respectively, in the ADVM3 data set.