SASERAIN Interface Engine

You can query the World Weather Online database to retrieve the observations or data values for a list of time series by specifying the World Weather Online code for the location (q-code). The World Weather Online q-code consists of a location code such as one for City and Country, latitude and longitude, IP address, US zip code, UK/Canadian postal code, or airport code (IATA). To specify more than one location, list each q-code in the QUERY= option, and separate the locations with a semicolon. Neither a comma nor a blank can be used as a separator between the q-codes, because one q-code can contain any number of commas or blanks.

You must also specify your unique World Weather Online premium API key (authentication token). To obtain your own unique API key, visit the World Weather Online website at the following URL:

https://developer.worldweatheronline.com/login.aspx

For more information about the web service (including pricing and premium service information), visit the website at the following URL:

https://developer.worldweatheronline.com/api/faq.aspx

The World Weather Online API key is a 31-character mixed-case alphanumeric string, such as "abCDefghijklmnopqrstuv123456789," and is represented by ’XXXXXXXXXXXXXXXXXXXXXXXXXXXXX’ in the APIKEY= option in the following example. In addition, the example URLs in this section and in the section Examples: SASERAIN Interface Engine use the same World Weather Online API key as the argument your_rain_apikey.

After you have your assigned World Weather Online API key and have agreed to the World Weather Online terms of use, you can use your API key to access the World Weather Online data, as shown in the following example.

The statements that follow enable you to access the weather for London, Paris, and Dubai. For brevity of output, the request is for only one day (NUM_OF_DAYS=1), which starts with today. The FX24=YES option returns observations at a frequency of every 3 hours with an additional observation for the 24-hour average (the value of the TIME variable is 24), and the observations are sorted in chronological order. For brevity, only the current conditions output is shown in Figure 1.

options validvarname=any;

title 'Retrieve Weather Data for London, Paris, and Dubai';
libname mylib "/sasusr/rain/doc";
libname rain saserain "/sasusr/rain/test"
   QUERY='London,United Kingdom;Paris,France;Dubai,United Arab Emirates'
   FX24=yes
   CONDITIONS=yes
   OUTXML=tricky
   AUTOMAP=replace
   MAPREF=MyMap
   XMLMAP="/sasusr/rain/test/tricky.map";
   APIKEY='XXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
   NUM_OF_DAYS=1
   FORMAT=xml;

data mylib.my24a;
   set rain.tricky;
run;
proc contents data=mylib.my24a; run;
proc print data=mylib.my24a; run;

libname condo "/sasusr/rain/test";
data mylib.mycca;
   set condo.cc_tricky;
run;

proc contents data=mylib.mycca; run;
proc print data=mylib.mycca; run;

The XML data that the World Weather Online website returns are placed in a file that is named by the OUTXML= option—in this case, TRICKY1.xml. Note: The SASERAIN engine appends a numeral to the XML file name, and the file extension (.xml) is excluded from the file name that appears in the OUTXML= option. When the SET statement is executed, the XML data are read into a SAS data set named TRICKY.sas7bdat, which resides in the location given inside the string enclosed in double quotation marks in the SASERAIN LIBNAME statement.

You could use either a SAS macro variable or a system environment variable to store the value of your World Weather Online API key so that the key does not appear explicitly in your SAS code. The XML map that is created is assigned the full path name that the XMLMAP= option specifies. The SASERAIN engine appends a numeral to the XML file name to indicate the position of the World Weather Online location code in the QUERY= option.

The QUERY= option specifies the list of World Weather Online locations that you want to retrieve weather data for. This option accepts a string, enclosed in single quotation marks, that denotes a list of one or more World Weather Online locations that you select (keep) in the resulting SAS data set. The result, TRICKY, is named in the DATA step and is shown in Figure 1. The preceding example uses three World Weather Online location codes. London, which is in the first position of the QUERY= option, has the numeral 1 appended to the name of the XML file, resulting in TRICKY1.xml. Paris is in the second position of the QUERY= option, so the numeral 2 is appended to the name of the XML file, resulting in TRICKY2.xml. Dubai is in the third position of the QUERY= option, so the numeral 3 is appended to the name of the XML file, resulting in TRICKY3.xml. The SASERAIN engine merges the three XML files to produce one merged output data set named TRICKY.sas7bdat. The current conditions data set is named CC_TRICKY. The second DATA step uses the SET statement to read the current conditions data into a new data set named MYCCA. These data are shown in Figure 1.

It is more efficient to use the DATA step to store your World Weather Online data in a SAS data set and then refer to the SAS data set directly in your PROC PRINT or PROC SGPLOT statement. You can also refer to the SASERAIN libref directly, as in the statement

proc print data=rain.tricky;

This statement uses the member name, TRICKY, in the PROC PRINT statement which invokes the RAIN libref to run the SASERAIN engine. This usage of the member name, TRICKY, corresponds to specifying the OUTXML=TRICKY option. Although using this statement might seem easier, it is not as efficient, because every time you use the SASERAIN libref, the SASERAIN interface engine reads the entire XML file into SAS again. So it is better to refer to the SAS data set repeatedly than to invoke the interface engine repeatedly. For another example that uses more SASERAIN LIBNAME statement options, see the section Examples: SASERAIN Interface Engine.