Skip to main content
GET
/
usage
/
connection
/
{connection_id}
Get Usage Data by Utility Connection
curl --request GET \
  --url https://external.nectarclimate.com/v2/usage/connection/{connection_id} \
  --header 'X-API-KEY: <api-key>'
{
  "totalUsageData": 123,
  "perPage": 123,
  "totalPages": 123,
  "currentPage": 123,
  "hasNext": true,
  "hasPrevious": true,
  "usageData": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "created": "2023-11-07T05:31:56Z",
      "startDate": "2023-12-25",
      "endDate": "2023-12-25",
      "usage": "<string>",
      "usageUnits": "J",
      "timeOfUseBreakdown": [
        {
          "timeOfUse": "PEAK",
          "usage": "<string>",
          "usageUnits": "Wh",
          "description": "<string>",
          "startDate": "2023-12-25",
          "endDate": "2023-12-25"
        }
      ],
      "serviceAddress": "<string>",
      "meter": "<string>",
      "site": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "name": "<string>",
        "dataCollectionStopDate": "2023-12-25",
        "externalId": "<string>",
        "address": "<string>",
        "path": [
          "<string>"
        ],
        "occupancyPercent": "<string>"
      },
      "identifiers": [
        {
          "rawName": "<string>",
          "value": "<string>",
          "name": "<string>"
        }
      ],
      "datasourceType": "ELECTRICITY",
      "timeOfUse": "PEAK",
      "netMeteringType": "EXPORT",
      "waterType": "POTABLE_WATER",
      "meterHighLow": "HIGH",
      "gasType": "NATURAL_GAS",
      "fuelType": "ANTHRACITE_COAL",
      "districtType": "HEATING",
      "districtMediumType": "HOT_WATER",
      "wasteDescription": "<string>",
      "wasteType": "<string>",
      "wasteStream": "<string>",
      "refrigerantType": "R11",
      "additionalFields": {},
      "meterIsTracked": true,
      "meterAddress": "<string>",
      "document": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "created": "2023-11-07T05:31:56Z",
        "auditTrailUrl": "<string>",
        "url": "<string>",
        "billDate": "2023-12-25",
        "chargesUnits": "USD",
        "utilityCompany": "<string>",
        "status": "<string>",
        "flaggedStatus": "<string>",
        "revisedDocumentId": "<string>",
        "updated": "2023-11-07T05:31:56Z",
        "fileName": "<string>",
        "email": "[email protected]",
        "jobId": "<string>",
        "notes": "<string>",
        "dueDate": "2023-12-25",
        "totalCharges": "<string>",
        "sourceType": "INVOICE",
        "isFlagged": true
      },
      "updated": "2023-11-07T05:31:56Z",
      "isEstimated": true,
      "isImplied": true,
      "currentReading": "<string>",
      "previousReading": "<string>",
      "multiplier": "<string>",
      "multiplierDescription": "<string>",
      "multiplier2": "<string>",
      "multiplier2Description": "<string>",
      "fractionRenewable": "<string>",
      "netMeteringGeneratedKwh": "<string>",
      "netMeteringGridImportKwh": "<string>",
      "netMeteringGridExportKwh": "<string>",
      "exclusion": true,
      "tariff": "<string>",
      "billedDemand": "<string>",
      "supplierName": "<string>",
      "utilityName": "<string>",
      "country": "<string>"
    }
  ]
}

Authorizations

​
X-API-KEY
string
header
required

Path Parameters

​
connection_id
string<uuid>
required

ID of the connection for which to retrieve usage data.

Query Parameters

​
datasourceType
enum<string>[]

('Optional. List of datasource types to filter by. If not provided, includes all types. Must be a sublist of "ELECTRICITY", "GAS", "WATER", "DISTRICT", "WASTE", "FUEL", "MISC", "REFRIGERANT", "SOLAR", "TELECOM"',)

  • 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
​
dateType
enum<string>
default:BILL_DATE

Filter by date field: 'UPDATED_DATE' (last update date), 'CREATED_DATE' (creation date), 'BILL_DATE' (default, bill date on the document), or 'USAGE_PERIOD' (usage period start and end dates). Each date parameter is applied independently if provided. For 'CREATED_DATE' and 'UPDATED_DATE', dates are truncated to start of day (00:00:00). Example: for data after January 1, 2024, use startDate=2024-01-01; for data before January 31, 2024, use endDate=2024-01-31.

  • USAGE_PERIOD - Usage Period
  • BILL_DATE - Bill Date
  • CREATED_DATE - Created Date
  • UPDATED_DATE - Updated Date
Available options:
USAGE_PERIOD,
BILL_DATE,
CREATED_DATE,
UPDATED_DATE
Minimum string length: 1
​
endDate
string<date>

Optional end date for the usage data in YYYY-MM-DD format (inclusive). If provided, filters for data on or before this date.

​
identifier
string
default:""

Filter meters by identifier value. Searches across all identifiers.

Minimum string length: 1
​
page
integer
default:1

Page number for paginated results. Default is 1.

​
startDate
string<date>

Optional start date for the usage data in YYYY-MM-DD format (inclusive). If provided, filters for data on or after this date.

Response

Serializer for usage data response.

​
totalUsageData
integer
required

Total number of usage data entries.

​
perPage
integer
required

Number of entries per page.

​
totalPages
integer
required

Total number of pages.

​
currentPage
integer
required

Current page number.

​
hasNext
boolean
required

Indicates if there is a next page.

​
hasPrevious
boolean
required

Indicates if there is a previous page.

​
usageData
object[]
required

List of usage data entries.