Get Usage Data Details

Authorizations

X-API-KEY

string

header

required

Path Parameters

msud_id

string<uuid>

required

ID of the usage data entry to retrieve.

Response

Serializer for MeterSiteUsageData.

External serializer wraps around the helper serializer to provide a more user-friendly interface.

string<uuid>

required

UUID of the meter site usage data entry.

created

string<date-time>

required

Timestamp when the meter site usage data entry was created.

startDate

string<date>

required

Start date for the meter site usage data entry.

endDate

string<date>

required

End date for the meter site usage data entry. If not available or not applicable, this is set to the start date by default.

usage

string

required

Usage amount extracted from billing data. For solar data, this is the kWh produced.

usageUnits

enum<string>

required

Units for usage, as specified in the document

J - J
Btu - Btu
MMBtu - Mmbtu
kJ - Kj
MJ - Mj
GJ - Gj
TJ - Tj
thm (EC) - Therm Ec
thm (US) - Therm Us
thm (UK) - Therm Uk
Dth (EC) - Dth Ec
Dth (US) - Dth Us
Dth (UK) - Dth Uk
Cal - Cal
kCal - Kcal
MCal - Mcal
erg - Erg
kVA - Kva
Wh - WH
kWh - KWH
MWh - MWH
GWh - GWH
ton hours - Ton Hours
W - W
KW - Kw
MW - Mw
GW - Gw
L - L
kL - Kl
ML - Ml
cubic ft - Cubic Ft
cubic yd - Cubic Yd
cubic m - Cubic M
MMCF - Mmcf
MCF - Mcf
HCF - Hcf
CF - Cf
CCF - Ccf
gal (UK) - Gal Uk
gal (US) - Gal Us
100 gal (US) - Hundred Gal Us
100 gal (UK) - Hundred Gal Uk
kgal (US) - Kgal Us
kgal (UK) - Kgal Uk
Mgal (US) - Million Gal Us
Mgal (UK) - Million Gal Uk
teu - Teu
bbl - Bbl
mbbl - Mbbl
kg - Kg
oz t - Oz T
g - G
lb - Lb
mlb - Mlb
tons (US) - Tons
sh ton - Sh Ton
metric ton - Metric Ton
tonne - Tonne
long tn - Long Tn
km - Km
mi - Mi
m - M
cm - Cm
mm - Mm
nm - Nm
yd - Yd
ft - Ft
in - In

Available options:

J,

Btu,

MMBtu,

kJ,

MJ,

GJ,

TJ,

thm (EC),

thm (US),

thm (UK),

Dth (EC),

Dth (US),

Dth (UK),

Cal,

kCal,

MCal,

erg,

kVA,

Wh,

kWh,

MWh,

GWh,

ton hours,

W,

KW,

MW,

GW,

L,

kL,

ML,

cubic ft,

cubic yd,

cubic m,

MMCF,

MCF,

HCF,

CF,

CCF,

gal (UK),

gal (US),

100 gal (US),

100 gal (UK),

kgal (US),

kgal (UK),

Mgal (US),

Mgal (UK),

teu,

bbl,

mbbl,

kg,

oz t,

g,

lb,

mlb,

tons (US),

sh ton,

metric ton,

tonne,

long tn,

km,

mi,

m,

cm,

mm,

nm,

yd,

ft,

in

timeOfUseBreakdown

object[] | null

required

[ELECTRICITY] Array of time-of-use breakdown entries when usage is split by TOU periods. Each entry contains timeOfUse category, usage amount, units, and optional description/dates.

Show child attributes

serviceAddress

string

required

Address of the service location associated with the usage data.

meter

string | null

required

Id of the matching meter associated with the usage data. For uploaded documents, field may be empty if no matching meter is found.

site

object

required

Site matched with the usage data.

Show child attributes

identifiers

object[]

required

Identifiers associated with the meter.

Show child attributes

datasourceType

enum<string>

required

Type of data source (utility) for the usage data entry.

ELECTRICITY - Electricity
GAS - Gas
WATER - Water
DISTRICT - District
WASTE - Waste
FUEL - Fuel
MISC - Misc
REFRIGERANT - Refrigerant
SOLAR - Solar
TELECOM - Telecom

Available options:

ELECTRICITY,

GAS,

WATER,

DISTRICT,

WASTE,

FUEL,

MISC,

REFRIGERANT,

SOLAR,

TELECOM

timeOfUse

enum<string> | null

required

