Services relating to surfaces of the Energy Asset Tool

Supported Formats

json, xml

GET /api/v1/surfaces/:id
Retrieve the surface 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.

GET /api/v1/blocks/:block_id/surfaces
Retrieve all surfaces belonging to the block.

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

{"block_id"=>2, "daylight_controls"=>true, "edge_fins_only"=>true, "edge_offset"=>8.8, "fin_depth"=>5.5, "fin_distance_between"=>1.1, "height"=>100.0, "id"=>1, "light_shelf_distance_from_top"=>2.2, "light_shelf_ext_protrusion"=>3.3, "light_shelf_int_protrusion"=>4.4, "name"=>"Surface 1", "number_of_windows"=>11, "overhang_depth"=>1.1, "overhang_height_above_window"=>1.2, "shading_type_id"=>1, "sill_height"=>2.2, "vertices"=>"[{"x":-50,"z":50,"y":12},{"x":-50,"z":-50,"y":12},{"x":-50,"z":-50,"y":0},{"x":-50,"z":50,"y":0}]", "wall_id"=>1, "width"=>100.0, "window_height"=>10.0, "window_id"=>nil, "window_layout_id"=>1, "window_wall_ratio"=>0.8, "window_width"=>10.0}
<surface>
<block-id type="integer">3</block-id>
<edge-fins-only type="boolean">false</edge-fins-only>
<edge-offset type="float" nil="true"/>
<fin-depth type="float" nil="true"/>
<fin-distance-between type="float" nil="true"/>
<height type="float">12.0</height>
<id type="integer">11</id>
<light-shelf-distance-from-top type="float" nil="true"/>
<light-shelf-ext-protrusion type="float" nil="true"/>
<light-shelf-int-protrusion type="float" nil="true"/>
<name type="string">Surface 1</name>
<number-of-windows type="integer">0</number-of-windows>
<overhang-depth type="float" nil="true"/>
<overhang-height-above-window type="float" nil="true"/>
<shading-type-id type="integer">1</shading-type-id>
<sill-height type="float" nil="true"/>
<vertices>
[{"x":7.071067810058594,"y":24,"z":-24.041629791259766},{"x":24.041629791259766,"y":24,"z":-7.071067810058594},{"x":24.041629791259766,"y":12,"z":-7.071067810058594},{"x":7.071067810058594,"y":12,"z":-24.041629791259766}]
</vertices>
<wall-id type="integer">2</wall-id>
<width type="float">24.0</width>
<window-height type="float" nil="true"/>
<window-id type="integer">2</window-id>
<window-layout-id type="integer">1</window-layout-id>
<window-wall-ratio type="float">0.23999999463558197</window-wall-ratio>
<window-width type="float" nil="true"/>
<window-height type="integer">10</window-height>
<daylight-controls type="boolean">true</daylight-controls>
</surface>

POST /api/v1/blocks/:block_id/surfaces
Create a new surface. This will associate the surface with the block and return a Surface 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

