Usage Instructions

The HPXML to Home Energy Score (HEScore) translator can be run hosted through the HEScore API or directly on your local machine. Most users will find that the HEScore API is the preferred method since it easily fits into the API workflow and automates the process. The stand alone method is mostly for developers needing to debug and track down problems in the translation as well as for those who want to make modifications to the translation assumptions and code.

Home Energy Score API

The HEScore API provides the most generally applicable way use HPXML to generate a Home Energy Score. See the the Home Energy Scoring Tool API Documentation for details on how to do that.

The HPXML translator is made available through the API method submit_hpxml_inputs, which accepts an HPXML file as a Base64 encoded payload, so you will need to convert it. An example of how to do this in Python is:

import base64

with open('path/to/hpxmlfile.xml','r') as f:
    hpxml_as_base64 = base64.standard_b64encode(

Similar libraries and functionality exist in many languages.

Stand Alone

The HPXML to HEScore translator that is used within the Home Energy Score API can be used independently as well. It is a Python script that accepts an HPXML file as input and returns a JSON file with HEScore inputs arranged like the HEScore API call submit_inputs expects. It it useful to run it this way for debugging a translation of your particular flavor of HPXML file or for development of the translator.

Set Up

The program runs using Python 3.x. The instructions below will help you set up Python on your platform and get the translator installed.


  1. Download Python 3.x from and Install.
  2. Add C:\Python3X to your path. Here’s how.
  3. Follow instructions for All Platforms.

Mac OS X

  1. Install Homebrew.
  2. Open a terminal.
  3. Install Python 3.x using homebrew: brew install python
  4. Follow instructions for All Platforms.


  1. Install Python 3.x using the package manager for your platform.
  2. Follow instructions for All Platforms.

All Platforms

Optionally install and activate a virtual environment. Instructions here.

Install the package using pip:

pip install hescore-hpxml

Alternatively, you can install the latest and greatest directly from GitHub, which is useful if you’re going to do some development on the translator. To do so, get a copy of the source code from GitHub, using your preferred method. If you’re not sure, just click “Download ZIP”.

Open a terminal and use pip to install it in developer mode:

cd path/to/hescore-hpxml
pip install -e .[dev]

Running the Translator

The best way to figure out how to run the translator is to call it with the -h flag.

hpxml2hescore -h