[ELECTRICITY] DEPRECATED: Time of use associated with the electricity usage data entry. Use timeOfUseBreakdown field instead for TOU information.

PEAK - Peak
OFF_PEAK - Off Peak
SHOULDER_MIDPEAK - Shoulder Midpeak
NIGHT_TIME - Night Time
DAY_TIME - Day Time
SUPER_OFF_PEAK - Super Off Peak
CRITICAL_PEAK - Critical Peak
WEEKDAY - Weekday
WEEKEND - Weekend
OTHER - Other

Available options:

PEAK,

OFF_PEAK,

SHOULDER_MIDPEAK,

NIGHT_TIME,

DAY_TIME,

SUPER_OFF_PEAK,

CRITICAL_PEAK,

WEEKDAY,

WEEKEND,

OTHER

netMeteringType

enum<string> | null

required

[ELECTRICITY] Indicates whether the meter is tracking electricity imports from the grid, exports to the grid, or onsite generation.

EXPORT - Export
IMPORT - Import
GENERATION - Generation

Available options:

EXPORT,

IMPORT,

GENERATION

waterType

enum<string> | null

required

[WATER] Type of water used.

POTABLE_WATER - Potable Water
WELL_WATER - Well Water
MUNICIPAL_WATER - Municipal Water
WASTE_WATER - Waste Water

Available options:

POTABLE_WATER,

WELL_WATER,

MUNICIPAL_WATER,

WASTE_WATER

meterHighLow

enum<string> | null

required

[WATER] Indicates if the meter type is 'HIGH' or 'LOW'.

HIGH - High
LOW - Low

Available options:

HIGH,

LOW

gasType

enum<string> | null

required

[GAS] Type of gas used.

NATURAL_GAS - Natural Gas

Available options:

NATURAL_GAS

fuelType

enum<string> | null

required

[FUEL] Type of fuel used, with predefined choices.

ANTHRACITE_COAL - Anthracite Coal
BITUMINOUS_COAL - Bituminous Coal
SUB_BITUMINOUS_COAL - Sub Bituminous Coal
LIGNITE_COAL - Lignite Coal
MIXED_COMMERCIAL_SECTOR - Mixed Commercial Sector
MIXED_ELECTRIC_POWER_SECTOR - Mixed Electric Power Sector
MIXED_INDUSTRIAL_COKING - Mixed Industrial Coking
MIXED_INDUSTRIAL_SECTOR - Mixed Industrial Sector
COAL_COKE - Coal Coke
MUNICIPAL_SOLID_WASTE - Municipal Solid Waste
PETROLEUM_COKE_SOLID - Petroleum Coke Solid
PLASTICS - Plastics
TIRES - Tires
AGRICULTURAL_BYPRODUCTS - Agricultural Byproducts
PEAT - Peat
SOLID_BYPRODUCTS - Solid Byproducts
WOOD_AND_WOOD_RESIDUALS - Wood And Wood Residuals
NATURAL_GAS - Natural Gas
BLAST_FURNACE_GAS - Blast Furnace Gas
COKE_OVEN_GAS - Coke Oven Gas
FUEL_GAS - Fuel Gas
PROPANE_GAS - Propane Gas
LANDFILL_GAS - Landfill Gas
OTHER_BIOMASS_GASES - Other Biomass Gases
ASPHALT_AND_ROAD_OIL - Asphalt And Road Oil
BUTANE - Butane
BUTYLENE - Butylene
CRUDE_OIL - Crude Oil
DISTILLATE_FUEL_OIL_NO_1 - Distillate Fuel Oil No 1
DISTILLATE_FUEL_OIL_NO_2 - Distillate Fuel Oil No 2
DISTILLATE_FUEL_OIL_NO_4 - Distillate Fuel Oil No 4
ETHANE - Ethane
ETHYLENE - Ethylene
HEAVY_GAS_OILS - Heavy Gas Oils
ISOBUTANE - Isobutane
ISOBUTYLENE - Isobutylene
KEROSENE - Kerosene
LIQUEFIED_PETROLEUM_GASES_LPG - Liquefied Petroleum Gases Lpg
COMPRESSED_NATURAL_GAS_CNG - Compressed Natural Gas Cng
LUBRICANTS - Lubricants
MOTOR_GASOLINE - Motor Gasoline
NAPHTHA_LESS_THAN_401_DEG_F - Naphtha Less Than 401 Deg F
NATURAL_GASOLINE - Natural Gasoline
OTHER_OIL_MORE_THAN_401_DEG_F - Other Oil More Than 401 Deg F
PENTANES_PLUS - Pentanes Plus
PETROCHEMICAL_FEEDSTOCKS - Petrochemical Feedstocks
PROPYLENE - Propylene
RESIDUAL_FUEL_OIL_NO_5 - Residual Fuel Oil No 5
RESIDUAL_FUEL_OIL_NO_6 - Residual Fuel Oil No 6
SPECIAL_NAPHTHA - Special Naphtha
UNFINISHED_OILS - Unfinished Oils
USED_OIL - Used Oil
BIODIESEL_100_PERCENT - Biodiesel 100 Percent
BIODIESEL_BLEND - Biodiesel Blend
ETHANOL_BLENDED_GASOLINE - Ethanol Blended Gasoline
ETHANOL_100_PERCENT - Ethanol 100 Percent
RENDERED_ANIMAL_FAT - Rendered Animal Fat
VEGETABLE_OIL - Vegetable Oil
NORTH_AMERICAN_SOFTWOOD - North American Softwood
NORTH_AMERICAN_HARDWOOD - North American Hardwood
BAGASSE - Bagasse
BAMBOO - Bamboo
STRAW - Straw

