REopt Lite Tutorial: API Overview (Text Version)

This is a text version of the video REopt Lite Tutorial: API Overview.

The REopt Lite^® Application Programming Interface, or API, allows you to interact with REopt Lite in a programmatic way—for dynamic analysis that can be embedded into your own applications.

Documentation for the API is available on NREL’s developer network at developer.nrel.gov. There are also links to the API on the home page of the REopt Lite web tool and at the bottom of every REopt Lite page.

Before we get started, you will need to acquire an API key for NREL’s developer network. Navigate to the home page of the developer network site and click “Get an API Key.” Fill out some general information, and an API key will be sent to the email you provide.

Once you have your API key, you can start making GET and POST requests to the API. We recommend reviewing the documentation in detail. For now, we will go through posting an example job to the API.

The code used in this example can be found at github.com/NREL/REopt-API-Analysis. All the code can be downloaded and used to access the API.

The fastest way to get started using the API is through the “Binder” link. To get there, click “README.md.” Then click the “Launch Binder” badge at the top of the file.

Once the binder is loaded, you will be dropped into an interactive Jupyter Notebook. Click the “run” button at the top of the page to move the session along.

The first block of code initializes some of the packages we need and loads some custom functions used in this notebook.

The second block of code defines the JSON post that represents the analysis scenario. As with the web tool, only three fields are required to run an analysis. These include location, defined by a latitude and longitude; load profile, defined by a Department of Energy reference building type and scaled by annual usage; and utility rate, based on a Utility Rate Database, or URDB, label.

The third block of code takes the JSON scenario description as an argument to the “reo_optimize()” function. The “reo_optimize()” function performs the steps shown in the “Example Workflow” section of the REopt Lite API Documentation. This is available on the developer network site under “Web Service Documentation” for Energy Optimization. Workflow steps include creating a job, receiving the job ID, polling for results until the job is complete, and receiving and storing results.

The results are saved in the “retail_store_results” variable. All the information from the scenario optimization can be accessed using this variable.

As an example, we are going to explore how the sizing and dispatch of an optimized system changes based on building type. To perform this analysis, we can take our original scenario post and loop through several different building types, saving our results as we go.

We will post a new job to the API for each scenario we are optimizing, going through the workflow steps described earlier. Once we have our results, we can use that information to compare scenarios.

In this analysis, we plot the size and dispatch of the optimized integrated energy system. We can see that the warehouse has the largest solar PV and energy storage system. This comes from the large peaks in the load profile and the structure of the rate tariff we used.

For more information, consult the REopt Lite API Documentation for detailed usage information. Access the REopt^® API Analysis github repository for example scripts. For questions and answers, visit the REopt Lite forum or email REopt@nrel.gov.