VA Report Example: Geographic data, SAS Viya Jobs, Data Driven Content, and REST APIs!

1 Like

SAS Visual Analytics offers great functionalities to work with geographic data. You can use the built-in functionalities to search for a specific address and visualize an area within a defined distance. In some cases, you may want to display the data on a map but you might also want to filter a bar chart or list table using more advanced filtering techniques based on geographical data. In this article, I will demonstrate how you can create a simple report that will use an address entered by the end-user to retrieve a list of schools within a distance range.

In this article, I will use a specific SAS Visual Analytics object: Data-Driven Content. This object offers the opportunity for the report designer to integrate a third-party web page in the report. When compared to the Web Content object, the Data-Driven Content object will receive data from the report which is nice but it also gives the opportunity to send data back to the Visual Analytic report which gives the opportunity to the third-party web pages to interact with the objects defined in the report as if they were native SAS Visual Analytics objects.

I've already covered Data-Driven Content objects for some other tasks in the past. If you want to get a better idea about what can be done, please don't hesitate to read:

On to our example, enter an address and retrieve a list of schools within a selected distance range.

Build the web page

You may ask yourself how this can be done. The answer is quite simple: JavaScript and HTML.

If you are not familiar with web development, you might think it will be complex to handle all the interactions and to write the code needed to get the expected result. You are right. This can be complex but SAS provides some JavaScript utilities that you can use to ease the development of the web page that will be displayed in the Data-Driven Content object. The functions that we will use are available on GitHub.

You will also find the code for this article on GitHub. I will not explain this code line by line but rather explain the logic.

The web page has:

An input box to enter the address that the user is looking for
A button to submit a request to ArcGIS in order to collect suggested addresses
A slider to select the distance range
An area to hold the suggestions returned by ArcGIS

Select any image to see a larger version.
Mobile users: To view the images, select the "Full" version at the bottom of the page.

What the web page does:

When the page loads, the report data are passed to the Data-Driven Content object.
When clicking on the button, it calls the ArcGIS web server passing the address typed by the end-user.
When the suggestions are received from ArcGIS, they are displayed in the area below the search box.
When the user clicks on an address in the suggestions area, a check mark indicates which address is selected and a query is sent to the ArcGIS server to retrieve the coordinates for the selected address.
When the coordinates are received from ArcGIS, they are used in combination with the distance information to call a SAS Viya job.
The SAS Viya job uses the same CAS table as the report to calculate the distance between the requested address and the school addresses. The calculation is based on the geodist function that comes with SAS. Using the distance parameter, the data is filtered and a JSON response is sent using proc json.
When the web page receives the selection from the SAS Viya job, it uses the returned data to identify which rows from the report data should be selected.
The selected rows are passed back to the report and the list table is filtered based on the selection.

If you want to make the link with the code, the functions that are used for each step are:

va.messagingUtil.setOnDataReceivedCallback
$(“#btnSearch”).click
displaySuggestions
getCoordinates
geoFilter.sas
getCASData
filterVAData
va.messagingUtil.postSelectionMessage

Retrieve data from ArcGISAt different stages of the application process, there will be calls to ArcGIS REST APIs. These endpoints are:

arcgis/rest/services/World/GeocodeServer/suggest
arcgis/rest/services/World/GeocodeServer/findAddressCandidates

The first one retrieves a list of suggestions and requires the following parameters:

    let params = {
        "text": $("#inputAddress").val(),
        "countryCode": "USA",
        "region": "Texas",
        "category": "Address",
        "isCollection": false,
        "f": "pjson"
    };

The text represents the address that was entered by the user. The countryCode and region are used to reduce the scope of the search and improve performance. The category indicates the type of information the query is looking after. If you want more information about this REST API, ArcGIS REST API

The findAddressCandidates endpoint retrieves the coordinates of a specific address. It requires the information provided by the suggest endpoint for a specific location.

Please note that ArcGIS offers a limited amount of requests to their REST APIs. This means that for a demo, it should not be an issue. As soon as your report goes production and it gains in popularity, you might need to get an Enterprise Subscription with ArcGIS to allow for more requests. A subscription with ArcGIS will also bring extra functionalities to your SAS Visual Analytics reports.

Create the SAS Viya job

As you have seen in step 6, a SAS Viya job is in charge of calculating the distance between each school address and the provided coordinates.Here is the SAS code:

    libname VISUAL cas caslib="VISUAL";
    data selection;
        set VISUAL.postsecondary_school_locations;
        distance=geodist(%sysevalf(&lat),%sysevalf(&lon), lat, lon, 'M');
        if distance < %sysevalf(&dist) then output;
    run;
    proc json out=_webout nosastags pretty;
        export selection;
    run;

The code uses different macro variables. These are URL parameters that are converted by the SAS Job Execution to macro variables. The parameters have to be defined when creating the job. This means that for our job, we have defined parameters for:

latitude: lat
longitude: lon
distance: dist
action: _action
output type: _output_type

...

These parameters are passed by the web application when calling the SAS Viya job:

    let params = {
        "lon": coordinates.x,
        "lat": coordinates.y,
        "dist": distance,
        "_action": "execute",
        "_output_type": "json"
    }

Deploy the web applicationFor this example, I've been using a SAS Viya 3.5. The logic for the application and the job are the same on Viya 2020.1 or later. Depending on the Viya version you are working with, you have different options to deploy the web application:

a specific container for SAS Viya 2020.1 or later
the web server deployed with the SAS Viya 3.5 environment
a web server outside of the Viya environment
...

There are many options available and I will not cover all of them in this article. Depending on your choice, you might have to adapt the configuration of CSRF and CORS within SAS Environment Manager. To make it easy as I'm using SAS Viya 3.5, I've copied the files directly under /var/www/html in a folder named geoFilter. As a result, I can use the following URL to access the web application:http://sasviya01.race.sas.com/geoFilter This is the URL that will be defined in the Data-Driven Content object options when building the report.Build the report. So far, we have seen the tasks assigned to the web page and to the SAS Viya job. It is now time to use the web page in a Visual Analytics report. For this article, I've used the following data from the US Federal Government. The data have been loaded into a CAS table directly from SAS Visual Analytics when building the report. The report is simplistic: one Data-Driven Content object at the top and one List Table object at the bottom. Only one column of the input table has been assigned to the Data-Driven Content object: Name. The List Table object can have as many variables as you wish.

The Data-Driven Content has one action defined which is to filter the List Table.

Here is the final result:

Conclusion

The Data-Driven Content object offers a lot of flexibility when the end-user needs to interact with third-party information providers. In this example, you have seen that it was possible to collect information from another web site (ArcGIS in this example), pass the data to a SAS Viya Job and use the outcome of the job to filter data in a Visual Analytics report. As you can imagine, this is only an example of what you can do to manipulate geographic data using SAS functions and without displaying the data on a map.With the Data-Driven Content object, you can achieve many tasks that would not be otherwise possible in SAS Visual Analytics. The Data-Driven Content object opens up a window to the outside world which can give you unlimited possibilities!

Articles using geographic data:

Enrich SAS VA Geo Maps with pinned locations loaded from a CSV file

Enrich VA Geo Maps using a custom ESRI map with pinned locations

Geocaching your data or the simplest way to hide/show data based on user location