Available options:

ANTHRACITE_COAL,

BITUMINOUS_COAL,

SUB_BITUMINOUS_COAL,

LIGNITE_COAL,

MIXED_COMMERCIAL_SECTOR,

MIXED_ELECTRIC_POWER_SECTOR,

MIXED_INDUSTRIAL_COKING,

MIXED_INDUSTRIAL_SECTOR,

COAL_COKE,

MUNICIPAL_SOLID_WASTE,

PETROLEUM_COKE_SOLID,

PLASTICS,

TIRES,

AGRICULTURAL_BYPRODUCTS,

PEAT,

SOLID_BYPRODUCTS,

WOOD_AND_WOOD_RESIDUALS,

NATURAL_GAS,

BLAST_FURNACE_GAS,

COKE_OVEN_GAS,

FUEL_GAS,

PROPANE_GAS,

LANDFILL_GAS,

OTHER_BIOMASS_GASES,

ASPHALT_AND_ROAD_OIL,

BUTANE,

BUTYLENE,

CRUDE_OIL,

DISTILLATE_FUEL_OIL_NO_1,

DISTILLATE_FUEL_OIL_NO_2,

DISTILLATE_FUEL_OIL_NO_4,

ETHANE,

ETHYLENE,

HEAVY_GAS_OILS,

ISOBUTANE,

ISOBUTYLENE,

KEROSENE,

LIQUEFIED_PETROLEUM_GASES_LPG,

COMPRESSED_NATURAL_GAS_CNG,

LUBRICANTS,

MOTOR_GASOLINE,

NAPHTHA_LESS_THAN_401_DEG_F,

NATURAL_GASOLINE,

OTHER_OIL_MORE_THAN_401_DEG_F,

PENTANES_PLUS,

PETROCHEMICAL_FEEDSTOCKS,

PROPYLENE,

RESIDUAL_FUEL_OIL_NO_5,

RESIDUAL_FUEL_OIL_NO_6,

SPECIAL_NAPHTHA,

UNFINISHED_OILS,

USED_OIL,

BIODIESEL_100_PERCENT,

BIODIESEL_BLEND,

ETHANOL_BLENDED_GASOLINE,

ETHANOL_100_PERCENT,

RENDERED_ANIMAL_FAT,

VEGETABLE_OIL,

NORTH_AMERICAN_SOFTWOOD,

NORTH_AMERICAN_HARDWOOD,

BAGASSE,

BAMBOO,

STRAW

districtType

enum<string> | null

required

[DISTRICT] Type of district used, either HEATING or COOLING.

HEATING - Heating
COOLING - Cooling

Available options:

HEATING,

COOLING

districtMediumType

enum<string> | null

required

[DISTRICT] Type of heating or cooling medium used, e.g. STEAM, HOT_WATER, etc.

HOT_WATER - Hot Water
STEAM - Steam
HOT_OIL - Hot Oil
CHILLED_WATER - Chilled Water

Available options:

HOT_WATER,

STEAM,

HOT_OIL,

CHILLED_WATER

wasteDescription

string

required

[WASTE] Description of the waste line item. E.g. OCC, Plastic bottles, etc.

wasteType

string

required

[WASTE] Type of waste, e.g. OCC, Plastic bottles, etc. The waste type config can be configured on the Nectar platform.

wasteStream

string

required

