Many words in the utility industry are super generic, so we try to be very consistent and define our nomeclature. If you get confused, we consider that a bug, so please tell us!
*_uid
The unique identifier for the UtilityAPI object. This is set by UtilityAPI, not the utility,
and is what you use to access specific objects on UtilityAPI. In API endpoint requests and
responses, these will always appear as something_uid to avoid confusion with
another field that has information about some utility identifier.
*_id
An identifier NOT set by UtilityAPI. This is different from the above uid.
The most visible example of this is meter_uid vs. service_identifier.
The former is what you use to retrieve the Meter object from /meters/123,
and the later is the utility's assigned service account id. We wish we could have just
used the utility's service account id as the meter_uid, but since we work with
multiple utilities, we don't want to risk a conflicting service identifier between different
utilities.
A utility service is the individual contract to provide electricity to a customer for some usage point. Basically, this is the thing that has a utility meter. Services do not always have physical meters (for example, an outdoor lighting service usually doesn't have a physical meter), but most of the time they do and most people call their services "meters".
This is why our API endpoint /meters is named
"meters" instead of "services". However, /meters is really the list of services so some
Meter objects might not have a physical meter number, but they will always have a
service_identifier.
The utility rate schedule that a utility service is on. This is a piece of information
we include when collecting utility data, but it can be called "rate" or "rate schedule".
We are going to always refer to it as service_tariff and avoid using the
term "rate" to avoid confusion.
An abbreviation for utility's service_identifier that is used in our
dashboard and documentation.
The invoice charging for Meter use. This is one of the two pieces of data we collect. Even if you receive one paper bill for multiple services, we automatically break the bill apart and include the appropriate subset under each Meter.
Electricity use for a certain time period. This is the other of the two pieces of data we collect. With the advent of smart meters, the utility can collect energy usage over small increments. When this is available, we will collect it as a download option.