Services relating to buildings of the Energy Asset Tool

Supported Formats

json

GET /api/v2/preview_buildings
Retrieve all preview buildings belonging to the user.

Also see v2#preview_buildings#show_simple.

Retrieve all preview buildings belonging to the user. These buildings will be returned in the short format provided by the show_simple method.

Supported Formats

json

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

Response: [
  {
    "building_id": 1,
    "total_floor_area!": 10512.0,
    "orientation!": "North/South",
    "name": "Valid Preview Building Name",
    "year_of_construction": 1902,
    "address": "123 Main Street",
    "city": "Good City Name",
    "state": "MA",
    "zip_code": "12345",
    "notes": "Built via building upload spreadsheet.",
    "status!": "Rated",
    "assessment_type": "Test"
  },
  {
    "building_id": 1,
    "total_floor_area!": 10512.0,
    "orientation!": "North/South",
    "name": "Valid Preview Building Name",
    "year_of_construction": 1902,
    "address": "123 Main Street",
    "city": "Good City Name",
    "state": "MA",
    "zip_code": "12345",
    "notes": "Built via building upload spreadsheet.",
    "status!": "Rated",
    "assessment_type": "Test"
  }
]

Params

Param name Description
token
required

Identifies the user

Validations:

  • Must be a String


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

Supported Formats

json

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

Response: {
  "building_id": 1,
  "total_floor_area!": 10512.0,
  "orientation!": "North/South",
  "name": "Valid Preview Building Name",
  "year_of_construction": 1902,
  "address": "123 Main Street",
  "city": "Good City Name",
  "state": "MA",
  "zip_code": "12345",
  "notes": "Built via building upload spreadsheet.",
  "status!": "Rated",
  "assessment_type": "Test",
  "blocks": [
    {
      "block_id": 1,
      "lighting": [
        {
          "id": 1,
          "percent_served": 90.0,
          "percent_served_status!": "Do not know",
          "fixture_status!": "Do not know",
          "mounting_type": "Recessed",
          "lamp_type": "Fluorescent T12"
        },
        {
          "id": 2,
          "percent_served": 10.0,
          "percent_served_status!": "Do not know",
          "fixture_status!": "Do not know",
          "mounting_type": "Pendant",
          "lamp_type": "Incandescent/Halogen"
        }
      ],
      "use_type:name!": "Office",
      "roof:roof_type": "Built-up w/ metal deck",
      "roof:roof_type_status!": "Do not know",
      "floor:floor_type": "Slab-on-Grade",
      "floor:floor_type_status!": "Do not know",
      "surfaces:window_wall_ratio": 0.33,
      "surfaces:window_wall_ratio_status!": "Do not know",
      "wall:wall_type": "Brick/Stone on steel frame",
      "wall:wall_type_status!": "Do not know",
      "window:framing_type": "Metal w/ Thermal Breaks",
      "window:framing_type_status!": "Do not know",
      "window:glass_type": "Single Pane",
      "window:glass_type_status!": "Do not know",
      "water_heater:fuel_type": "Natural Gas",
      "water_heater:fuel_type_status!": "Do not know",
      "hvac_system:type": "Packaged Rooftop VAV with Electric Reheat",
      "hvac_system:type_status!": "Do not know",
      "hvac_system:fuel_type": "Electricity",
      "hvac_system:fuel_type_status!": "Do not know"
    }
  ]
}

Params

Param name Description
token
required

Identifies the user

Validations:

  • Must be a String


GET /api/v2/preview_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.

Supported Formats

json

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

Response: {
  "building_id": 1,
  "total_floor_area!": 10512.0,
  "orientation!": "North/South",
  "name": "Valid Preview Building Name",
  "year_of_construction": 1902,
  "address": "123 Main Street",
  "city": "Good City Name",
  "state": "MA",
  "zip_code": "12345",
  "notes": "Built via building upload spreadsheet.",
  "status!": "Rated",
  "assessment_type": "Test"
}

Params

Param name Description
token
required

Identifies the user

Validations:

  • Must be a String


DELETE /api/v2/buildings/preview/:id
Delete an existing preview building with the given ID. Nothing is returned.

Supported Formats

json

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) {"token":"1234TokenGoesHere"}

Params