[WASTE] Stream of waste, e.g. OCC, Plastic bottles, etc. The waste stream config can be configured on the Nectar platform.

refrigerantType

enum<string> | null

required

[REFRIGERANT] Type of refrigerant used.

R11 - R11
R12 - R12
R22 - R22
R123 - R123
R124 - R124
R134A - R134A
R401A - R401A
R401B - R401B
R402A - R402A
R402B - R402B
R403A - R403A
R403B - R403B
R404A - R404A
R405A - R405A
R406A - R406A
R407A - R407A
R407B - R407B
R407C - R407C
R407D - R407D
R407F - R407F
R408A - R408A
R409A - R409A
R409B - R409B
R410A - R410A
R410B - R410B
R411A - R411A
R411B - R411B
R412A - R412A
R413A - R413A
R413B - R413B
R414A - R414A
R414B - R414B
R415A - R415A
R415B - R415B
R416A - R416A
R417A - R417A
R417B - R417B
R417C - R417C
R418A - R418A
R419A - R419A
R419B - R419B
R420A - R420A
R420B - R420B
R421A - R421A
R421B - R421B
R421C - R421C
R422A - R422A
R422B - R422B
R422C - R422C
R422D - R422D
R422E - R422E
R423A - R423A
R423B - R423B
R424A - R424A
R424B - R424B
R425A - R425A
R426A - R426A
R426B - R426B
R426C - R426C
R427A - R427A
R427B - R427B
R427C - R427C
R428A - R428A
R428B - R428B
R429A - R429A
R429B - R429B
R430A - R430A
R430B - R430B
R431A - R431A
R431B - R431B
R432A - R432A
R432B - R432B
R433A - R433A
R433B - R433B
R433C - R433C
R433D - R433D
R434A - R434A
R434B - R434B
R435A - R435A
R435B - R435B
R436A - R436A
R436B - R436B
R437A - R437A
R437B - R437B
R438A - R438A
R438B - R438B
R444B - R444B
R445A - R445A
R447A - R447A
R448A - R448A
R448B - R448B
R449A - R449A
R449B - R449B
R450A - R450A
R450B - R450B
R451A - R451A
R451B - R451B
R452A - R452A
R452B - R452B
R453A - R453A
R454A - R454A
R454B - R454B
R454C - R454C
R455A - R455A
R456A - R456A
R459A - R459A
R460A - R460A
R461A - R461A
R462A - R462A
R463A - R463A
R464A - R464A
R465A - R465A
R115 - R115
R116 - R116
R12B1 - R12B1
R13 - R13
R13B1 - R13B1
R13I1 - R13I1
R14 - R14
R14e - R14E
R21 - R21
R23 - R23
R30 - R30
R31 - R31
R40 - R40
R41 - R41
R50 - R50
R113 - R113
R114 - R114
R125 - R125
R141B - R141B
R142B - R142B
R143A - R143A
R152A - R152A
R170 - R170
R218 - R218
R290 - R290
R318 - R318
R600 - R600
R600A - R600A
R717 - R717
R744 - R744
R508B - R508B
R1270 - R1270
R32 - R32
R161 - R161
R227EA - R227Ea
R236CB - R236Cb
R236EA - R236Ea
R236FA - R236Fa
R245CA - R245Ca
R245FA - R245Fa
R414C - R414C
R415C - R415C
R416B - R416B
R123A - R123A
R123B - R123B
R365MFC - R365Mfc
R4310 - R4310
R127C - R127C
R12A - R12A
R22A - R22A
R502A - R502A
R601A - R601A

Available options:

R11,

R12,

R22,

R123,

R124,

R134A,

R401A,

R401B,

R402A,

R402B,

R403A,

R403B,

R404A,

R405A,

R406A,

R407A,

R407B,

R407C,

R407D,

R407F,

R408A,

R409A,

R409B,

R410A,

R410B,

R411A,

R411B,

R412A,

R413A,

R413B,

R414A,

R414B,

R415A,

R415B,

R416A,

R417A,

R417B,

R417C,

R418A,

R419A,

R419B,

R420A,

R420B,

R421A,

R421B,

R421C,

R422A,

R422B,

R422C,

R422D,

R422E,

R423A,

R423B,

R424A,

R424B,

R425A,

R426A,

R426B,

R426C,

R427A,

R427B,

R427C,

R428A,

R428B,

R429A,

R429B,

R430A,

R430B,

R431A,

R431B,

R432A,

R432B,

R433A,

R433B,

R433C,

R433D,

R434A,

R434B,

R435A,

