Skip to main content
Warning: You are using the test version of PyPI. This is a pre-production deployment of Warehouse. Changes made here affect the production instance of TestPyPI (testpypi.python.org).
Help us improve Python packaging - Donate today!

Enertiv API wrapper to access the EPA's Portfolio Manager database.

Project Description
***
# Getting Started

This is a python wrapper for the EPA's Portfolio Manager Web Services. The Portfolio Manager API is available at https://portfoliomanager.energystar.gov/webservices/home.

Generally, this API works by doing the following:

- Log into a user by instantiating an object of the PortfolioManager() class with a Portfolio Manager username and password. Any valid Portfolio Manager username and password will also work as a login at www.energystar.gov/benchmarking, and needs to be enabled to use Web Services.
- Just about everything in the Portfolio Manager has an ID. This includes accounts, customers, properties, property uses, meters, monthly energy details, and more. Using the Portfolio Manager API involves a lot of identifying and tracking ID numbers.
- Using an ID number and the proper API call, you can access information stored in the Portfolio Manager database.

Let's go through an example. To get started, instantiate an instance of the PortfolioManager class with a Portfolio Manager username and password (the standard Enertiv login will work here).


```python
#password field is being left empty, needs to be added to continue. Add the password between the second set of single quotes '' on the following line.
enertiv_test = PortfolioManager('enertiv', '')
```

The PortfolioManager object you create in the previous step is able to access almost anything available within Portfolio Manager. (Note: If you are not familiar with Portfolio Manager, a good place to start before using the API would be the standard Portfolio Manager website at www.energystar.gov/benchmark. At that site you can log in, explore the tool, and see what kind of information is available through the Portfolio Manager database).

### Using this API, you can get:

__Account and Customer Information__
- information about your own account using the ```.account_info()``` method
- see your the account ID of the account you used to log into the system using the ```.account_id``` method
- see a list of pending sharing requests and notifications using the following set of calls:
```
.check_account_shares(),
.check_property_shares(),
.check_meter_shares(),
.check_portfolio_manager_notifications()```

- a list of customers who have connected their account with Enertiv's account using ```.customer_list```
- a list of properties shared by a single customer account using the ```.customer_property_list()``` method and a customer's account ID
- a list of all buildings connected to your account using ```.full_building_list```. This will return a list of Property objects.


__Property Information__

- property information, including floor area and year built using ```.property_info``` on a Property object
- a list of property uses (this shows if different areas like ground floor retail, data centers, offices, or other building uses have been put into Portfolio Manager) using ```.property_use_list``` on a Property object
- a list of meters associated with a property using ```.meter_list```. This returns a list of Meter objects.
- a list of property uses associated with a property using the ```.meter_list()```. This returns a list of PropertyUse objects.


__Property Use Information__
- information about a single property use (this helps you see how a building has changed over time) using ```.property_use_info``` on a PropertyUse object.

__Meter Information__

- Details about a meter by getting a meter ID for a given property with ```.meter_info``` on a Meter object
- energy data information for electricity, natural gas, steam, and (sometimes) water use for a given meter using the ```.meter_consumption_data_recent()``` method. By default, the method provides the 20 most recent energy data entires. Custom start and end dates to pull data from can be specified by setting the ```start_date= ``` and ```end_date= ``` parameters with a date in 'YYYY-mm-dd' format.
- get all energy consumption data for a meter (for all time) using the ```.meter_consumption_data_full()``` method

__ENERGY STAR Scores & Other Metrics__

- Get an ENERGY STAR score for a given month using the ```.get_ENERGY_STAR_score()``` method on a Property object. By default, the method only searches for the current month. Any month can be specified by setting the ```year= ``` and ``` month= ``` parameters.
- Get a list of ENERGY STAR scores over a date range using the ```.get_ENERGY_STAR_scores()``` method on a Property object. By default, the method searches the building over all time, but you can specify a custom date range by setting the ```start_date=``` and ```end_date=``` parameters.
- Get a list of any number of metrics available through Portfolio Manager by using the ```.get_metrics()``` method on a Property object. The default setting is to check the most recent month and provide a sample of popular metrics. To set the reporting date for a custom year/month, use the ```year=``` and ```month=``` parameters. To specify a custom list of metrics to retrieve, provide a string of comma delineated metrics to the ```metrics=``` parameter.

The full list of metrics is exhaustive, but generally includes information about ENERGY STAR scores, greenhouse gas emissions, heating and cooling degree days, weather adjusted and non-adjusted site and source energy, and aggregated property details. A full list of available metrics is available at http://downloads.energystar.gov/bi/portfolio-manager/Custom_Reporting_Metric_Inventory_en_US.xlsx

#### Example 1: Get Property Information for a Building


```python
enertiv_test.full_building_list
```

This call returns a list of Property objects for any property connected to the account we used to create the 'enertiv_test' object.
We use these Property objects to access other parts of the Portfolio Manager API.

Using calls on the Property object, we can access information about the building itself:


```python
building_list = enertiv_test.full_building_list
test_property = building_list[0]
```

```python
test_property.property_info
```
### Example 2: Accessing Energy Consumption Data

If we want to access more information about a property, such as the different property uses within the building or the building's meter configuration, we can do the following:

* Use the Property object to get a list of meters at the building

```python
property_meters = test_property.meter_list
test_meter = property_meters[0]
```
This returns a list of meters that serve the Property.

* Use any of the Meter objects retrieved from the previous ```.meter_list``` call to get energy consumption information for a specific meter:


```python
test_meter.meter_consumption_data_recent()
```

### Example 3: Retrieving ENERGY STAR scores and other metrics

Again using a Property object, we can get the ENERGY STAR score (or other metrics) about the building:

ENERGY STAR scores:

```python
ENERGY_STAR_scores = test_property.get_ENERGY_STAR_scores(start_date = "2014-11", end_date = "2016-01")
ENERGY_STAR_scores
```
Other metrics:

```python
test_property.get_metrics(year='2016', month='12')
```

You can specify up to 10 metrics to pull from the database by setting the 'metrics=' parameter in the method call, and specify which month to pull metrics for by setting the 'year=' and 'month='' parameters. The default behavior is to check the most recent month and provide a sample of popular metrics. A full list of available metrics is available at http://downloads.energystar.gov/bi/portfolio-manager/Custom_Reporting_Metric_Inventory_en_US.xlsx
Release History

Release History

This version
History Node

0.1.0

Download Files

Download Files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

File Name & Checksum SHA256 Checksum Help Version File Type Upload Date
portfolio-manager-service-0.1.0.tar.gz (6.9 kB) Copy SHA256 Checksum SHA256 Source Jun 1, 2017

Supported By

WebFaction WebFaction Technical Writing Elastic Elastic Search Pingdom Pingdom Monitoring Dyn Dyn DNS Sentry Sentry Error Logging CloudAMQP CloudAMQP RabbitMQ Heroku Heroku PaaS Kabu Creative Kabu Creative UX & Design Fastly Fastly CDN DigiCert DigiCert EV Certificate Rackspace Rackspace Cloud Servers DreamHost DreamHost Log Hosting