Use of ESSENCE APIs to Support Flexible Analysis and Reporting

Abstract

ObjectiveTo describe and provide examples of the Electronic Surveillance System for the Early Notification of Community-based Epidemics (ESSENCE) application programming interface (API) as a part of disease surveillance workflows.IntroductionThe ESSENCE application supports users’ interactive analysis of data by clicking through menus in a user interface (UI), and provides multiple types of user defined data visualization options, including various charts and graphs, tables of statistical alerts, table builder functionality, spatial mapping, and report generation. However, no UI supports all potential analysis and visualization requirements. Rapidly accessing data processed through ESSENCE using existing access control mechanisms, but de-coupled from the UI, supports innovative analyses, visualizations and reporting of these data using other tools.MethodsThe ESSENCE API gives users the ability to query ESSENCE data and functionality via a Representational State Transfer (REST) web API designed to use HTTPs protocol. As with logging into the ESSENCE application normally, use of the API also requires users to authenticate with their username and password by including it in the code. This makes programmatic interfaces with the application possible whereby a tool or program makes a request to the API endpoint and the API returns the result of the query in a structured form. The ESSENCE API is a collection of endpoints that return different sets of data, including ESSENCE time series graphs, time series data, data details data, aggregated data created using the table builder functionality, number of unique facilities or regions (i.e. counties) reporting for a query, and results from the detector algorithms and alert list. All of the query parameter information is stored in the API URL, which the user can create programmatically or by first creating their query from within ESSENCE, and then clicking the “API URL” to generate the necessary URL. API results are generally available in both json and csv formats.ResultsEpidemiologists in the CDC NSSP have developed R code that uses these APIs to create customized Rmarkdown reports and visualizations not possible within the ESSENCE application, as well as to automate extraction of data from ESSENCE to support routine reporting for other CDC program areas (e.g., influenza-like illness, and suspected opioid encounters). Anecdotally, some Sites utilize the API to populate publically facing dashboards with aggregated data from ESSENCE. Programmatic access to processed ESSENCE data via the APIs also supports easily sharable exploratory analysis and visualization that can serve as a sandbox for testing new methods for future inclusion within ESSENCE.ConclusionsThe development and use of the ESSENCE APIs in public health surveillance will support more efficient and timely access to machine-readable data de-coupled from point and click user interfaces, and has the potential to spur new and innovative ways of using data that has traditionally been less programmatically accessible to users. New tools and programs can leverage the data in web or mobile applications, traditional reports, and more easily integrate disparate data sources for comprehensive surveillance.