Data model overview

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

Entity	API resource	Description
Company	`/company`	Top-level entity containing sites and connections
Site	`/company/{id}/site`	Physical address with meters
Connection	`/company/{id}/connection`	Configured link to a utility provider
Account	`/company/{id}/account`	Billing relationship with a utility; discovered via connections
Meter	`/company/{id}/meter`	Measurement point for a single commodity at a site
Document	`/company/{id}/document`	Processed utility statement
UsageData	`/company/{id}/usage`	Time-series consumption record
LineItem	Nested in document	Individual 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

Field	Type	Description
`id`	UUID	Unique identifier
`billDate`	Date	End date of billing period
`startDate`	Date	Start date of billing period
`totalCharges`	Decimal	Total amount due
`currentCharges`	Decimal	New charges this period
`chargesUnits`	String	Currency code (USD, EUR, etc.)
`revisedDocument`	UUID	Links to superseding document if revised

UsageData

Field	Type	Description
`id`	UUID	Unique identifier
`startDate`	Date	Start of consumption period
`endDate`	Date	End of consumption period
`rawUsage`	Decimal	Usage as reported on bill
`rawUsageUnits`	String	Original unit of measure
`standardUsage`	Decimal	Normalized usage value
`netMeteringType`	Enum	IMPORT, EXPORT, or GENERATION

Meter

Field	Type	Description
`id`	UUID	Unique identifier
`datasourceType`	Enum	Commodity: ELECTRICITY, GAS, WATER, etc.
`isTracked`	Boolean	Whether included in active analytics
`isDuplicated`	Boolean	Whether marked as duplicate
`tags`	Array	Meter tags assigned to this meter

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
Net metering exports: Export 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:

Annotation	Description	Used for
`isArchived`	`dataCollectionStopDate` is set and in past	Filtering inactive sites
`isVisibleByCurrentUser`	User has site permission	Permission filtering
`dailyUsage`	`standardUsage / span_days`	Calendarization
`calendarizedUsage`	`dailyUsage * overlap_days`	Monthly aggregation

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

Entity relationships

Entity definitions

Data processing behavior

Key data fields

Document

UsageData

Meter

Calendarization algorithm

Cost attribution algorithm

Annotations and computed fields

Next steps

Document processing details

Meter organization

​Entity relationships

​Entity definitions

​Data processing behavior

​Key data fields

​Document

​UsageData

​Meter

​Calendarization algorithm

​Cost attribution algorithm

​Annotations and computed fields

​Next steps

Document processing details

Meter organization

Entity relationships

Entity definitions

Data processing behavior

Key data fields

Document

UsageData

Meter

Calendarization algorithm

Cost attribution algorithm

Annotations and computed fields

Next steps