Blocks
Energy Asset - Block

Services relating to blocks of the Energy Asset Tool

Supported Formats

json, xml
>>>

GET /api/v1/blocks/:id
Retrieve the block with the specific ID.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
404 Unsupported operation
500 Unspecified error on server.

Examples

{"building_id":1,"building_use_type_id":2,"color":"blue","created_at":"2013-09-30T18:14:19Z","dimension_1":10.0,"dimension_10":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,"floor_id":null,"floor_to_ceiling_height":10.0,"floor_to_floor_height":10.0,"has_drop_ceiling":false,"has_timer_controls":false,"id":2,"is_above_ground":true,"name":"Block 1","number_of_bg_floors":1,"number_of_floors":1,"operating_season_id":null,"operation_id":null,"orientation":10.0,"percent_footprint":null,"perimeter_zone_depth":null,"position":"10","roof_id":null,"selected":false,"shape_id":1,"sides":"4","skylight_id":null,"skylight_layout_id":null,"ui_id":"10","updated_at":"2013-09-30T18:14:19Z","uses_percent_served":false,"vertices":"10","zone_layout_id":null}
<block>
<building-id type="integer">9</building-id>
<building-use-type-id type="integer">21</building-use-type-id>
<color>128300</color>
<created-at type="datetime">2013-06-28T21:09:48Z</created-at>
<dimension-1 type="float">100.0</dimension-1>
<dimension-10 type="float" nil="true"/>
<dimension-2 type="float">100.0</dimension-2>
<dimension-3 type="float" nil="true"/>
<dimension-4 type="float" nil="true"/>
<dimension-5 type="float" nil="true"/>
<dimension-6 type="float" nil="true"/>
<dimension-7 type="float" nil="true"/>
<dimension-8 type="float" nil="true"/>
<dimension-9 type="float" nil="true"/>
<floor-id type="integer">12</floor-id>
<floor-to-ceiling-height type="float">9.0</floor-to-ceiling-height>
<floor-to-floor-height type="float">12.0</floor-to-floor-height>
<has-drop-ceiling type="boolean" nil="true"/>
<has-timer-controls type="boolean" nil="true"/>
<id type="integer">14</id>
<is-above-ground type="boolean">true</is-above-ground>
<name>blk1</name>
<number-of-bg-floors type="integer">0</number-of-bg-floors>
<number-of-floors type="integer">4</number-of-floors>
<operating-season-id type="integer" nil="true"/>
<operation-id type="integer" nil="true"/>
<orientation type="float">0.0</orientation>
<percent-footprint type="float" nil="true"/>
<perimeter-zone-depth type="float" nil="true"/>
<position>{"x":7.816861152648926,"y":24,"z":5}</position>
<roof-id type="integer">12</roof-id>
<selected type="boolean" nil="true"/>
<shape-id type="integer">1</shape-id>
<sides nil="true"/>
<skylight-id type="integer" nil="true"/>
<skylight-layout-id type="integer" nil="true"/>
<ui-id/>
<updated-at type="datetime">2013-10-23T19:42:55Z</updated-at>
<uses-percent-served type="boolean">false</uses-percent-served>
<vertices>
[[{"x":57.81686019897461,"y":0,"z":-45},{"x":-42.18313980102539,"y":0,"z":-45},{"x":-42.18313980102539,"y":0,"z":55},{"x":57.81686019897461,"y":0,"z":55}],[{"x":57.81686019897461,"y":12,"z":-45},{"x":-42.18313980102539,"y":12,"z":-45},{"x":-42.18313980102539,"y":12,"z":55},{"x":57.81686019897461,"y":12,"z":55}],[{"x":57.81686019897461,"y":24,"z":-45},{"x":-42.18313980102539,"y":24,"z":-45},{"x":-42.18313980102539,"y":24,"z":55},{"x":57.81686019897461,"y":24,"z":55}],[{"x":57.81686019897461,"y":36,"z":-45},{"x":-42.18313980102539,"y":36,"z":-45},{"x":-42.18313980102539,"y":36,"z":55},{"x":57.81686019897461,"y":36,"z":55}],[{"x":57.81686019897461,"y":48,"z":-45},{"x":-42.18313980102539,"y":48,"z":-45},{"x":-42.18313980102539,"y":48,"z":55},{"x":57.81686019897461,"y":48,"z":55}]]
</vertices>
<zone-layout-id type="integer" nil="true"/>
</block>
>>>

GET /api/v1/buildings/:building_id/blocks
Retrieve all blocks belonging to the building.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
404 Unsupported operation
500 Unspecified error on server.
>>>

POST /api/v1/buildings/:building_id/blocks
Create a new block. This will associate the block with the building and return a Block object with unique ID assigned.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
404 Unsupported operation
500 Unspecified error on server.

Examples