Param name Description
token
required

Identifies the user

Validations:

  • Must be a String


GET /api/v2/buildings/preview/:id/duplicate
Duplicate an existing building with the given ID. Response for a successful request is to create a complete Building object with a new unique ID.The returned response is the short form of the building information.

Supported Formats

json

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

Response: {
  "building_id": 1,
  "total_floor_area!": 10512.0,
  "orientation!": "North/South",
  "name": "Valid Preview Building Name",
  "year_of_construction": 1902,
  "address": "123 Main Street",
  "city": "Good City Name",
  "state": "MA",
  "zip_code": "12345",
  "notes": "Built via building upload spreadsheet.",
  "status!": "Rated",
  "assessment_type": "Test"
}

Params

Param name Description
token
required

Identifies the user

Validations:

  • Must be a String


PUT /api/v2/preview_buildings/:id
Update building attributes for the building with given the ID. Sets the attribute certainty status to "Edited" for every attribute updated. The returned response is the long form of the building information.

Supported Formats

json

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.
422 Building is not in edit mode. Place building in edit mode first before editing
422 The attribute <attribute> which ends with ! can not be changed with the update method.
422 The attribute <attribute> can not be changed with the update method. To change this attribute you must delete the building and start again.
422 Can't update <attribute> because building has no <attribute>.

Examples

(json) PUT {
  "token": "1234TokenGoesHere",
  "building": {
    "block_id": "1",
    "building_name": "Updated Building Name",
    "building_notes": "Built via building upload spreadsheet."
  }
}
Response: {
  "building_id": 1,
  "total_floor_area!": 10512.0,
  "orientation!": "North/South",
  "name": "Valid Preview Building Name",
  "year_of_construction": 1902,
  "address": "123 Main Street",
  "city": "Good City Name",
  "state": "MA",
  "zip_code": "12345",
  "notes": "Built via building upload spreadsheet.",
  "status!": "Rated",
  "assessment_type": "Test",
  "blocks": [
    {
      "block_id": 1,
      "lighting": [
        {
          "id": 1,
          "percent_served": 90.0,
          "percent_served_status!": "Do not know",
          "fixture_status!": "Do not know",
          "mounting_type": "Recessed",
          "lamp_type": "Fluorescent T12"
        },
        {
          "id": 2,
          "percent_served": 10.0,
          "percent_served_status!": "Do not know",
          "fixture_status!": "Do not know",
          "mounting_type": "Pendant",
          "lamp_type": "Incandescent/Halogen"
        }
      ],
      "use_type:name!": "Office",
      "roof:roof_type": "Built-up w/ metal deck",
      "roof:roof_type_status!": "Do not know",
      "floor:floor_type": "Slab-on-Grade",
      "floor:floor_type_status!": "Do not know",
      "surfaces:window_wall_ratio": 0.33,
      "surfaces:window_wall_ratio_status!": "Do not know",
      "wall:wall_type": "Brick/Stone on steel frame",
      "wall:wall_type_status!": "Do not know",
      "window:framing_type": "Metal w/ Thermal Breaks",
      "window:framing_type_status!": "Do not know",
      "window:glass_type": "Single Pane",
      "window:glass_type_status!": "Do not know",
      "water_heater:fuel_type": "Natural Gas",
      "water_heater:fuel_type_status!": "Do not know",
      "hvac_system:type": "Packaged Rooftop VAV with Electric Reheat",
      "hvac_system:type_status!": "Do not know",
      "hvac_system:fuel_type": "Electricity",
      "hvac_system:fuel_type_status!": "Do not know"
    }
  ]
}
Example 1: {
  "token":"1234TokenGoesHere",
  "building": {
     "block_id":1,
     "assessment_type":"Test"
  }
}
Example 2: {
  "token":"1234TokenGoesHere",
  "building": {
    "block_id":1,
    "floor:floor_type":"Slab-on-Grade"
  }
}
Example 3: {
  "token":"1234TokenGoesHere",
  "building": {
    "block_id":1,
    "lighting:{fixture_id}:lamp_type":'LED'
  }
}

Params

Param name Description
token
required

Identifies the user

Validations:

  • Must be a String

building
required

describes the building

Validations:

  • Must be a Hash

building[block_id]
required

