Skip to main content
This guide provides API-facing details for developers building integrations. For a user-friendly introduction, see How your data works in the Knowledge Base.

​
Entity relationships

Nectar organizes utility data in a hierarchical structure:

​
Entity definitions

EntityAPI resourceDescription
Company/companyTop-level entity containing sites and connections
Site/company/{id}/sitePhysical address with meters
Connection/company/{id}/connectionConfigured link to a utility provider
Account/company/{id}/accountBilling relationship with a utility; discovered via connections
Meter/company/{id}/meterMeasurement point for a single commodity at a site
Document/company/{id}/documentProcessed utility statement
UsageData/company/{id}/usageTime-series consumption record
LineItemNested in documentIndividual charge or credit on a document

​
Data processing behavior

When a document enters Nectar, it moves through an external lifecycle: Key behaviors:
  • Core bill fields, usage data, and line items are extracted from source documents.
  • Meter/account/site associations are applied to organize data in the API model.
  • Validation checks run before data is published to improve quality and consistency.
  • Electricity demand values are included when present in source documents.

​
Key data fields

​
Document

FieldTypeDescription
idUUIDUnique identifier
billDateDateEnd date of billing period
startDateDateStart date of billing period
totalChargesDecimalTotal amount due
currentChargesDecimalNew charges this period
chargesUnitsStringCurrency code (USD, EUR, etc.)
revisedDocumentUUIDLinks to superseding document if revised

​
UsageData

FieldTypeDescription
idUUIDUnique identifier
startDateDateStart of consumption period
endDateDateEnd of consumption period
rawUsageDecimalUsage as reported on bill
rawUsageUnitsStringOriginal unit of measure
standardUsageDecimalNormalized usage value
exclusionBooleanIf true, usage is subtracted from aggregations
netMeteringTypeEnumIMPORT, EXPORT, or GENERATION

​
Meter

FieldTypeDescription
idUUIDUnique identifier
datasourceTypeEnumCommodity: ELECTRICITY, GAS, WATER, etc.
isTrackedBooleanWhether included in active analytics
isDuplicatedBooleanWhether marked as duplicate

​
Calendarization algorithm

Nectar converts billing period data to calendar months using daily proration: 
# Simplified algorithm
daily_usage = total_usage / (end_date - start_date + 1)

for month in overlapping_months:
    overlap_start = max(bill_start, month_start)
    overlap_end = min(bill_end, month_end)
    overlap_days = (overlap_end - overlap_start) + 1
    month_usage = daily_usage * overlap_days
Key details:
  • Inclusive date counting: Both start and end dates are included (closed interval)
  • Computed at query time: Raw data preserved; calendarization applied dynamically
  • Exclusion handling: Excluded meters multiply by -1 during aggregation

​
Cost attribution algorithm

For multi-meter bills, charges are allocated proportionally by usage: 
# For same-commodity charges
meter_share = meter_usage / total_usage
meter_cost = (total_charges - open_balance) * meter_share

# For account-level charges (customer fees, etc.)
meter_cost = charge_amount / meter_count
Key details:
  • Uses new charges (excludes carried balance) to prevent double-counting
  • Demand charges allocated specifically to demand meters
  • Currency preserved (no automatic conversion)

​
Annotations and computed fields

Several fields are computed at query time rather than stored:
AnnotationDescriptionUsed for
isArchiveddataCollectionStopDate is set and in pastFiltering inactive sites
isVisibleByCurrentUserUser has site permissionPermission filtering
dailyUsagestandardUsage / span_daysCalendarization
calendarizedUsagedailyUsage * overlap_daysMonthly aggregation

​
Next steps

Document processing details

Document-processing behavior and expected outputs

Meter organization

Meter, account, and site relationships