Successful Request: {"name":"Block 1","shape_id":1,"dimension_1":"10","dimension_2":"10","dimension_3":"10","dimension_4":"10","dimension_5":"10","dimension_6":"10","dimension_7":"10","dimension_8":"10","dimension_9":"10","dimension_10":"10","number_of_floors":1,"floor_to_floor_height":"10","has_drop_ceiling":false,"orientation":"10","is_above_ground":true,"color":"blue","vertices":"10","position":"10","selected":"10","floor_to_ceiling_height":"10","ui_id":"10","sides":"4","number_of_bg_floors":1,"uses_percent_served":"10","has_timer_controls":false,"building_use_type_id":2,"building_id":1}
Bad Request: {"name":"Block 1","shape_id":1,"dimension_1":"10","dimension_2":"10","dimension_3":"10","dimension_4":"10","dimension_5":"10","dimension_6":"10","dimension_7":"10","dimension_8":"10","dimension_9":"10","dimension_10":"10","number_of_floors":1,"floor_to_floor_height":"10","has_drop_ceiling":false,"orientation":"10","is_above_ground":true,"color":"blue","vertices":"10","position":"10","selected":"10","floor_to_ceiling_height":"10","ui_id":"10","sides":"4","number_of_bg_floors":1,"uses_percent_served":"10","has_timer_controls":false,"building_use_type_id":2,"roof_id":1234,"building_id":1}
Response with errors: {"errors":{"roof_id":["does not exist"],"roof":["does not exist"]}}
(xml):
<block>
  <name>Block 4</name>
  <shape-id type="integer">1</shape-id>
  <dimension-1>10</dimension-1>
  <dimension-2>10</dimension-2>
  <dimension-3>10</dimension-3>
  <dimension-4>10</dimension-4>
  <dimension-5>10</dimension-5>
  <dimension-6>10</dimension-6>
  <dimension-7>10</dimension-7>
  <dimension-8>10</dimension-8>
  <dimension-9>10</dimension-9>
  <dimension-10>10</dimension-10>
  <number-of-floors type="integer">1</number-of-floors>
  <floor-to-floor-height>10</floor-to-floor-height>
  <has-drop-ceiling type="boolean">false</has-drop-ceiling>
  <orientation>10</orientation>
  <is-above-ground type="boolean">true</is-above-ground>
  <color>blue</color>
  <vertices>
    [[{"x":57.81686019897461,"y":0,"z":-45},{"x":-42.18313980102539,"y":0,"z":-45},{"x":-42.18313980102539,"y":0,"z":55},{"x":57.81686019897461,"y":0,"z":55}],[{"x":57.81686019897461,"y":12,"z":-45},{"x":-42.18313980102539,"y":12,"z":-45},{"x":-42.18313980102539,"y":12,"z":55},{"x":57.81686019897461,"y":12,"z":55}],[{"x":57.81686019897461,"y":24,"z":-45},{"x":-42.18313980102539,"y":24,"z":-45},{"x":-42.18313980102539,"y":24,"z":55},{"x":57.81686019897461,"y":24,"z":55}],[{"x":57.81686019897461,"y":36,"z":-45},{"x":-42.18313980102539,"y":36,"z":-45},{"x":-42.18313980102539,"y":36,"z":55},{"x":57.81686019897461,"y":36,"z":55}],[{"x":57.81686019897461,"y":48,"z":-45},{"x":-42.18313980102539,"y":48,"z":-45},{"x":-42.18313980102539,"y":48,"z":55},{"x":57.81686019897461,"y":48,"z":55}]]
  </vertices>
  <position>10</position>
  <selected>10</selected>
  <floor-to-ceiling-height>10</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>10</uses-percent-served>
  <has-timer-controls type="boolean">false</has-timer-controls>
  <building-id type="integer">1</building-id>
  <building-use-type-id type="integer">2</building-use-type-id>
</block>

Params

Param name Description
shape_id
required

ID for the shape of this block.

Validations:

  • Must be a Integer
dimension_1
required

Length of dimension 1 (in feet).

Validations:

  • Must be a Float
dimension_2
required

Length of dimension 2 (in feet).

Validations:

  • Must be a Float
dimension_3
optional

Length of dimension 3 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
dimension_4
optional

Length of dimension 4 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
dimension_5
optional

Length of dimension 5 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
dimension_6
optional

Length of dimension 6 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
dimension_7
optional

Length of dimension 7 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
dimension_8
optional

Length of dimension 8 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
number_of_floors
required

Number of floors in block (1-500).

Validations:

  • Must be a Integer
floor_to_floor_height
required

Average floor-to-floor height (in feet). Must be greater than 9.

Validations:

  • Must be a Float
floor_to_ceiling_height
required

Average floor-to-ceiling height (in feet). Must be greater than 0.

Validations:

  • Must be a Float
has_drop_ceiling
optional

True if block has a drop ceiling, false otherwise

Validations:

  • Must be one of: true, false.
orientation
required

Degrees from North of block (0-359).

Validations:

  • Must be a Float
is_above_ground
required

True if above ground, false if below ground.

Validations:

  • Must be one of: true, false.
vertices
required

x,y coordinates for the block vertices.

Validations:

  • Must be a String
position
required

x,y coordinates of block position.

Validations:

  • Must be a String
number_of_bg_floors
optional