request:  {"name":"Surface 1","vertices":"[{"x":-50,"z":50,"y":12},{"x":-50,"z":-50,"y":12},{"x":-50,"z":-50,"y":0},{"x":-50,"z":50,"y":0}]","window_wall_ratio":0.8,"window_layout_id":1,"shading_type_id":1,"overhang_height_above_window":1.2,"overhang_depth":1.1,"light_shelf_distance_from_top":2.2,"light_shelf_ext_protrusion":3.3,"light_shelf_int_protrusion":4.4,"fin_depth":5.5,"fin_distance_between":1.1,"edge_offset":8.8,"sill_height":2.2,"number_of_windows":11,"width":100,"height":100,"window_width":10,"window_height":10,"block":{"building_id":1,"building_use_type_id":2,"color":"blue","created_at":"2013-07-18T16:04:46Z","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-07-18T16:04:46Z","uses_percent_served":false,"vertices":"10","zone_layout_id":null},"wall":{"building_id":1,"created_at":"2013-07-18T16:04:46Z","id":1,"updated_at":"2013-07-18T16:04:46Z","wall_insulation_thickness":3.3,"wall_r_value":17.0,"wall_type_id":3,"wall_u_factor":0.23}}
<surface>
  <name type="string">Surface 5</name>
  <vertices>[{"x":-50,"z":50,"y":12},{"x":-50,"z":-50,"y":12},{"x":-50,"z":-50,"y":0},{"x":-50,"z":50,"y":0}]</vertices>
  <window-wall-ratio type="float">0.8</window-wall-ratio>
  <window-layout-id type="integer">1</window-layout-id>
  <shading-type-id type="integer">1</shading-type-id>
  <overhang-height-above-window type="float">1.2</overhang-height-above-window>
  <overhang-depth type="float">1.1</overhang-depth>
  <light-shelf-distance-from-top type="float">2.2</light-shelf-distance-from-top>
  <light-shelf-ext-protrusion type="float">3.3</light-shelf-ext-protrusion>
  <light-shelf-int-protrusion type="float">4.4</light-shelf-int-protrusion>
  <fin-depth type="float">5.5</fin-depth>
  <edge-fins-only>f</edge-fins-only>
  <fin-distance-between type="float">1.1</fin-distance-between>
  <edge-offset type="float">8.8</edge-offset>
  <sill-height type="float">2.2</sill-height>
  <number-of-windows type="integer">11</number-of-windows>
  <width type="integer">100</width>
  <height type="integer">100</height>
  <window-width type="integer">10</window-width>
  <window-height type="integer">10</window-height>
  <block>
    <building-id type="integer">1</building-id>
    <building-use-type-id type="integer">2</building-use-type-id>
    <color>blue</color>
    <created-at type="datetime">2014-03-17T19:50:04Z</created-at>
    <dimension-1 type="float">10.0</dimension-1>
    <dimension-10 type="float">10.0</dimension-10>
    <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>
    <floor-id type="integer" nil="true"/>
    <floor-to-ceiling-height type="float">10.0</floor-to-ceiling-height>
    <floor-to-floor-height type="float">10.0</floor-to-floor-height>
    <has-drop-ceiling type="boolean">false</has-drop-ceiling>
    <has-timer-controls type="boolean">false</has-timer-controls>
    <id type="integer">2</id>
    <is-above-ground type="boolean">true</is-above-ground>
    <name>Block 2</name>
    <number-of-bg-floors type="integer">1</number-of-bg-floors>
    <number-of-floors type="integer">1</number-of-floors>
    <operating-season-id type="integer" nil="true"/>
    <operation-id type="integer" nil="true"/>
    <orientation type="float">10.0</orientation>
    <percent-footprint type="float" nil="true"/>
    <perimeter-zone-depth type="float" nil="true"/>
    <position>10</position>
    <roof-id type="integer" nil="true"/>
    <selected type="boolean">false</selected>
    <shape-id type="integer">1</shape-id>
    <sides>4</sides>
    <skylight-id type="integer" nil="true"/>
    <skylight-layout-id type="integer" nil="true"/>
    <ui-id>10</ui-id>
    <updated-at type="datetime">2014-03-17T19:50:04Z</updated-at>
    <uses-percent-served type="boolean">false</uses-percent-served>
    <vertices>10</vertices>
    <zone-layout-id type="integer" nil="true"/>
  </block>
  <wall>
    <building-id type="integer">1</building-id>
    <created-at type="datetime">2014-03-17T19:50:04Z</created-at>
    <id type="integer">1</id>
    <updated-at type="datetime">2014-03-17T19:50:04Z</updated-at>
    <wall-insulation-thickness type="float">3.3</wall-insulation-thickness>
    <wall-r-value type="float">17.0</wall-r-value>
    <wall-type-id type="integer">3</wall-type-id>
    <wall-u-factor type="float">0.23</wall-u-factor>
  </wall>
</surface>

Params

Param name Description
window_layout_id
required

Window Layout ID. Specifies type of window layout to create. Must be greater than or equal to 0

Validations:

  • Must be a Integer

wall_id
optional

ID of wall assigned to this surface.

Validations:

  • Must be a Integer

window_id
optional

ID of window assigned to this surface.

Validations:

  • Must be a Integer

window_wall_ratio
optional

Window-to-wall ratio. Must be less than 0.95

Validations:

  • Must be a Float

edge_offset
optional

