Web Service Documentation / Categories / Reporting Services

Reporting Services

The Reporting Services allows you to retrieve metrics for your properties and respond to data requests on behalf of your customers.

The services that allow you to retrieve reporting metrics are divided into 2 categories. The first category involves a set of APIs that allow you to interface with the Custom Reporting feature within the Portfolio Manager user interface. This set of web services are only available within the Live environment. For more information, please see the Custom Reporting API Guide. These APIs also allow you to interface with over 10 ENERGY STAR reports that EPA has predefined. For more information, please see the ENERGY STAR Reports API Guide. All metric calculations initiated by these APIs behave asynchronously. The second category involves the original set of APIs that allow you to retrieve a smaller set of metric calculations which behave synchronously.

The services that allow you to respond to data requests on behalf of your customers are similar to the functionality provided by the user interface. This set of web services are only available within the Live environment. For more information, please see the Data Response API Guide.

Custom Reporting (Template Management)

Method REST URI * Description
GET /reports/metrics?groupIds=(groupIds)&availableToCustomMetrics=(availableToCustomMetrics) Returns a list of available metrics to use in a report template.
POST /reports/templates Creates a report template in your account. Returns unique identifiers for both the template and the corresponding report.
GET /reports/templates/(templateId) Returns the information for a specific report template. The report template must be owned by you.
PUT /reports/templates/(templateId) Updates the information for a specific report template. The report template must be owned by you.
DELETE /reports/templates/(templateId) Deletes a specified report template. The report template must be owned by you.
GET /reports/templates?type=(type) Returns a list of report templates in your account.

Custom Reporting (Report Management)

Method REST URI * Description
GET /reports/(reportId) Returns the information for a specific report. The report must be owned by you.
PUT /reports/(reportId) Updates the information for a specific report. The report must be owned by you.
GET /reports/(reportId)/download?type=(type) Downloads the results for a specific report. The report must be owned by you.
POST /reports/(reportId)/generate Generates a specific report. The report must be owned by you.
GET /reports/(reportId)/status Returns the status information for a specific report. The report must be owned by you.
GET /reports?type=(type) Returns a list of reports in your account.

Custom Reporting (Responding to Data Requests)

Method REST URI * Description
GET /reports/customers/(customerId)/dataRequests/(dataRequestId) Returns the information for a specific customer's data request.
GET /reports/customers/(customerId)/dataRequests?status=(status) Returns a list of data requests for a specific customer.
POST /reports/customers/(customerId)/dataResponses Creates a data response for a specific customer's data request.
GET /reports/customers/(customerId)/dataResponses/(dataResponseId) Returns a list of properties associated to a specific customer's data response.
PUT /reports/customers/(customerId)/dataResponses/(dataResponseId) Updates the list of properties to a specific customer's data response.
DELETE /reports/customers/(customerId)/dataResponses/(dataResponseId) Deletes a specific customer's data response.
GET /reports/customers/(customerId)/dataResponses/(dataResponseId)/download?type=(type) Downloads the data response preview results for a specific customer.
GET /reports/customers/(customerId)/dataResponses/(dataResponseId)/errors/download?type=(type) Returns the error information associated to a specific customer's data response preview.
POST /reports/customers/(customerId)/dataResponses/(dataResponseId)/generate Generates a preview of a specific customer's data response.
GET /reports/customers/(customerId)/dataResponses/(dataResponseId)/receipt/download Downloads a PDF receipt of a specific customer's data response submission.
POST /reports/customers/(customerId)/dataResponses/(dataResponseId)/send Submits and finalizes a specific customer's data response.
GET /reports/customers/(customerId)/dataResponses/(dataResponseId)/status Returns the status information for a specific customer's data response.
DELETE /reports/customers/(customerId)/dataResponses/dataRequests/(dataRequestId) Deletes a specific customer's data request access.
GET /reports/customers/(customerId)/dataResponses/dataRequests/(dataRequestId)/download?type=(type) Downloads all of the data responses for a specific customer's data request.
GET /reports/customers/(customerId)/dataResponses?status=(status)&dataRequestId=(dataRequestId) Returns a list of data responses for a specific customer's data request.

Reporting

Method REST URI * Description
GET /property/(propertyId)/design/metrics Returns a list of metric values for an existing property design. The property must already be shared with you.
GET /property/(propertyId)/metrics Returns the values for a specified set of metrics and units for a specific property and period ending date. The property must already be shared with you.
GET /property/(propertyId)/metrics/monthly Returns a list of monthly metric values for a specific property and period ending date based on the specified set of metrics and measurement system.
GET /property/(propertyId)/reasonsForNoScore Returns a list of alert information that explains why a specific property cannot receive an ENERGY STAR score for a specific period ending date.
GET /property/(propertyId)/reasonsForNoWaterScore Returns a list of alert information that explains why a specific property cannot receive an ENERGY STAR water score for a specific period ending date.
GET /property/(propertyId)/useDetails/metrics Returns the time-weighted use detail values for a specific property, period ending date, and measurement system. The property must already be shared with you.

* For the LIVE environment, relative to the base URI:  https://portfoliomanager.energystar.gov/ws

LIVE