A summary of Denowatts API v.2 (current)
API Instructions (RESTful) Version 3
Updated: May 31, 2023
I. Introduction
The Denowatts service includes API access to two call types:
- Raw Device records (up to 1-minute); or
- Clean Site records (5-minute)
|
Call Type |
Record Interval (minutes) |
|
Raw Device (ending timestamp) |
Varies by device. Typically between 1-15 minutes |
|
Clean Site (beginning timestamp) |
5 minute |
Monitoring services, customer enterprise applications, and other performance-related uses should use the Site Performance records for “Next Day Processed” and “Deno Clean Data”.
Real-time services such as aerial inspections, commissioning, and monitoring validation may choose to use Raw Deno records for low latency data.
|
Call Type |
Data |
Availability |
Use Case |
|
Raw Device |
Irradiance Cell Temperature Expected Power Meter data Inverter data |
~2 Minutes |
Aerial Inspections Monitoring Setup and Data Validation |
|
Clean |
“Site Rollup” Deno Weather Remote Weather Measured Generation Expected Energy |
1 Hour |
Monitoring Services Customer Enterprise Applications
|
|
“Next Day Processed” Key Performance Indices (KPIs) Learned Energy Losses (unvalidated) |
Next Day |
||
|
“Validated Data” Losses (Validated) |
5-Day |
II. GET Request Limitations
The Maximum Time Range per call is 7 days for Raw Deno records and 60 days for Site Performance records. Raw records are only accessible for 30 days after the timestamp. Each Denowatts Account is allowed 30 calls per minute for both API calls. No concurrent requests are allowed.
Error 400 is returned if requests exceed these limitations.
III. Raw Device Records
Use Case: The user would like to obtain raw data records from all Denowatts connected devices at a Site. A 2-minute record latency is acceptable.
The raw records deliver all timestamped records from individual devices. All Deno sensor records and MODBUS devices that have been mapped into the Denowatts gateways are available in this way. This method allows for direct data readings to be obtained from a single Device.
Each device will have a selection of metrics available. For example, a Deno sensor may have irr_poa_ref or irr_hor_ref depending on its orientation. Metrics available to MODBUS devices will be dependent on the specific device and which metrics were configured to be read over MODBUS. Consult https://my.denowatts.com/metrics to see the list of all possible metrics and corresponding unit.
Raw Device record GET requests should be delayed at least 2-minutes after the desired record timestamp. For example, the GET request for the 8:00 record should be requested at 8:02. Raw Device records use an ENDING timestamp convention, meaning a record with timestamp 8:00 will include data sampled from 7:59 through 8:00.
Resource URL
https://api.denowatts.com/api/v3/raw
Parameters
|
Parameter |
Description |
Example values |
|
dev_id |
The ID of the device to query. |
1.1.1.201 |
|
site_id |
The ID of the site to query. This can be found in the site analysis URL. |
547 |
|
start_date |
ISO 8601-formatted datetime for the start of the requested time span, in the timezone of the installed energy system. |
2013-09-25T00:00:00 or Simply 2013-09-25 |
|
end_date |
ISO 8601-formatted datetime for the end of the requested time span, in the timezone of the installed energy system. |
2013-09-26T00:00:00 or Simply 2013-09-26 |
|
metric |
(Optional) The specific metric to query. If given only the selected metric will be returned, otherwise all available metrics will be returned. |
irr_poa_ref |
|
order |
(Optional) “reverse” changes the newest timestamps to appear at the top of the response |
reverse |
Response Values
|
Value |
Description |
Example values |
|
status |
Status of the request made |
“OK” for good result, “ERROR” for any kind of error, see msg node for details |
|
msg |
When any error occurs, both from api or from user input parameter, this node will contain the error message. |
End date has to be greater than Start date |
|
total_records |
Total records found in a given range. |
498 |
|
data |
List of key/value pairs indicating the node identifier and value for each node included in the request. |
Array |
|
data[i].timestamp |
Timestamp of each record in system’s time zone. Available on all devices. |
2022-05-01 11:45:00 |
|
data[i].timestamp_iso |
Timestamp of each record in system’s time zone in ISO format. Available on all devices. |
2022-05-01T11:45:00-04:00 |
|
data[i].[key] |
All available data for the device will be listed for each node. |
Dependent on key |
|
next_page |
Indicates if there is any next page of records for current request. We provide a max 2000 records per request. |
true |
|
next_page_start_timestamp |
The start_date to use to get then next page of data if available. |
2022-05-01 11:45:00 |
Example GET Request
Raw Deno Data
https://api.denowatts.com/api/v3/raw?start_date=2023-05-1&end_date=2023-05-2&dev_id= 1.1.1.201&site_id=547
{
"status": "OK",
"total_records": 500,
"data": [
{
"timestamp": "2023-05-29 09:00:36",
"timestamp_iso": "2023-05-29T09:00:36-06:00",
"v_deno_cap": 5.27,
"v_deno_bat": 0,
"time_lag": 78,
"temp_deno": 50.6,
"temp_cell_deno": 50.6,
"temp_cell_bom": 44.3,
"temp_cell": 44.3,
"temp_bom": 41.4,
"pwr_expected": 6688,
"nrg_deno_expected": 133.183776855,
"irr_rpoa_ref": 32.41053342336259,
"irr_rpoa_eff": 19.2,
"irr_poa_ref": 985,
"irr_deno_3": 19.2,
"irr_deno_2": 985.1,
"irr_deno_1": 984.9,
"ins_tpoa_ref": 214.641708374,
"db_rssi": 40,
"ang_z": -39.340317146443354,
"ang_y": -0.1676367354856805,
"ang_x": 50.65918265234943,
"ang_tilt": 50.659682853556646
},
IV. Clean Records
Use Case: The user would like to obtain 5-minute weather, including remotely reported ambient temperature, wind speed/direction, precipitation, measured generation, and performance diagnostics. The 5-minute records include an average of all Deno sensors that are attached to an Array. A 60-minute delay in record availability (“Site Rollup”), Next Day availability (“Next Day Processed”), or 5-Day availability (“Validated Data”) is acceptable.
The Clean records return aggregated data from all Deno sensors and meters and attached to a Site. Sites are configured in the Customer Portal and are analogous to individual energy models. A Site may have one or more Deno sensors attached to provide weather and energy simulation data. Local ambient weather conditions are also included in this API based on the site’s geographical coordinates (provided by IBM Enhanced Local Conditions).
The availability of record information depends on the use case. For example, performance technicians may obtain basic performance metrics such as Energy Performance Index (EPI) within 75 minutes of the record timestamp (unprocessed) which may be helpful for same-day performance analysis. O&M services and customer dispatch may choose to obtain Site Performance data the following day (after 6:00 am EST) to see Learned Energy and Losses waterfall (unvalidated). Finally, analysts providing monthly performance reports may choose to call each month of data on the 5th day of the following month to obtain validated losses data (termed “Validated Data” by our marketing department).
Resource URL
https://api.denowatts.com/api/v3/clean
Parameters
|
Parameter |
Description |
Example values |
|
site_id |
The ID of the site to query. This can be found in the site analysis URL. |
547 |
|
start_date |
ISO 8601-formatted datetime for the start of the requested time span, in the time zone of the installed energy system |
2013-09-25T00:00:00 or Simply 2013-09-25 |
|
end_date |
ISO 8601-formatted datetime for the end of the requested time span, in the time zone of the installed energy system |
2013-09-26T00:00:00 or Simply 2013-09-26 |
|
metric |
(Optional) The specific metric to query. If given only the selected metric will be returned, otherwise all available metrics will be returned. |
irr_poa_ref |
|
order |
(Optional) “reverse” changes the newest timestamps to appear at the top of the response |
reverse |
Response Values
|
Value |
Description |
Example values |
|
status |
Status of the request made |
“OK” for good result, “ERROR” for any kind of error, see msg node for details |
|
msg |
When any error occurs, both from api or from user input parameter, this node will contain the error message |
End date has to be greater than Start date |
|
total_records |
Total records found in a given range |
498 |
|
kpi_data |
Key performance indices for the selected times. List of key/val pairs indicating the node identifier and value for each node included in the request. |
99.3 |
|
kpi_data.nrg_net_gen_total |
Total cumulative measured site generation for the selected time period (kWh) |
13303 |
|
kpi_data.nrg_expected_total |
Total cumulative expected energy for the selected time period (kWh) |
13059 |
|
kpi_data.nrg_leared_total |
Total cumulative learned energy for the selected time period (kWh) |
14724 |
|
kpi_data.nrg_commissioned_total |
Total cumulative commissioned energy for the selected time period (kWh) |
13195 |
|
kpi_data.EPI |
Expected Performance Index |
92.29 |
|
kpi_data.LPI |
Learned Performance Index |
90.93 |
|
kpi_data.CPI |
Commissioned Performance Index |
100.82 |
|
data |
List of key/val pairs indicating the node identifier and value for each node included in the request. (one record for each 15-min interval) |
Array |
|
data[i].timestamp |
Timestamp of each record in system’s timezone |
2022-05-01 11:45:00 |
|
data[i].timestamp_iso |
Timestamp of each record in system’s timezone in ISO format |
2022-05-01T11:45:00-04:00 |
|
data[i].[key] |
All available data for the site will be listed for each node. |
Dependent on key |
|
next_page |
Indicates if there is any next page of records for current request. We provide a max 2000 records per request. |
true |
|
next_page_start_timestamp |
The start_date to use to get then next page of data if available. |
2022-05-01 11:45:00 |
Example GET Requests
Site Performance
https://api.denowatts.com/api/v3/clean?start_date=2022-05-1&end_date=2022-05-2&site_id=547
{
"status": "OK",
"total_records": 97,
"kpi_data": {
"measured_energy_total": 13303,
"expected_energy_total": 13059,
"learned_energy_total": 14724,
"commissioned_energy_total": 13195,
"EPI": 92.29,
"LPI": 90.93,
"CPI": 100.82
},
"data": [
{
"timestamp": "2022-05-01 09:45:00",
"timestamp_iso": "2022-05-01T09:45:00-04:00",
"timestamp_utc": "2022-05-01 13:45:00",
"sunrise_time_local": "2022-05-01 05:40:02",
"sunset_time_local": "2022-05-01 19:54:11",
"irr_eff_cumul": 67.0347,
"irr_eff_val": 648.3,
"irr_front_cumul": 65.1869,
"irr_front_val": 628.914,
"irr_rear_cumul": 0.0981,
"irr_rear_val": 33.258,
"irr_ghi_cumul": 0,
"irr_ghi_val": 0,
"tcell": 32.67,
"tbom": 30.52,
"tamb": 10.25,
"wind_speed": 5.3,
"wind_direction": 30,
"snow_24hour": 0,
"snow_15min": 0,
"precip_24hour": 0,
"precip_15min": 0,
"expected_cumul": 885.1302,
"expected_val": 1396.362,
"comp_cumul": 884.8155,
"comp_val": 1381.034,
"learned_val": 1494.2549,
"measured_cumul": 696.7258,
"measured_val": 1351.6,
"systemic_loss": 0,
"shade_loss": 0,
"snow_loss": 0,
"outage_loss": 142.6549
},
{
"timestamp": "2022-05-01 10:00:00",
"timestamp_iso": "2022-05-01T10:00:00-04:00",
"timestamp_utc": "2022-05-01 14:00:00",
"sunrise_time_local": "2022-05-01 05:40:02",
"sunset_time_local": "2022-05-01 19:54:11",
"irr_eff_cumul": 67.2099,
"irr_eff_val": 701.05,
"irr_front_cumul": 65.3572,
"irr_front_val": 681.024,
"irr_rear_cumul": 0.1067,
"irr_rear_val": 34.364,
"irr_ghi_cumul": 0,
"irr_ghi_val": 0,
"tcell": 31.95,
"tbom": 28.54,
"tamb": 11,
"wind_speed": 6,
"wind_direction": 0,
"snow_24hour": 0,
"snow_15min": 0,
"precip_24hour": 0,
"precip_15min": 0,
"expected_cumul": 885.5082,
"expected_val": 1512.89,
"comp_cumul": 885.1895,
"comp_val": 1495.962,
"learned_val": 1607.62,
"measured_cumul": 697.0637,
"measured_val": 1434,
"systemic_loss": 0,
"shade_loss": 0,
"snow_loss": 0,
"outage_loss": 173.62
},
{
"timestamp": "2022-05-01 10:15:00",
"timestamp_iso": "2022-05-01T10:15:00-04:00",
"timestamp_utc": "2022-05-01 14:15:00",
"sunrise_time_local": "2022-05-01 05:40:02",
"sunset_time_local": "2022-05-01 19:54:11",
"irr_eff_cumul": 67.3974,
"irr_eff_val": 749.9,
"irr_front_cumul": 65.5395,
"irr_front_val": 729.256,
"irr_rear_cumul": 0.1155,
"irr_rear_val": 35.418,
"irr_ghi_cumul": 0,
"irr_ghi_val": 0,
"tcell": 31.04,
"tbom": 27.15,
"tamb": 11.5,
"wind_speed": 8,
"wind_direction": 0,
"snow_24hour": 0,
"snow_15min": 0,
"precip_24hour": 0,
"precip_15min": 0,
"expected_cumul": 885.9081,
"expected_val": 1599.066,
"comp_cumul": 885.5871,
"comp_val": 1590.244,
"learned_val": 1607.62,
"measured_cumul": 697.4222,
"measured_val": 1482.4,
"systemic_loss": 0,
"shade_loss": 0,
"snow_loss": 0,
"outage_loss": 125.22
}
],
"next_page": false}
Looking for the legacy v2 API? See this article: https://support.denowatts.com/api-v2-legacy