1. Knowledge Base
  2. Downloads and Documentation

How do I use the Denowatts API?

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:

  1. Raw Device records (up to 1-minute); or
  2. 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
Onsite Commissioning

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