What changes were made in the August 2023 web services 21.0 release?

  • Updated

The 21.0 Beta release was June 26, 2023. The Live release was August 28, 2023. 

Enhancements for the 21.0 Live Release  

  • Updates to the "Vehicle Dealership" property use type (in preparation for the release of a new U.S. 1-100 scoring model in Portfolio Manager).
    • The current property use type "Automobile Dealership" will be renamed to "Vehicle Dealership."
      • Updates to existing web service metric names used in the Get-Use-Detail-Metric web service will be as follows:
        • vehicleDealershipComputerDensity
        • vehicleDealershipGrossFloorArea
        • vehicleDealershipNumberOfComputers
        • vehicleDealershipNumberOfWorkersOnMainShift
        • vehicleDealershipWeeklyOperatingHours
        • vehicleDealershipWorkerDensity
        • temporaryDataFlagVehicleDealership
        • designVehicleDealershipGrossFloorArea
    • The "primaryFunction" element of the property.xsd schema will now expect "Vehicle Dealership" instead of "Automobile Dealership."
    • A new use detail will be introduced for the "Vehicle Dealership" property use.
      • Average Number of Vehicles in Inventory
        • Web services name: averageNumberOfVehiclesInInventory
    • Existing "Vehicle Dealership" property uses will be backfilled with default values for the corresponding use details:
      • Number of Workers on Main Shift
        • Backfill based on a default density of 1.7 workers for every 1,000 square feet of gross floor area entered.
      • Average Number of Vehicles in Inventory
        • Backfill based on a default density of 7.6 vehicles for every 1,000 square feet of gross floor area entered.
      • Percent That Can Be Heated
        • Backfill with a default value of "100."
      • Percent That Can Be Cooled
        • Backfill with a default value of "100."
    • The services noted below will be impacted by these use detail changes:
      • POST   /property/(propertyId)/propertyUse
      • GET   /propertyUse/(propertyUseId)
      • POST   /propertyUse/(propertyUseId)/useDetails
      • GET   /propertyUse/(propertyUseId)/useDetailsRevisions
      • PUT/GET   /useDetails/(useDetailsId)
      • GET   /idHierarchy/useDetails/(useDetailId)
      • PUT/GET   /property/(propertyId)/design
      • POST   /targetFinder
    • New Use Detail Metrics will be available via the Get-Use-Details-Metrics web service:
      • vehicleDealershipAverageNumberOfVehiclesInInventory
      • vehicleDealershipVehicleDensity
    • As part of the Live Release on August 28, 2023, the new "Score Preview" metric will be available for Vehicle Dealerships, and will include new adjustments for Parking Lots and Parking Garages (see below). For more information on the "Preview Score" functionality, see What is the Score Preview metric?
      • For API users, this metric is available via the Get Metrics API call (web services name: scorePreview). Please note that this metric will return a value of "N/A" for any Canadian property or for any U.S. property for which the system-calculated property type is not "Vehicle Dealership."
      • The "Score Preview" metric will not be available during the Beta period.

 

  • Updates to the Bank Branch score model for Canadian buildings
    • Score Updates
      • U.S. scores will remain unchanged.
      • Canadian scores for properties containing a "Bank Branch" property use type will be updated.
    • No new or updated Use Details.
    • No new metrics available.

 

  • Updates to the Worship Facility score model for Canadian buildings
    • Score Updates
      • U.S. scores will remain unchanged.
      • New Canadian scores will be available for properties containing a "Worship Facility" property use type. These properties will be updated.
    • New Use Detail
      • Ceiling Height
        • Web services name: ceilingHeight
    • Existing "Worship Facility" property uses will be backfilled with default values.
      • Ceiling Height
        • Backfill with default value of 20 feet.
    • The services noted below will be impacted by these use detail changes.
      • POST   /property/(propertyId)/propertyUse
      • GET   /propertyUse/(propertyUseId)
      • POST   /propertyUse/(propertyUseId)/useDetails
      • GET   /propertyUse/(propertyUseId)/useDetailsRevisions
      • PUT/GET   /useDetails/(useDetailsId)
      • GET   /idHierarchy/useDetails/(useDetailId)
      • PUT/GET   /property/(propertyId)/design
      • POST   /targetFinder

 

  • Updates to the Mailing Center/Post Office score model for Canadian buildings
    • Score Updates
      • U.S. scores will remain unchanged (not eligible to receive a 1-100 score).
      • New Canadian scores will be available for properties containing a "Worship Facility" property use type. These properties will be updated.
    • New Use Details
      • Delivery Facility
        • Web services name: deliveryFacility
      • Number of Letters and Packages per Year
        • Web services name: numberOfLettersPackagesPerYear
    • Existing "Mailing Center/Post Office" property uses will be backfilled with default values.
      • Weekly Operating Hours
        • Backfill with default value of "80."
      • Number of Workers on Main Shift
        • Backfill based on a default density of 2 workers for every 1,000 square feet of gross floor area entered.
      • Delivery Facility
        • Backfill with a default value of "Yes."
      • Number of Letters and Packages Per Year
        • Backfill based on a default density of 250,000 letters and packages per year for every 1,000 square feet of gross floor area entered.
      • Percent That Can Be Heated
        • Backfill with a default value of "100."
      • Percent That Can Be Cooled
        • Backfill with a default value of "100."
    • The services noted below will be impacted by these use detail changes.
      • POST   /property/(propertyId)/propertyUse
      • GET   /propertyUse/(propertyUseId)
      • POST   /propertyUse/(propertyUseId)/useDetails
      • GET   /propertyUse/(propertyUseId)/useDetailsRevisions
      • PUT/GET   /useDetails/(useDetailsId)
      • GET   /idHierarchy/useDetails/(useDetailId)
      • PUT/GET   /property/(propertyId)/design
      • POST   /targetFinder

 

  • Adjustment updates for Parking Lots and Parking Garages
    • Will apply to all Canadian properties for which a Parking Lot or Parking Garage use type has been defined.
    • Will not apply to U.S. properties until a later time (TBD). The existing Parking adjustments will apply to U.S. buildings until that time. However, starting with the 21.0 Live release on August 28, 2023, these new adjustments will be used in generating the "Preview Score" metric for "Vehicle Dealership" properties (see above).

 

  • New TEST-only API to generate sample properties in the TEST environment
    • Will facilitate use of the TEST environment for API users who do not anticipate creating customer accounts/properties as part of their Portfolio Manager API integration.
    • Available sample properties will draw from those currently available within the Portfolio Manager front-end interface.
    • API users will be able to specify how many test properties they wish to create, up to a specified maximum number (TBD).
    • More details will be provided as part of the June 28, 2023 Beta release webinar.

 

  • Annual updates to factors and reference data
    • EPA will be using the August release to implement annual updates to key factors and reference data underlying Portfolio Manager, which may include some or all of the following:
      • Thermal conversion factors
      • GHG emissions factors for plant-specific and regional electricity based on new eGRID data (www.epa.gov/egrid)
      • All other emissions factors
      • Default fuel cost data (as used in Target Finder and Design services)
      • Default fuel mix (as used in Target Finder and Design services)
      • Weather station mapping
      • Source energy conversion factors
      • National Median EUI values
    • All updates will be documented in the corresponding Technical Reference Documents, available at https://portfoliomanager.energystar.gov/pm/help. 