DEPRECATED - use number_of_floors.

Validations:

  • Must be one of: .
uses_percent_served
optional

True of uses percent served, false otherwise.

Validations:

  • Must be one of: true, false.
has_timer_controls
optional

True if block has timer controls, false otherwise.

Validations:

  • Must be one of: true, false.
skylight_id
optional

ID of Skylight assigned to block.

Validations:

  • Must be a Integer
skylight_layout_id
optional

ID of Skylight layout.

Validations:

  • Must be a Integer
percent_footprint
optional

Skylight percent of roof area (usually 3%-5%).

Validations:

  • Must be a Float
roof_id
optional

ID of roof assigned to block.

Validations:

  • Must be a Integer
floor_id
optional

ID of floor assigned to block.

Validations:

  • Must be a Integer
operation_id
optional

ID of operation assigned to block.

Validations:

  • Must be a Integer
building_use_type_id
optional

ID of building use type assigned to block.

Validations:

  • Must be a Integer
perimeter_zone_depth
optional

Perimeter zone depth.

Validations:

  • Must be a Float
zone_layout_id
optional

ID of zone layout.

Validations:

  • Must be a Integer
operating_season_id
optional

ID of operating season.

Validations:

  • Must be a Integer
low_flow_faucets
optional

True of low flow faucets used, false otherwise.

Validations:

  • Must be one of: true, false.
co_sensors
optional

True if CO Sensors, false otherwise.

Validations:

  • Must be one of: true, false.
>>>

PUT /api/v1/blocks/:id
Update an existing block. Nothing is returned. NOTE: A block's shape can NOT be modified once it has been created. If the wrong shape has been selected the block must be deleted and recreated.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
404 Unsupported operation
500 Unspecified error on server.
422 A block's shape_id can NOT be modified.

Params

Param name Description
shape_id
required

ID for the shape of this block.

Validations:

  • Must be a Integer
dimension_1
required

Length of dimension 1 (in feet).

Validations:

  • Must be a Float
dimension_2
required

Length of dimension 2 (in feet).

Validations:

  • Must be a Float
dimension_3
optional

Length of dimension 3 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
dimension_4
optional

Length of dimension 4 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
dimension_5
optional

Length of dimension 5 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
dimension_6
optional

Length of dimension 6 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
dimension_7
optional

Length of dimension 7 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
dimension_8
optional

Length of dimension 8 (in feet). Depends on shape if required.

Validations:

  • Must be a Float
number_of_floors
required

Number of floors in block (1-500).

Validations:

  • Must be a Integer
floor_to_floor_height
required

Average floor-to-floor height (in feet). Must be greater than 9.

Validations:

  • Must be a Float
floor_to_ceiling_height
required

Average floor-to-ceiling height (in feet). Must be greater than 0.

Validations:

  • Must be a Float
has_drop_ceiling
optional

True if block has a drop ceiling, false otherwise

Validations:

  • Must be one of: true, false.
orientation
required

Degrees from North of block (0-359).

Validations:

  • Must be a Float
is_above_ground
required

True if above ground, false if below ground.

Validations:

  • Must be one of: true, false.
vertices
required

x,y coordinates for the block vertices.

Validations:

  • Must be a String
position
required

x,y coordinates of block position.

Validations:

  • Must be a String
number_of_bg_floors
optional

DEPRECATED - use number_of_floors.

Validations:

  • Must be one of: .
uses_percent_served
optional

True of uses percent served, false otherwise.

Validations:

  • Must be one of: true, false.
has_timer_controls
optional

True if block has timer controls, false otherwise.

Validations:

  • Must be one of: true, false.
skylight_id
optional

ID of Skylight assigned to block.

Validations:

  • Must be a Integer
skylight_layout_id
optional

ID of Skylight layout.

Validations:

  • Must be a Integer
percent_footprint
optional

Skylight percent of roof area (usually 3%-5%).

Validations:

  • Must be a Float
roof_id
optional

ID of roof assigned to block.

Validations:

  • Must be a Integer
floor_id
optional

ID of floor assigned to block.

Validations:

  • Must be a Integer
operation_id
optional

ID of operation assigned to block.

Validations:

  • Must be a Integer
building_use_type_id
optional

ID of building use type assigned to block.

Validations:

  • Must be a Integer
perimeter_zone_depth
optional

Perimeter zone depth.

Validations:

  • Must be a Float
zone_layout_id
optional

ID of zone layout.

Validations:

  • Must be a Integer
operating_season_id
optional

ID of operating season.

Validations:

  • Must be a Integer
low_flow_faucets
optional

True of low flow faucets used, false otherwise.

Validations:

  • Must be one of: true, false.
co_sensors
optional

True if CO Sensors, false otherwise.

Validations:

  • Must be one of: true, false.
>>>

DELETE /api/v1/blocks/:id
Delete the block and disassociate it from the building. Nothing is returned.

Supported Formats

json, xml

Errors

Code Description
401 Unauthorized - ensure token is being passed with each service call.
404 Unsupported operation
500 Unspecified error on server.