What changes were made in the August 2022 web services 19.0 release?

The Beta release of the Portfolio Manager web services 19.0 schemas was June 27, 2022. The Live release was August 29, 2022. 

For the 19.0 Beta release on June 27, 2022 and LIVE release on August 29, 2022
  • Changes to the use details for the “Convenience Store” property use
    • Applies to all Convenience Stores (including those with Gas Stations and those without gas stations)
    • New use details
      • Number of Full-Time Equivalent (FTE) Workers
        • Web services name: numberOfFTEWorkers
      • Number of Cooking Equipment Units
        • Web services name: numberOfCookingEquipmentUnits
      • Number of Warming/Heating Equipment Units
        • Web services name: numberOfWarmingHeatingEquipmentUnits
    • Existing “Convenience Store” property uses will be backfilled with default values
      • Number of Full-Time Equivalent (FTE) Workers
        • Backfill based on a default density of 2.2 FTE workers for every 1,000 square feet of entered gross floor area
      • Number of Cooking Equipment Units
        • Backfill with default value of “0”
      • Number of Warming/Heating Equipment Units
        • Backfill with default value of “0”
      • Providers and/or building owners will need to review and correct default values as appropriate.
    • 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 …/metrics call:
      • convenienceStoreWithGasFullTimeEquivalentFteWorkers
      • convenienceStoreWithoutGasFullTimeEquivalentFteWorkers
      • convenienceStoreWithGasFullTimeEquivalentFteWorkersDensity
      • convenienceStoreWithoutGasFullTimeEquivalentFteWorkersDensity
      • convenienceStoreWithGasNumberOfCookingEquipmentUnits
      • convenienceStoreWithoutGasNumberOfCookingEquipmentUnits
      • convenienceStoreWithGasNumberOfWarmingHeatingEquipmentUnits
      • convenienceStoreWithoutGasNumberOfWarmingHeatingEquipmentUnits
  • Addition of Spanish to “preferred language” options
    • Spanish will be added as a selection for <languagePreference> in the account.xsd and customer.xsd schemas.
    • This option will be automatically incorporated into the following GET calls:
      • GET /account
      • GET /customer/<customerId>
    • This option will be available for the following POST and PUT calls:
      • PUT /account
      • POST /account
      • POST /customer
      • PUT /customer/<customerId>
    • Although this new functionality will be part of the 19.0 release, Spanish will not be supported as a language preference until 2023. If you try to reference it in the above PUT and POST calls before then, you will receive the following error:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <response status="Error">
      <errors>
            <error errorDescription="es_US (Spanish) is not currently available." errorNumber="-200"/>
      </errors>
 </response>
 
  • Rate limits for web service requests
In order to provide a high quality of service for all Portfolio Manager users, EPA began applying a rate limit for Portfolio Manager web service requests in the 19.0 release:
 
 TEST Environment 
8am to 8pm EDTOff hours
M-F10r/s10r/s
Sat-Sun10r/s10r/s
*The TEST request rate limit is intentionally set low to allow providers to more easily verify their retry logic. This rate limit will remain at 10 requests per second.
 
 LIVE Environment 
8am to 8pm EDTOff hours
M-F 100r/s200r/s
Sat-Sun 200r/s200r/s

See this FAQ on rate limits for more information.
 
  • Updates to federalAgency.xsd schema
    • Minor updates to the schema definition to improve development integration.
    • No changes to XML response output from the Get Federal Agency List call.
 
  • 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)
      • Default fuel mix (as used in Target Finder and Design)
      • Weather station mapping
      • Source energy conversion factors
      • National Median EUI values

For release later in 2022 (specific dates TBD)

The following enhancements will be released in both Portfolio Manager and the Portfolio Manager web services API later in 2022. These will not be included in the Beta release on June 27. More details regarding these enhancements, included anticipated release date(s) and documentation for front-end and API functionality, will be communicated once available.
​​​​
  • New Score for Single Family Homes
    • The current ENERGY STAR Home Energy Yardstick functionality for existing Single Family Homes will be integrated within Portfolio Manager, and will return a score on a scale of 1-100.
    • ENERGY STAR Certification will not be available for existing Single Family Homes.
    • Web service providers will be able to assess the performance of Single Family Homes in two ways:
      • As a persistent (saved) property record within Portfolio Manager
        • Uses the existing singleFamilyHome.xsd schema for the creation or editing of this property use and use details.
        • totalGrossFloorArea and numberOfPeople will be used to calculate the score.
          • totalGrossFloorArea is a required use detail.
          • numberOfPeople will be defaulted to “2” if a value is not provided.
        • numberOfBedrooms is optional (not a required value), and will not be assigned a default if no value is entered.
        • Providers and/or building owners will need to review and correct default values as appropriate.
        • All other calls (including GET …/metrics) will continue to function as they do now, with the addition of “score” as a metric that can be returned for this property use.
      • As a “one-off” assessment
        • A new web service (POST /hey) will be introduced that will allow calculation of a 1-100 score for a Single Family Home, without previously creating a property record in Portfolio Manager.
        • Similar to the “Target Finder Services” available in the API, results from this pathway will not be saved within Portfolio Manager for future reference.
        • This new API call will require authentication.
        • Anticipated web service details are as follows:
        • Example Request
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<hey>
    <propertyInfo>
        <postalCode>60304</postalCode>
        <numberOfOccupants>2</numberOfOccupants>
        <grossFloorArea units="Square Feet" temporary="false">
            <value>1500</value>
        </grossFloorArea>
    </propertyInfo>
    <meter>
        <type>Electric</type>
        <unitOfMeasure>kBtu (thousand Btu)</unitOfMeasure>
        <meterData>
            <meterConsumption>
                <startDate>2019-01-01</startDate>
                <endDate>2019-01-31</endDate>
                <usage>4000</usage>
            </meterConsumption>
                 
