-
Notifications
You must be signed in to change notification settings - Fork 35
4. API endpoints
The root URL for accessing the API is https://developer.nrel.gov/api/reopt.
The next directory of any URL is determined by which version of the API you wish to access. The safest and recommended directory is the stable/ directory. The stable/ directory will point to v3/ as of the end of September 2023. Before its release, the third version of the API is accessible via v3/ and is available now under the dev/ directory.
The analysis endpoints facilitate posting a REopt® analysis job, retrieving the results, downloading a proforma, and obtaining some statistics related to how long a given energy system can meet a site critical load during electrical outages. Example: https://developer.nrel.gov/api/reopt/stable/help?API_KEY=DEMO_KEY
This URL is where you POST your Scenario to by optimized by REopt. If the inputs are valid, then the API will return a run_uuid that can be used to access results, the proforma, and resilience statistics. Go here for information on all the inputs for a job.
After POST'ing a valid job you will receive a run_uuid. To check for your results you use a GET method at this URL. Go here for information on all the outputs for a job.
Returns a spreadsheet proforma in Excel format. Access this endpoint in a browser to automatically download the file.
After POST'ing a valid job you will receive a run_uuid. Once your status is "optimal" (returned from the job/run_uuid/results endpoint). You can POST an outagesimjob that will run the outage simulator using your results to calculate outage survivability metrics of the cost-optimal energy system. This endpoint starts a two step process similar to the job endpoint (see next endpoint). Your post will look like:
{"run_uuid": "288523d9-b3ca-491b-a490-27b10c384ce1"}
An optional input is "bau" for business-as-usual, which is a boolean. For example, a POST as follows:
{
"run_uuid": "288523d9-b3ca-491b-a490-27b10c384ce1",
"bau": true
}
will also calculate the resilience statistics for the bau scenario. Note that if the bau scenario does not have any existing capacities (such as an existing Generator or PV system) then the survivability probabilities will all be zero.
Returns descriptive statistics of resilience metrics explaining how long the system can function during outages.
These endpoints are provide information on input defaults as well as filters that are used for input validation (primarily related to the job/ endpoint).
Provides a JSON response detailing the input parameters, including data formats, minimum and maximum allowable values, and dependencies with related parameters.
Provides a list of known invalid Utility Rate Database labels, i.e. rates they may have incomplete information or cannot be modeled.
Provides the annual kWh consumed by a Department of Energy Commercial Reference Building. These values are useful if you need a starting point for an unknown site load. Query parameters include:
- doe_reference_name
- latitude
- longitude
Provides the annual energy timeseries for a LoadProfile, LoadProfileBoilerFuel, or LoadProfileChillerThermal based on the Department of Energy Commercial Reference Building (CRB) dataset. Only one load profile type can be returned based on the load_type specified. By default, load_type is assumed to be 'electric'.
When load_type is 'electric' a LoadProfile is constructed. Query parameters include:
- load_type
- doe_reference_name
- latitude
- longitude
- annual_kwh
- monthly_totals_kwh (alternative to annual_kwh)
Note: monthly_totals_kwh can be a list of 12 values (e.g. [100,200,350,400,600,900,1000,1200,600,500,400,300]) or broken out into 12 0-indexed parameters (i.e. monthly_totals_kwh[0]=100,monthly_totals_kwh[0]=200,monthly_totals_kwh[0]=350,...). Also, if neither annual_kwh or monthly_totals_kwh are provided, a default annual energy consumption will be assumed based on the CRB dataset.
When load_type is 'electric' response attributes include: loads_kw, annual_kwh, min_kw, mean_kw, max_kw
When load_type is 'heating', a LoadProfileBoilerFuel is constructed. Query parameters include:
- load_type
- doe_reference_name
- latitude
- longitude
- annual_mmbtu
- monthly_mmbtu (alternative to annual_mmbtu) Note: monthly_mmbtu can be a list of 12 values (e.g. [100,200,350,400,600,900,1000,1200,600,500,400,300]) or broken out into 12 0-indexed parameters (i.e. monthly_mmbtu[0]=100,monthly_mmbtu[0]=200,monthly_mmbtu[0]=350,...). Also, if neither annual_mmbtu or monthly_mmbtu are provided, a default annual energy consumption will be assumed based on the CRB dataset.
When load_type is 'heating' response attributes include: loads_mmbtu, annual_mmbtu, min_mmbtu, mean_mmbtu, max_mmbtu
When load_type is 'cooling', a LoadProfileChillerThermal is constructed. Query parameters include:
- load_type
- doe_reference_name
- latitude
- longitude
- annual_tonhour
- monthly_tonhour (alternative to annual_tonhour)
- chiller_cop
- max_thermal_factor_on_peak_load Note: monthly_tonhour can be a list of 12 values (e.g. [100,200,350,400,600,900,1000,1200,600,500,400,300]) or broken out into 12 0-indexed parameters (i.e. monthly_tonhour[0]=100,monthly_tonhour[0]=200,monthly_tonhour[0]=350,...). Also, if neither annual_tonhour or monthly_tonhour are provided, a default annual energy consumption will be assumed based on the CRB dataset. Furthermore, if max_thermal_factor_on_peak_load is not provided, the default as specified in will be used. A default chiller_cop will also be calculated based on the load if one is not provided.
When load_type is 'heating' and the input parameters as described have been provided, response attributes include: loads_ton, annual_tonhour, min_ton, mean_ton, max_ton, chiller_cop
When load_type is 'cooling', a LoadProfileChillerThermal load profile can be returned as a percentage of total load for a default CRB profile, using these alternative query parameters:
- load_type
- doe_reference_name
- latitude
- longitude
- annual_fraction
- monthly_fraction (alternative to annual_fraction) Note: monthly_fraction can be a list of 12 values (e.g. [0.25,0.15,0.25,0.2,0.2,0.2,0.45,0.5,0.35,0.3,0.3,0.25,]) or broken out into 12 0-indexed parameters (i.e. monthly_fraction[0]=0.25,monthly_fraction[0]=0.15,monthly_fraction[0]=0.25,...). When load_type is 'heating' and the input parameters as described have been provided, response attributes include: loads_fraction, annual_fraction, min_fraction, mean_fraction, max_fraction.
Provides the Generator efficiency (slope_gal_per_kwh and intercept_gal_per_hr) for a given nameplate capacity.
Query parameters include:
- generator_kw
Provides the ElectricTariff hourly emissions profile in pounds of carbon dioxide per kilowatt for a given location. Query parameters include:
- latitude
- longitude
Returns defaults including: prime_mover, size_class, hw_or_steam, default_inputs, chp_size_based_on_avg_heating_load_kw, size_class_bounds. Query parameters include:
- existing_boiler_production_type_steam_or_hw
- avg_boiler_fuel_load_mmbtu_per_hr
- prime_mover
- size_class Note: Must provide either existing_boiler_production_type_steam_or_hw and avg_boiler_fuel_load_mmbtu_per_hr or prime_mover.
Provides the COP of an ElectricChiller subject to a maximum cooling load, as well as a ton-hour to kilowatt-thermal conversion factor. Query parameters include:
- max_kw
- max_ton
- max_thermal_factor_on_peak_load Must provide either max_kw or max_ton. By default, max_thermal_factor_on_peak_load is 1.25.
Provides COP (and electric COP) subject to hot_water_or_steam and/or prime_mover inputs, as well as the installed_cost_us_dollars_per_ton and om_cost_us_dollars_per_ton of a system based on the peak cooling thermal load. Query parameters include:
- max_cooling_load_tons
- hot_water_or_steam
- prime_mover Note that hot_water_or_steam and prime_mover are optional. The default value for hot_water_or_steam is hot_water. If hot_water_or_steam is provided, prime_mover is not used. If hot_water_or_steam is NOT provided and prime_mover is, prime_mover will refer to Boiler prime mover defaults.
Returns parameters for defining and summarizing unavailability periods, including formatted_datetime_periods (ISO 8601 YYYY-MM-DDThh format) and weekday_weekend_total_hours_by_month, a summary of a yearly profile that calculates weekday, weekend, and total hours by month. Query parameters include:
- year
- chp_prime_mover
- chp_unavailability_periods Note, chp_prime_mover is required if chp_unavailability_periods is not provided, otherwise not required or used. Also, chp_unavailability_periods is list of dictionaries, one dict per unavailability period (as defined in the CHP input attributes).
Returns a summary of optimization jobs for a specific user. For each job, the follow attributes are reported:
- run_uuid
- status
- created (date)
- description
- focus
- address
- urdb_rate_name
- doe_reference_name
- npv_us_dollars
- net_capital_costs
- year_one_savings_us_dollars
- pv_kw
- wind_kw
- gen_kw
- batt_kw
- batt_kwh
API_KEY parameter must be added to url Run a REopt optimization: /job? Get descriptions of possible inputs: /help? Get descriptions of possible inputs: /job/inputs? Get descriptions of possible outputs: /job/outputs? Get CHP defaults, which depend on other CHP inputs: /chp_defaults? Get absorption chiller defaults, which depend on other absorption chiller inputs: /absorption_chiller? Get grid emissions for a location: /emissions_profile? Get EASIUR health emissions cost data for a location: /easiur_costs? Get a simulated load profile: /simulated_load? Get a summary of a user's optimization jobs: /<user_uuid>/summary? Get a summary of a subset of a user's optimization jobs: /<user_uuid>/summary_by_chunk? Unlink an optimization job from a user: /<user_uuid>/unlink/<run_uuid>? Get outage start times centered or starting on peak load: /peak_load_outage_times? Check if a URDB label is in a set of invalid labels: /invalid_urdb? Get a summary of a yearly CHP unavailability profile: /schedule_stats?