Edge Offset. Must be greater than or equal to 0

Validations:

  • Must be a Float

sill_height
optional

Sill Height. Must be between 0-6

Validations:

  • Must be a Float

shading_type_id
optional

Shading Type ID. Must be greater than or equal to 0

Validations:

  • Must be a Integer

number_of_windows
optional

Number of windows. Must be greater than or equal to 1

Validations:

  • Must be a Integer

width
optional

Width. Must be greater than or equal to 0

Validations:

  • Must be a Float

height
optional

Height. Must be greater than or equal to 0

Validations:

  • Must be a Float

overhang_height_above_window
optional

Overhang Height above window. Must be between 0-2

Validations:

  • Must be a Float

overhang_depth
optional

Overhang depth. Must be greater than or equal to 0

Validations:

  • Must be a Float

fin_depth
optional

Fin Depth. Must be greater than or equal to 0

Validations:

  • Must be a Float

fin_distance_between
optional

Distance between fins. Must be greater than or equal to 0

Validations:

  • Must be a Float

light_shelf_distance_from_top
optional

Light shelf distance from top. Must be greater than or equal to 0

Validations:

  • Must be a Float

light_shelf_ext_protrusion
optional

Light shelf exterior protrusion. Must be greater than or equal to 0

Validations:

  • Must be a Float

light_shelf_int_protrusion
optional

Light shelf internal protrusion. Must be greater than or equal to 0

Validations:

  • Must be a Float

window_width
optional

Window width. Must be greater than or equal to 0

Validations:

  • Must be a Float

window_height
optional

Window height. Must be greater than or equal to 0

Validations:

  • Must be a Float

daylight_controls
optional

True if daylight controls are used for this surface, false otherwise

Validations:

  • Must be one of: true, false.


PUT /api/v1/surfaces/:id
Update an existing surface. 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.

Params

Param name Description
window_layout_id
required

Window Layout ID. Specifies type of window layout to create. Must be greater than or equal to 0

Validations:

  • Must be a Integer

wall_id
optional

ID of wall assigned to this surface.

Validations:

  • Must be a Integer

window_id
optional

ID of window assigned to this surface.

Validations:

  • Must be a Integer

window_wall_ratio
optional

Window-to-wall ratio. Must be less than 0.95

Validations:

  • Must be a Float

edge_offset
optional

Edge Offset. Must be greater than or equal to 0

Validations:

  • Must be a Float

sill_height
optional

Sill Height. Must be between 0-6

Validations:

  • Must be a Float

shading_type_id
optional

Shading Type ID. Must be greater than or equal to 0

Validations:

  • Must be a Integer

number_of_windows
optional

Number of windows. Must be greater than or equal to 1

Validations:

  • Must be a Integer

width
optional

Width. Must be greater than or equal to 0

Validations:

  • Must be a Float

height
optional

Height. Must be greater than or equal to 0

Validations:

  • Must be a Float

overhang_height_above_window
optional

Overhang Height above window. Must be between 0-2

Validations:

  • Must be a Float

overhang_depth
optional

Overhang depth. Must be greater than or equal to 0

Validations:

  • Must be a Float

fin_depth
optional

Fin Depth. Must be greater than or equal to 0

Validations:

  • Must be a Float

fin_distance_between
optional

Distance between fins. Must be greater than or equal to 0

Validations:

  • Must be a Float

light_shelf_distance_from_top
optional

Light shelf distance from top. Must be greater than or equal to 0

Validations:

  • Must be a Float

light_shelf_ext_protrusion
optional

Light shelf exterior protrusion. Must be greater than or equal to 0

Validations:

  • Must be a Float

light_shelf_int_protrusion
optional

Light shelf internal protrusion. Must be greater than or equal to 0

Validations:

  • Must be a Float

window_width
optional

Window width. Must be greater than or equal to 0

Validations:

  • Must be a Float

window_height
optional

Window height. Must be greater than or equal to 0

Validations:

  • Must be a Float

daylight_controls
optional

True if daylight controls are used for this surface, false otherwise

Validations:

  • Must be one of: true, false.


DELETE /api/v1/surfaces/:id
Delete the surface and disassociate it from the block. 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.