> ## Documentation Index > Fetch the complete documentation index at: https://nectarclimate.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Data model overview > Technical guide to Nectar API data structures, processing behavior, and entity relationships. This guide provides API-facing details for developers building integrations. For a user-friendly introduction, see [How your data works](/docs/platform/methodology/overview) in the Knowledge Base. *** ## Entity relationships Nectar organizes utility data in a hierarchical structure: ```mermaid theme={null} erDiagram Company ||--o{ Site : contains Company ||--o{ Connection : has Connection ||--o{ Account : discovers Site ||--o{ Meter : contains Account ||--o{ Meter : owns Meter ||--o{ UsageData : records Meter }|--|| Commodity : tracks Account ||--o{ Document : receives Document ||--o{ LineItem : contains Document ||--o{ UsageData : generates ``` ### 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: ```mermaid theme={null} flowchart LR A[Document Input] --> B[Extraction] B --> C[Validation] C --> D[Structured API Data] ``` 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.) | | `revisedDocumentId` | UUID \| null | When every usage row on this document is revised to the same document, the ID of that replacing document; otherwise null | | `supersededDocumentIds` | UUID\[] | IDs of documents fully superseded by this one (every usage row on each listed document points here) | ### UsageData | Field | Type | Description | | ------------------- | ------------ | ---------------------------------------------------------------------------------------------- | | `id` | UUID | Unique identifier | | `revisedDocumentId` | UUID \| null | When this usage record is superseded by a corrected document, the ID of the replacing document | | `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 | Document-level revision fields stay compatible for **full-document** revisions. Usage and emissions exclusions are **per usage row**; sibling usage without a revision link still contributes. For site cost, superseded rows preserve the earlier document's historical meter and site allocation. ### Meter | Field | Type | Description | | ---------------- | ------- | ----------------------------------------------------------------------- | | `id` | UUID | Unique identifier | | `datasourceType` | Enum | Commodity: ELECTRICITY, GAS, WATER, SEWER, etc. | | `waterType` | Enum | Water subtype when `datasourceType` is WATER (potable, well, municipal) | | `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: ```python theme={null} # 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, Nectar first assigns line items linked only to one site. It then allocates the remaining net current charges: ```python theme={null} net_charges = total_charges - open_balance remainder = net_charges - directly_assigned_charges utility_type_share = remainder / utility_types_with_usage meter_share = utility_type_share * meter_usage / utility_type_usage ``` Key details: * Uses **net current charges** so carried balances are not counted again * Falls back to an equal split only when no eligible row has positive usage * Retains superseded rows for historical site cost allocation * Normalizes cross-bill portfolio cost analytics to USD; bill audit views retain native currency *** ## 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 | *** ## Next steps Document-processing behavior and expected outputs Meter, account, and site relationships