Identifies the internal block.

Validations:

  • Must be a String

building[name]
optional

Name of building.

Validations:

  • Must be a String

building[year_of_construction]
optional

Year building was completed.

Validations:

  • Must be a String

building[address]
optional

Street address of building.

Validations:

  • Must be a String

building[city]
optional

City of address.

Validations:

  • Must be a String

building[state]
optional

State of address.

Validations:

  • Must be a String

building[zip_code]
optional

Zipcode of address.

Validations:

  • Must be a String

building[assessment_type]
optional

Test if you are not doing a formal audit or Real if you are.

Validations:

  • Must be a String

building[notes]
optional

Any kind of additional text.

Validations:

  • Must be a String


GET /api/v2/preview_buildings/:id/validate
Validates a building with given ID. Response for a successful request is a description of the validation.

Supported Formats

json

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.
400 Building has no blocks.
400 The building has blocks without a use type.
400 The building has blocks without a roof.
400 The building has blocks without a floor.
400 The building has blocks without walls.
400 The building has blocks without wwr
400 The building has blocks without a percentage footprint
400 The building has blocks without fixtures
400 The building has blocks without fixture values
400 The building has blocks with fixture values out of range
400 The building has blocks without hvac systems
400 If the validation message is not one of the above, you might get a dump of the validation hash as a fall back for an unexpected condition. If this happens please report it to the help desk so that we can help you determine the actual cause of the validation failure.

Params

Param name Description
token
required

Identifies the user

Validations:

  • Must be a String


GET /api/v2/preview_buildings/:id/report
Retrieve the individual score values as well as a link to the PDF report for a single Preview Building, specified by the ID parameter.

Supported Formats

json

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.

Params

Param name Description
token
required

Identifies the user

Validations:

  • Must be a String


PUT /api/v2/preview_buildings/:id/edit_mode
Update building account with given ID. Sets the building status type back to "Editing". If the building status type is already "Editing", no change is made. Nothing is returned.

Supported Formats

json

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) {"token":"1234TokenGoesHere"}

Params

Param name Description
token
required

Identifies the user

Validations:

  • Must be a String


PUT /api/v2/preview_buildings/:id/verify
Update building with the given ID. Sets the attribute certainty status to "Verified" or "Do not know". Response for a successful request is a 204 no content status code.

Supported Formats

json

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.
400 Building is not in edit mode. Place building in edit mode first before editing
400 The attribute <attribute> is not a valid attribute, please check and try again
400 The attribute <attribute> which ends with ! can not be changed with the verify method.
400 The attribute <attribute> can not be changed with the verify method. To change this attribute you must delete the building and start again.
400 Can't update <attribute> because building has no <attribute>.

Examples

(json) {
    "token":"1234TokenGoesHere",
    "building": {
      "block_id":"4950",
      "floor:floor_type":"true"
    }
  }

Params

Param name Description
token
required

Identifies the user

Validations:

  • Must be a String

building
required

describes the building

Validations:

  • Must be a Hash

building[block_id]
required

Identifies the block to use

Validations:

  • Must be a String

building[attribute]
required

The attribute to update, i.e floor:floor_type

Validations:

  • Must be a String


PUT /api/v2/preview_buildings/:id/revert
Update building with the given ID. Sets the attribute certainty status from "Edited" or "Do not know". Response for a successful request is a 204 no content status code.

Supported Formats

json

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.
400 Building is not in edit mode. Place building in edit mode first before editing
400 The attribute <attribute> is not a valid attribute, please check and try again
400 The attribute <attribute> which ends with ! can not be changed with the verify method.
400 The attribute <attribute> can not be changed with the verify method. To change this attribute you must delete the building and start again.
400 Can't update <attribute> because building has no <attribute>.

Examples

(json) {
    "token":"1234TokenGoesHere",
    "building": {
      "block_id":"4950",
      "floor:floor_type":"true"
    }
  }

Params

Param name Description
token
required

Identifies the user

Validations:

  • Must be a String

building
required

describes the building

Validations:

  • Must be a Hash

building[block_id]
required

Identifies the block to use

Validations:

  • Must be a String

building[attribute]
required

The attribute to update, i.e floor:floor_type

Validations:

  • Must be a String