R435B,

R436A,

R436B,

R437A,

R437B,

R438A,

R438B,

R444B,

R445A,

R447A,

R448A,

R448B,

R449A,

R449B,

R450A,

R450B,

R451A,

R451B,

R452A,

R452B,

R453A,

R454A,

R454B,

R454C,

R455A,

R456A,

R459A,

R460A,

R461A,

R462A,

R463A,

R464A,

R465A,

R115,

R116,

R12B1,

R13,

R13B1,

R13I1,

R14,

R14e,

R21,

R23,

R30,

R31,

R40,

R41,

R50,

R113,

R114,

R125,

R141B,

R142B,

R143A,

R152A,

R170,

R218,

R290,

R318,

R600,

R600A,

R717,

R744,

R508B,

R1270,

R32,

R161,

R227EA,

R236CB,

R236EA,

R236FA,

R245CA,

R245FA,

R414C,

R415C,

R416B,

R123A,

R123B,

R365MFC,

R4310,

R127C,

R12A,

R22A,

R502A,

R601A

additionalFields

object

required

Additional fields for the usage data. For information on adding custom fields to the Nectar schema get in touch with our team.

Show child attributes

meterIsTracked

boolean

required

Whether the meter is tracked.

meterAddress

string | null

required

Address of the meter.

document

object

required

Document associated with the usage data.

Show child attributes

updated

string<date-time>

Timestamp when the meter site usage data entry was last updated.

isEstimated

boolean

Indicates if the usage data is estimated by the utility company.

isImplied

boolean

Indicates if the usage data is implied by the tenant usage and the raw usage. For more information on how this differs from estimation, see the Nectar methodology.

currentReading

string<decimal> | null

Current meter reading.

Pattern: ^-?\d{0,10}(?:\.\d{0,10})?$

previousReading

string<decimal> | null

Previous meter reading.

Pattern: ^-?\d{0,10}(?:\.\d{0,10})?$

multiplier

string<decimal> | null

Multiplier applied to the meter reading.

Pattern: ^-?\d{0,10}(?:\.\d{0,10})?$

multiplierDescription

string | null

Description of the multiplier applied to the meter reading. E.g. conversion factor, pressure adjustment, etc.

multiplier2

string<decimal> | null

Second multiplier applied to the meter reading.

Pattern: ^-?\d{0,10}(?:\.\d{0,10})?$

multiplier2Description

string | null

Description of the second multiplier applied to the meter reading. E.g. conversion factor, pressure adjustment, etc.

fractionRenewable

string<decimal> | null

[ELECTRICITY] Fraction of energy sourced from renewable resources (0 to 1). This field is populated from the utility bill or set by a user.

Pattern: ^-?\d{0,5}(?:\.\d{0,5})?$

netMeteringGeneratedKwh

string<decimal> | null

[ELECTRICITY] Total kWh of electricity generated from solar on-site.

Pattern: ^-?\d{0,10}(?:\.\d{0,10})?$

netMeteringGridImportKwh

string<decimal> | null

[ELECTRICITY] Total kWh of electricity imported from the grid, only applicable if the meter is not tracking imports.

Pattern: ^-?\d{0,10}(?:\.\d{0,10})?$

netMeteringGridExportKwh

string<decimal> | null

[ELECTRICITY] Total kWh of electricity exported to the grid, only applicable if the meter is not tracking exports.

Pattern: ^-?\d{0,10}(?:\.\d{0,10})?$

exclusion

boolean

Indicates if the meter site usage data entry is subtracted in aggregation (to be used when meter is used to measure what needs to be deducted in the case of landlord - tenant calculations).

tariff

string | null

[ELECTRICITY, GAS, WATER, DISTRICT] Tariff code or description associated with the usage.

billedDemand

string<decimal> | null

[ELECTRICITY] Total billed kW, meter level. Only applies to electricity meters. If billed demand is not available or allocatable across multiple meters, this field is set to 0.

Pattern: ^-?\d{0,10}(?:\.\d{0,10})?$

supplierName

string | null

[ELECTRICITY, GAS] Name of the supplier. Only applies to electricity and gas meters.

utilityName

string | null

[ELECTRICITY, GAS] Name of the local delivery utility company. Only applies to electricity and gas meters.

country

string | null

Country associated with the meter site usage data entry.

Accounts

Companies

Webhook Portal

Connections

Documents

Intervals

Jobs

Meters

Ping

Sites

Team

Usage Data

Webhook Payloads

Authorizations

Path Parameters

Response