Planned enhancements that will not be included in the 21.0 Beta release on June 26, 2023

These updates will not be included in the 21.0 Beta release on June 26, 2023. If they are available in time, they will be included in the 21.0 Live release on August 28, 2023. Otherwise, they will be released later in 2023, with further notification provided to API users as release dates are defined.
 

  • New web services for the following user interface functionalities:
    • Custom Property Use Details and Custom Intensity Metrics
      • Portfolio Manager users will be able to define customized intensity metrics (e.g., “[XX] per [YY]”) for each property, based on the performance indicators that are most meaningful to their organization.
      • Users will be able to define up to two new “Custom Property Use Details” that are not already captured within the Portfolio Manager use details for a given property use.
      • Users will be able to define up to three new “Custom Intensity Metrics” by selecting the appropriate numerator and denominator for the intensity metric, according to the following formula:
        • [Choose any Energy/Water/GHG metric available in Portfolio Manager] per [Choose an existing or custom Property Use Detail]. 
        • Example Custom Intensity Metrics might include:
          • Site Energy Use per Student
          • Water Use per Hotel Room Night Sold
          • GHG Emissions per Car Manufactured
          • Weather Normalized Source Energy per Worker on Main Shift
          • Indirect GHG Emissions per Hospital Bed
      • Further API documentation regarding this new functionality will be provided as soon as it is available.
    • Responses to Portfolio Manager Data Requests
      • Building upon the new Custom Reporting functionality released as part of the web services 20.0 enhancement in February 2023, further API calls will be developed to allow web service users to respond to published Data Requests.
        • For example, state/local jurisdictions with benchmarking ordinances typically publish a Portfolio Manager Data Request as the mechanism through which covered properties must report their benchmarking results.
        • Currently, third-party service providers cannot release/submit benchmarking results to a Data Request via web services – even if they are managing all other aspects of the benchmarking process via web services. Instead, they must use the front-end user interface.
        • This enhancement will broaden the scope of services that providers can offer via the web services API.
      • It is expected that these new web services will be released directly into the LIVE API, without a prior Beta period. Further documentation will be provided closer to release.
  • User interface and web services updates to Offsite Green Power tracking
    • Currently in development, but likely will not be available until after the August 28, 2023 Live release.
    • Further details will be provided during the June 26, 2023 Beta release webinar, if available.

Was this article helpful?