Task

Obtain the total consumption for a given meter during a given service period, without double-counting and ensuring data accuracy.

Contextual Notes

• A measurement period is defined as the period of time between periodStart and periodEnd dates. For measurement periods that have the same dates or are only one day more or less on either or both ends, we consider them as the same measurement periods.
• A meter reading is defined as a data record for a meter and represented by a meterData object in the Arcadia data model. A meter can have multiple meter readings over time.
• On the Utility Cloud API, the “primary” provider is sometimes referred to as the “main” provider and the “additional” provider is sometimes referred to as the “secondary” provider.

High Level Steps

1. Check if there are any duplicates for the same measurement period and the same meter.

If there are ADDITIONAL/SECONDARY providers present on a statement, there will be duplicate meter readings and the duplicates will occur on one statement.

• For example, on a statement for the meter-level measurement period between Jan 1, 2023, and Feb 1, 2023, there are two meter readings for the same meter with the meter number 123. The first meter reading is 45 kWh and the second meter reading is 50 kWh. When this happens, you will need to decide which meter reading to use when accounting for the total usage for this measurement period.

If there are no ADDITIONAL/SECONDARY providers present on a statement, there may be duplicate meter readings and, if so, they will occur on different statements.

You can check whether ADDITIONAL/SECONDARY providers are present at the JSON path accountData.providers.classification in a Retrieve Statement endpoint response. To learn more about ADDITIONAL/SECONDARY providers, see the Arcadia Data Model guide.

When duplicates are present, thetotalUsages of each meter reading may be the same or different.

2. If duplicates are present, decide which one to use.

📘

Around 70% of meter reading duplicates due to this edge case can be resolved by this logic.

To ensure you are not double-counting and choosing the accurate value, you can choose which value to use with the following steps:

• For meter readings that have the same totalUsage values, you can choose a random one to use as the totalUsage values are identical.
• For meter readings that have different totalUsage values, you need to determine which meter reading belongs to the commodity distributor and use the value from that meter. The commodity distributor owns the metering, therefore they are accountable for the accuracy of the data. You can check if a meter reading belongs to the commodity distributor with the following steps:
  • Check the value for the meterData.deregulationStatus field. When the value is DELIVERY_ONLY, the meter reading belongs to the commodity distributor and you can use the totalUsage value reported for this meter reading.
    • If the meterData.deregulationStatus value is not DELIVERY_ONLY, then check the accountData.charges.lifeCycleStage field by first finding the accountData object the meterData object nests under, then finding a charges object that nests under the accountData object. When the value for accountData.charges.lifeCycleStage is one of TRANSMISSION, DISTRIBUTION, COMBINED_DELIVERY, then the meter reading belongs to the commodity distributor and you can use the totalUsage value reported for this meter.
      • If neither of these values are present in the JSON response, you need to manually review the statement and determine which meter belongs to the commodity distributor contextually. Additionally, you can reach out to our Support team for a recommendation.

        👍

        Consider upgrading to the Plug API and using DataHub

        If you prefer us to handle this logic for you, consider using our DataHub product. The DataHub product has this logic built-in, therefore will only present the relevant total usage from commodity usage accounting purposes.

Steps for De-Duplicating via the API

🚧

Most likely, if you are ONLY using the API, you will be able to resolve around 50% of the duplicates due to this edge case programmatically and will need to rely on manual reviews to resolve the remaining duplicates.

Accouting for one meter for one measurement period

1. Use the Meter Details endpoint to make a request by specifying the meterId.
2. The response will include an array of usage objects for the specified meterId for all measurement periods.
3. Identify the measurement period you care about and identify all usage objects that has the same periodStart and periodEnd date or +/- one day with respect to the measurement period, has "tariffRateComponents.tarffRateComponentType": "TOTAL", and has "contributionStatus": "CONTRIBUTING"
   1. If there is only one usage object identified, then there is no duplicate meter readings for the specific measurement period and you can skip step 4 and proceed to step 6.
   2. If there are more than one usage object identified, proceed to step 4.
4. Review the measuredUsage value and compare if the values are the same for the identified usage objects.
   1. If they are the same, you can use any one of them to account for the total usage.
   2. If they are not the same, proceed to step 5.
5. Review the ._embedded.meters[0].deregulationStatus field for each identified usage object.
   1. If the value is DELIVERY_ONLY, then the meter reading is for a commodity distributor and you can use the totalUsage value.
   2. If the value is not DELIVERY_ONLY, you will need to manually perform the remaining checks outlined here.

Account for one meter for all measurement periods

6. Repeat steps 1-5 for all measurement periods you need to account for.

Accounting for all meters for all measurement periods

7. Call the List Meters endpoint without specifying any query parameters to get all meterIds associated with your org.
8. Repeat steps 1-6 for all meterIds obtained in step 7.