Filtering and query parameters

Most list endpoints in the Nectar API accept query parameters to filter the results. This guide covers the most commonly used filters.

Usage data filters

The usage data endpoints (/usage/company/{id}, /usage/site/{id}, etc.) support the following filters:

Parameter	Type	Description	Example
`startDate`	Date	Filter by start boundary (behavior depends on `dateType`)	`2025-01-01`
`endDate`	Date	Filter by end boundary (behavior depends on `dateType`)	`2025-12-31`
`dateType`	String	Which date field to filter on (default: `BILL_DATE`)	`USAGE_PERIOD`
`datasourceType`	String	Filter by utility type (accepts multiple values)	`ELECTRICITY`, `GAS`
`identifier`	String	Search across all meter identifiers (normalized — see below)	`0137746423`

Date type values

Value	Description
`BILL_DATE`	Filter by the invoice date on the document (default)
`USAGE_PERIOD`	Filter by the usage period start and end dates
`CREATED_DATE`	Filter by when the record was created
`UPDATED_DATE`	Filter by when the record was last updated

curl -X GET 'https://external.nectarclimate.com/v2.2/usage/company/{companyId}?startDate=2025-01-01&endDate=2025-12-31&datasourceType=ELECTRICITY' \
  -H 'X-API-Key: YOUR_SECRET_KEY'

import requests

response = requests.get(
    f"https://external.nectarclimate.com/v2.2/usage/company/{company_id}",
    headers={"X-API-Key": "YOUR_SECRET_KEY"},
    params={
        "startDate": "2025-01-01",
        "endDate": "2025-12-31",
        "datasourceType": "ELECTRICITY",
    },
)
usage_data = response.json()

Commodity types

Use these values for the datasourceType parameter:

Value	Commodity
`ELECTRICITY`	Electricity
`GAS`	Natural gas
`WATER`	Water (potable, well, municipal — not sewer)
`WASTE`	Waste
`FUEL`	Fuel (diesel, propane, etc.)
`SOLAR`	Solar
`SEWER`	Sewer / wastewater discharge
`STEAM`	Steam (district)
`CHILLED_WATER`	Chilled water (district)
`HOT_WATER`	Hot water (district)

On current API versions (v2.0, v2.1, and v2.2), sewer meters in responses are represented as datasourceType: "WATER" with waterType: "WASTE_WATER". First-class datasourceType: "SEWER" in response bodies is planned for a future API version. Filtering with datasourceType=WATER returns both water and sewer records on current versions — use meter-level fields to distinguish them in response payloads.

Identifier matching

The identifier filter normalizes both the search value and stored identifiers before comparing. Normalization removes dashes, spaces, underscores, commas, and forward slashes, strips leading zeros, and converts to uppercase. This means:

013-774-6423 matches 0137746423
137746423 matches 0137746423 (leading zeros are ignored)

Document filters

Document endpoints (/document/company/{id}, /document/site/{id}, etc.) support the same date, dateType, datasourceType, and identifier filters as usage data endpoints. Additionally:

Parameter	Type	Description
`isDeleted`	Boolean	Include soft-deleted documents (default: `false`)

Connection filters

Connection endpoints (/connection/company/{id}) support owner, status, and site filters:

Parameter	Type	Description
`connectionOwnerEmail`	String (email)	Filter by exact connection owner email
`sites`	UUID (repeatable)	Filter to connections linked to one or more sites
`status`	String	Filter by connection status (e.g., `CONNECTED`, `PASSWORD_INCORRECT`)

See Connection statuses for the full list of status values.

# Filter by owner and site
curl -X GET 'https://external.nectarclimate.com/v2.2/connection/company/{companyId}[email protected]&sites={siteId}' \
  -H 'X-API-Key: YOUR_SECRET_KEY'

Combining filters with pagination

All filters work alongside pagination parameters. The total in the response reflects the filtered count, not the unfiltered total.

# Get page 2 of electricity usage data for 2025
curl -X GET 'https://external.nectarclimate.com/v2.2/usage/company/{companyId}?startDate=2025-01-01&endDate=2025-12-31&datasourceType=ELECTRICITY&page=2' \
  -H 'X-API-Key: YOUR_SECRET_KEY'

Developer onboarding

Integration patterns

API reference guides

Data model and methodology

Usage data filters

Date type values

Commodity types

Identifier matching

Document filters

Connection filters

Next steps

Pagination

API Reference

​Usage data filters

​Date type values

​Commodity types

​Identifier matching

​Document filters

​Connection filters

​Combining filters with pagination

​Next steps

Pagination

API Reference

Usage data filters

Date type values

Commodity types

Identifier matching

Document filters

Connection filters

Combining filters with pagination

Next steps