Buildings
Energy Asset - Buildings

Services relating to buildings of the Energy Asset Tool

Supported Formats

json, xml
>>>

GET /api/v1/buildings
Retrieve all buildings belonging to the user.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
404 Unsupported operation
500 Unspecified error on server.
>>>

GET /api/v1/buildings/:id
Retrieve the building with the given ID, including all related data to the building.

Also see status_types => To retrieve a list of valid status_type_id.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
404 Unsupported operation
500 Unspecified error on server.

Examples

json:
{"building":{"id":2,"name":"Test Building","last_accessed":null,"year_of_construction":2013,"address":"1234 Somewhere Ave.","city":"Richland","state":"WA","zip_code":"99352","created_at":"2015-01-26T22:46:33Z","updated_at":"2015-01-26T22:46:33Z","user_id":13,"total_floor_area":1000.0,"notes":"Some notes about my building.","status_type_id":1,"use_types":[{"id":2,"display_name":"Lodging","created_at":"2014-11-24T20:30:56Z","updated_at":"2014-11-24T20:30:56Z","service_name":"hotel","operating_hours_per_week":"106.0","cooling_set_point":"70.0","heating_set_point":"70.0","misc_energy_loads":"1.11","sq_ft_per_occ":250,"score_type_id":3}],"blocks":[{"id":2,"name":"Block 2","building_id":2,"shape_id":1,"dimension_1":10.0,"dimension_2":10.0,"dimension_3":10.0,"dimension_4":10.0,"dimension_5":10.0,"dimension_6":10.0,"dimension_7":10.0,"dimension_8":10.0,"dimension_9":10.0,"dimension_10":10.0,"number_of_floors":1,"floor_to_floor_height":10.0,"has_drop_ceiling":false,"orientation":10.0,"is_above_ground":true,"created_at":"2015-01-26T22:46:33Z","updated_at":"2015-01-26T22:46:33Z","vertices":"10","position":"10","selected":false,"floor_to_ceiling_height":10.0,"ui_id":"10","sides":"4","number_of_bg_floors":1,"uses_percent_served":false,"has_timer_controls":false,"skylight_id":null,"roof_id":null,"floor_id":null,"operation_id":null,"building_use_type_id":2,"perimeter_zone_depth":null,"zone_layout_id":null,"percent_footprint":null,"operating_season_id":null,"skylight_layout_id":null,"low_flow_faucets":null,"co_sensors":null,"building_use_type":{"id":2,"use_type_id":2,"building_id":2,"created_at":"2015-01-26T22:46:33Z","updated_at":"2015-01-26T22:46:33Z","use_type_color_id":3},"shape":{"id":1,"name":"Rectangle","file_path":"","sort_order":1,"created_at":"2014-11-24T20:30:56Z","updated_at":"2014-11-24T20:30:56Z","service_name":"rectangle","surface_count":4},"":null,"surfaces":[],"block_air_handlers":[],"air_handlers":[],"block_zone_equipments":[],"zone_equipments":[],"block_fixtures":[],"fixtures":[],"block_water_heaters":[],"water_heaters":[]}],"ratings":[],"plants":[],"air_handlers":[],"zone_equipments":[],"water_heaters":[],"fixtures":[],"walls":[],"windows":[],"roofs":[],"floors":[],"skylights":[],"operations":[]}}
xml:
<?xml version="1.0" encoding="UTF-8"?>
<building>
  <id type="integer">2</id>
  <name>Test Building</name>
  <last-accessed nil="true"/>
  <year-of-construction type="integer">2013</year-of-construction>
  <address>1234 Somewhere Ave.</address>
  <city>Richland</city>
  <state>WA</state>
  <zip-code>99352</zip-code>
  <created-at type="datetime">2015-01-26T22:48:17Z</created-at>
  <updated-at type="datetime">2015-01-26T22:48:17Z</updated-at>
  <user-id type="integer">13</user-id>
  <total-floor-area type="float">1000.0</total-floor-area>
  <notes>Some notes about my building.</notes>
  <status-type-id type="integer">1</status-type-id>
  <use-types type="array">
    <use-type>
      <id type="integer">2</id>
      <display-name>Lodging</display-name>
      <created-at type="datetime">2014-11-24T20:30:56Z</created-at>
      <updated-at type="datetime">2014-11-24T20:30:56Z</updated-at>
      <service-name>hotel</service-name>
      <operating-hours-per-week type="decimal">106.0</operating-hours-per-week>
      <cooling-set-point type="decimal">70.0</cooling-set-point>
      <heating-set-point type="decimal">70.0</heating-set-point>
      <misc-energy-loads type="decimal">1.11</misc-energy-loads>
      <sq-ft-per-occ type="integer">250</sq-ft-per-occ>
      <score-type-id type="integer">3</score-type-id>
    </use-type>
  </use-types>
  <blocks type="array">
    <block>
      <id type="integer">2</id>
      <name>Block 2</name>
      <building-id type="integer">2</building-id>
      <shape-id type="integer">1</shape-id>
      <dimension-1 type="float">10.0</dimension-1>
      <dimension-2 type="float">10.0</dimension-2>
      <dimension-3 type="float">10.0</dimension-3>
      <dimension-4 type="float">10.0</dimension-4>
      <dimension-5 type="float">10.0</dimension-5>
      <dimension-6 type="float">10.0</dimension-6>
      <dimension-7 type="float">10.0</dimension-7>
      <dimension-8 type="float">10.0</dimension-8>
      <dimension-9 type="float">10.0</dimension-9>
      <dimension-10 type="float">10.0</dimension-10>
      <number-of-floors type="integer">1</number-of-floors>
      <floor-to-floor-height type="float">10.0</floor-to-floor-height>
      <has-drop-ceiling type="boolean">false</has-drop-ceiling>
      <orientation type="float">10.0</orientation>
      <is-above-ground type="boolean">true</is-above-ground>
      <created-at type="datetime">2015-01-26T22:48:17Z</created-at>
      <updated-at type="datetime">2015-01-26T22:48:17Z</updated-at>
      <vertices>10</vertices>
      <position>10</position>
      <selected type="boolean">false</selected>
      <floor-to-ceiling-height type="float">10.0</floor-to-ceiling-height>
      <ui-id>10</ui-id>
      <sides>4</sides>
      <number-of-bg-floors type="integer">1</number-of-bg-floors>
      <uses-percent-served type="boolean">false</uses-percent-served>
      <has-timer-controls type="boolean">false</has-timer-controls>
      <skylight-id nil="true"/>
      <roof-id nil="true"/>
      <floor-id nil="true"/>
      <operation-id nil="true"/>
      <building-use-type-id type="integer">2</building-use-type-id>
      <perimeter-zone-depth nil="true"/>
      <zone-layout-id nil="true"/>
      <percent-footprint nil="true"/>
      <operating-season-id nil="true"/>
      <skylight-layout-id nil="true"/>
      <low-flow-faucets nil="true"/>
      <co-sensors nil="true"/>
      <building-use-type>
        <id type="integer">2</id>
        <use-type-id type="integer">2</use-type-id>
        <building-id type="integer">2</building-id>
        <created-at type="datetime">2015-01-26T22:48:17Z</created-at>
        <updated-at type="datetime">2015-01-26T22:48:17Z</updated-at>
        <use-type-color-id type="integer">3</use-type-color-id>
      </building-use-type>
      <shape>
        <id type="integer">1</id>
        <name>Rectangle</name>
        <file-path></file-path>
        <sort-order type="integer">1</sort-order>
        <created-at type="datetime">2014-11-24T20:30:56Z</created-at>
        <updated-at type="datetime">2014-11-24T20:30:56Z</updated-at>
        <service-name>rectangle</service-name>
        <surface-count type="integer">4</surface-count>
      </shape>
      < nil="true"/>
      <surfaces type="array"/>
      <block-air-handlers type="array"/>
      <air-handlers type="array"/>
      <block-zone-equipments type="array"/>
      <zone-equipments type="array"/>
      <block-fixtures type="array"/>
      <fixtures type="array"/>
      <block-water-heaters type="array"/>
      <water-heaters type="array"/>
    </block>
  </blocks>
  <ratings type="array"/>
  <plants type="array"/>
  <air-handlers type="array"/>
  <zone-equipments type="array"/>
  <water-heaters type="array"/>
  <fixtures type="array"/>
  <walls type="array"/>
  <windows type="array"/>
  <roofs type="array"/>
  <floors type="array"/>
  <skylights type="array"/>
  <operations type="array"/>
