Repository navigation
2. Run analyses using the API
The REopt API includes many endpoints (TODO: update). However, the main use case is running an optimization job and getting the results of the job, which is a two-step process.
First, you POST your REopt Scenario to the job endpoint, i.e. https://developer.nrel.gov/api/reopt/stable/job. POST'ing can be done with many tools. This repository includes python functions to make it easy to POST your jobs to the API.
The job endpoint will return a run_uuid in JSON format, like
{"run_uuid": "288523d9-b3ca-491b-a490-27b10c384ce1"}
Go here for information on all the inputs for a job. (TODO: update)
The second step is to GET your results at the results endpoint using your run_uuid. The URL will look like:
https://developer.nrel.gov/api/reopt/stable/job/288523d9-b3ca-491b-a490-27b10c384ce1/results
Note that it can take some time to optimize your Scenario. While the job is running the Scenario.status will be "Optimizing...". Once the job is complete the status will be "optimal" (assuming no problems were encountered).
The API response will contain three top level keys: (TODO: still true?)
- "inputs": all of the inputs that you provided in addition to all the other default values that were used;
- "outputs": the optimization results; and
- "messages": information on input validation as well as errors if they occurred.
This repository contains example scripts to run the REopt API. See the single_scenario_example.ipynb and multi_scenario_examply.ipynb as starting points.
An optimization job is created by POST'ing your Scenario to the job endpoint.
For example, a Scenario POST looks like:
{
"Site": {
"longitude": -118.1164613,
"latitude": 34.5794343
},
"ElectricLoad": {
"doe_reference_name": "MidriseApartment",
"annual_kwh": 1000000.0
},
"ElectricTariff": {
"urdb_label": "5ed6c1a15457a3367add15ae"
},
"PV": {},
"Financial": {
"elec_cost_escalation_rate_fraction": 0.03,
"analysis_years": 20,
}
All possible input keys can be viewed in the API code (which also contains descriptions, defaults, and minimum/maximum values of the inputs) or the REopt.jl documentation.
Note that many of the input fields in the above example are not required. If you see a default value in the models.py for any field, then it is not required. Also, some fields are conditionally required. For example there are many ways to define your electric load profile, including providing your own loads_kw, scaling one (or multiple) DoE Commercial Reference Building (CRB) profiles, or using a DoE CRB default load. See the REopt.jl documentation for more details.