[…user enters 12 consecutive months of consumption data for each fuel type consumed at the home…]

        </meterData>
    </meter>
    <meter>
        <type>Natural Gas</type>
        <unitOfMeasure>kBtu (thousand Btu)</unitOfMeasure>
        <meterData>
            <meterConsumption>
                <startDate>2019-01-01</startDate>
                <endDate>2019-01-31</endDate>
                <usage>2000</usage>
            </meterConsumption>

[…user enters 12 consecutive months of consumption data for each fuel type consumed at the home…]

        </meterData>
    </meter>
</hey>
        •  
Example Response
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<propertyMetrics month="12" year="2019">
    <metric name="sourceTotal" uom="kBtu" dataType="numeric">
        <value>159600.0</value>
    </metric>
    <metric name="siteEnergyUseElectricityGridPurchase" uom="kBtu" dataType="numeric">
        <value>48000.0</value>
    </metric>
    <metric name="siteEnergyUseNaturalGas" uom="kBtu" dataType="numeric">
        <value>24000.0</value>
    </metric>
    <metric name="score" dataType="numeric">
        <value>35</value>
    </metric>
    <metric name="n/a" dataType="string">
        <value>60304</value>
    </metric>
    <metric name="coolingDegreeDaysCDD" uom="&#176;F" dataType="numeric">
        <value>1074.0</value>
    </metric>
    <metric name="heatingDegreeDaysHDD" uom="&#176;F" dataType="numeric">
        <value>6126.0</value>
    </metric>
    <metric name="singleFamilyHomeNumberOfPeople" dataType="numeric">
        <value>2.00</value>
    </metric>
    <metric name="nonTimeWeightedFloorArea" uom="ft&#178;" dataType="numeric">
        <value>1500.0</value>
    </metric>
    <metric name="scoreMotivationText" dataType="string">
        <value>Consider taking action to reduce your home's energy use. You could save about $210 per year by improving your score to a 50, the average U.S. home score.</value>
    </metric>
</propertyMetrics>
Note that this service will return calculated metrics for the most recent 12-month period for which total energy consumption is available. If a user provides more than 12 complete months of energy data, those values will be ignored in calculating metrics.
This functionality is expected to be released in the Portfolio Manager user interface and the web services API in Fall 2022.
 
  • New 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.
    • This functionality is expected to be released in the Portfolio Manager user interface and the web services API in late 2022.
 
  • Extend user interface reporting functionality to web services
    • Custom Reports
      • Additional API calls will be made available to better align front-end and API reporting functionality, including:
        • Enabling web services users to design and generate a custom report containing up to 50 metrics for multiple properties and multiple period ending dates (this new call will be asynchronous);
        • Enabling web service users to share a custom report template with another Portfolio Manager user; and
        • Enabling web service users to request data from others using a custom reporting template.
      • It is anticipated that enhancement will supplement the existing "Get Metrics" API call, which is limited to 10 metrics for a single property.
      • These services are expected to be available in late 2022. They will be released directly into the Live API, without a prior Beta period. Further documentation will be provided closer to release.
 
    • Data Requests/Responses
      • 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.
      • These services are expected to be available in 2023. They will be released directly into the Live API, without a prior Beta period. Further documentation will be provided closer to release.
 
  • New "ENERGY STAR Score Preview" metric
    • This new metric is a "preview" of what a given property's new score will be based on a forthcoming update to that property type's score model.
    • The purpose is to provide stakeholders with a sense of how their score(s) will change based on the model update, so that they can plan for these changes and/or provide feedback to EPA on the new score model. 
    • Note that this metric will only return a score preview value for property types that are currently undergoing a score update.  All others will return a value of "N/A."
      • This metric is already available in the front-end user interface, but currently returns a value of "N/A" for all properties.
      • This metric is already availably via the Get Metrics API call (web services name: scorePreview), but currently returns a value of "N/A" for all properties.
    • The first score model that will utilize the "Score Preview" metric will be the new model for Convenience Stores. Anticipated release of the Convenience Store Score Preview is late 2022.
    • Please refer to this FAQ for more information. 
​​​​​

EPA expects to hold another webinar dedicated to these topics in the future, as further guidance and documentation become available.

Was this article helpful?