>>>

GET /api/v1/buildings/:id/simple
Retrieve the building with the given ID and return a simplified data structure the does not include all of the nested info.

Also see status_types => To retrieve a list of valid status_type_id.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
404 Unsupported operation
500 Unspecified error on server.

Examples

json:
{"building":{"id":2,"name":"Test Building","last_accessed":null,"year_of_construction":2013,"address":"1234 Somewhere Ave.","city":"Richland","state":"WA","zip_code":"99352","created_at":"2015-01-26T22:57:12Z","updated_at":"2015-01-26T22:57:12Z","user_id":13,"total_floor_area":1000.0,"notes":"Some notes about my building.","status_type_id":1"}}
xml:
<building>
  <id type="integer">2</id>
  <name>Test Building</name>
  <last-accessed nil="true"/>
  <year-of-construction type="integer">2013</year-of-construction>
  <address>1234 Somewhere Ave.</address>
  <city>Richland</city>
  <state>WA</state>
  <zip-code>99352</zip-code>
  <created-at type="datetime">2015-01-26T22:59:17Z</created-at>
  <updated-at type="datetime">2015-01-26T22:59:17Z</updated-at>
  <user-id type="integer">13</user-id>
  <total-floor-area type="float">1000.0</total-floor-area>
  <notes>Some notes about my building.</notes>
  <status-type-id nil="true"/>
  <status-type-id type="integer">1</status-type-id>
</building>
>>>

POST /api/v1/buildings
Create a new building. Response for a successful request is a complete Building object with the assigned unique ID of the new building.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
404 Unsupported operation
500 Unspecified error on server.

Examples

{"name":"Test Building","total_floor_area":"1000","year_of_construction":"2013","zip_code":"99352","city":"Richland","state":"WA"}
<building>
  <name>Test Building</name>
  <year-of-construction>2013</year-of-construction>
  <address>1234 Somewhere Ave.</address>
  <city>Richland</city>
  <state>WA</state>
  <zip-code>99352</zip-code>
  <total-floor-area>1000</total-floor-area>
  <notes>Some notes about my building.</notes>
</building>

Params

Param name Description
name
required

Name of building.

Validations:

  • Must be a String
year_of_construction
required

Year building was completed.

Validations:

  • Must be a Integer
address
required

Street address of building.

Validations:

  • Must be a String
city
required

City of address.

Validations:

  • Must be a String
state
required

State of address.

Validations:

  • Must be a String
zip_code
required

Zipcode of address.

Validations:

  • Must be a String
total_floor_area
required

Gross floor area in square feet.

Validations:

  • Must be a Integer
notes
optional

Optional notes about building.

Validations:

  • Must be a String
>>>

PUT /api/v1/buildings/:id
Update building account with given ID. Sets Status_Type back to \"Editing\". Nothing is returned.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
404 Unsupported operation
500 Unspecified error on server.
>>>

GET /api/v1/buildings/:id/validate
Determine if a single Building, specified by the ID parameter, is ready to be simulated. Response will include a Boolean 'valid' property and an array of validation errors (empty if the Building is valid). The types of errors can be broken down to whole building and specific block errors.
Building-specific errors:
   building_without_blocks
Block-specific errors :
   has_small_blocks
   blocks_without_use_types
   blocks_without_roofs
   blocks_without_floors
   blocks_without_walls
   blocks_without_wwr
   blocks_without_percent_footprint
   blocks_without_fixtures
   blocks_without_fixture_values
   blocks_with_fixture_values_too_high
   blocks_with_fixture_values_too_low
   blocks_without_primary_hvac

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
404 Unsupported operation
500 Unspecified error on server.

Examples

Invalid building example:
  {
  "valid": false,
  "errors": [
    "building_without_block"
    ]
  }
Invalid block example:
{
  "valid": false,
  "errors": [
    {
      "blocks_without_primary_hvac": [
        {
          "building_id": 2,
          "building_use_type_id": 2,
          "color": "c8dcdc",
          "created_at": "2013-09-24T18:58:09Z",
          "dimension_1": 100,
          "dimension_10": null,
          "dimension_2": 100,
          "dimension_3": null,
          "dimension_4": null,
          "dimension_5": null,
          "dimension_6": null,
          "dimension_7": null,
          "dimension_8": null,
          "dimension_9": null,
          "floor_id": 2,
          "floor_to_ceiling_height": 9,
          "floor_to_floor_height": 12,
          "has_drop_ceiling": null,
          "has_timer_controls": null,
          "id": 2,
          "is_above_ground": true,
          "name": "b1",
          "number_of_bg_floors": 0,
          "number_of_floors": 1,
          "operating_season_id": null,
          "operation_id": null,
          "orientation": 0,
          "percent_footprint": null,
          "perimeter_zone_depth": null,
          "position": "{"x":0,"z":0,"y":6}",
          "roof_id": 2,
          "selected": null,
          "shape_id": 1,
          "sides": null,
          "skylight_id": 2,
          "skylight_layout_id": null,
          "ui_id": "",
          "updated_at": "2013-09-24T18:58:10Z",
          "uses_percent_served": false,
          "vertices": "[[{"x":50,"z":50,"y":0},{"x":50,"z":-50,"y":0},{"x":-50,"z":-50,"y":0},{"x":-50,"z":50,"y":0}],[{"x":50,"z":50,"y":12},{"x":50,"z":-50,"y":12},{"x":-50,"z":-50,"y":12},{"x":-50,"z":50,"y":12}]]",
          "zone_layout_id": null
        }
      ]
    }
  ]
}

Valid example (json):
  {
    "valid": true,
    "errors": []
  }
Example with errors (xml):
<hash>
<valid type="boolean">false</valid>
<errors type="array">
<error>
<blocks-without-hvac-systems type="array"></blocks-without-hvac-systems>
</error>
</errors>
</hash>
>>>

POST /api/v1/buildings/:id/simulate
Submit a single Building for simulation and scoring, which will also validate the building. The simulation process can take anywhere from several minutes to a few hours depending on the server load, so the response from this request will be a simple 200 Success. When the simulation is finished, an email will be sent to the User who created the Building. At this time simulations cannot be canceled.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
500 Unspecified error on server.
404 Unable to run simulation for building.

Examples

(xml)
<hash>
 <success>
  Your request has been queued! You will receive the result at the following email: smart.staffguy@pnnl.gov
 </success>
</hash>
{"(json) success":"Your request has been queued! You will receive the result at the following email: smart.staffguy@pnnl.gov
{"error":"Unable to run simulation for building."}
{"simulation_complete":"Unable to submit simulation request since the building has already been simulated and no changes have been made to the data."}
{"simulation_running":"Unable to submit simulation request since the building already has a simulation request."}
>>>

GET /api/v1/buildings/:id/score
Retrieve the current score information for a single Building, specified by the ID parameter. Response is a Score object with the current and potential scores and EUIs.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
500 Unspecified error on server.
404 Unable to run simulation for building.

Examples

{
  "score": {
    "source_norm_eui": 242,
    "source_points": 4,
    "potential_norm_eui": 142,
    "potential_points": 6
  }
}
{"simulation_not_submitted":"No score has been computed for this building yet."}
{"simulation_running":"Building simulation is still running so score cannot be returned yet."}
error (xml):
<hash>
 <simulation-running>
  Building simulation is still running so score cannot be returned yet.
 </simulation-running>
</hash>
>>>

GET /api/v1/buildings/:id/report
Retrieve the current PDF report for a single Building, specified by the ID parameter.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
404 Unsupported operation
500 Unspecified error on server.
>>>

GET /api/v1/buildings/:id/model_one_idf
Retrieve the IDF used to simulate a single Building, current/proposed, specified by the ID parameter.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
404 Unsupported operation
500 Unspecified error on server.
>>>

GET /api/v1/buildings/:id/model_one_osm
Retrieve the OSM for a single Building, current/proposed, specified by the ID parameter.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
404 Unsupported operation
500 Unspecified error on server.
>>>

GET /api/v1/buildings/:id/model_two_idf
Retrieve the recommended/baseline model IDF used to simulate a single Building, specified by the ID parameter.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
404 Unsupported operation
500 Unspecified error on server.
>>>

GET /api/v1/buildings/:id/model_two_osm
Retrieve the recommended/baseline model OSM of a single Building, specified by the ID parameter.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
401 Access Denied -- Not owner of building and/or the building has not been shared with this user.
404 Unsupported operation
500 Unspecified error on server.