Documentation Index Fetch the complete documentation index at: https://docs.nectarclimate.com/llms.txt
Use this file to discover all available pages before exploring further.
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 /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 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 idUUID Unique identifier billDateDate End date of billing period startDateDate Start date of billing period totalChargesDecimal Total amount due currentChargesDecimal New charges this period chargesUnitsString Currency code (USD, EUR, etc.) revisedDocumentUUID Links to superseding document if revised
UsageData Field Type Description idUUID Unique identifier startDateDate Start of consumption period endDateDate End of consumption period rawUsageDecimal Usage as reported on bill rawUsageUnitsString Original unit of measure standardUsageDecimal Normalized usage value netMeteringTypeEnum IMPORT, EXPORT, or GENERATION
Meter Field Type Description idUUID Unique identifier datasourceTypeEnum Commodity: ELECTRICITY, GAS, WATER, etc. isTrackedBoolean Whether included in active analytics isDuplicatedBoolean Whether marked as duplicate tagsArray 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 dynamicallyNet 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 isArchiveddataCollectionStopDate is set and in pastFiltering inactive sites isVisibleByCurrentUserUser has site permission Permission 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
