Use of ESSENCE APIs to Support Flexible Analysis and Reporting

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