Monthly utility cost, energy and carbon by resource

Changed on

Aggregates emission rows classified with the given usage (default building) by calendar month (UTC) and utility resource. Each row covers the days from its start date to its end date, both inclusive; its energy, carbon, quantities and costs are pro-rated over the months it covers by days, and only the days inside the requested range count (a row ending before it starts stays in its start month). Costs are split into energy cost (carbon rows) and other charges (standing charges, levies) per currency. Rows of soft-deleted source records are excluded. The missing-cost list still counts rows by start month. At most 120 months. Reporting currency: with currency in the request, or else the organization's reporting currency (GET /v1/organization/settings), each month's cost shares are converted into that currency at ECB euro reference rates (cross rates via EUR) after the site filter and the day split: rateBasis bill_date uses the rate of the row's start date (UTC), period_end the rate of the last day of the month the share falls in (also when the range ends inside the bill). A weekend or holiday takes the latest ECB rate on or before it (at most 14 days back); a day after today (the end of the current month) takes the latest published rate. Each row's costs is then one entry in the reporting currency, originalCosts keeps the amounts per original currency and conversions the rate of each amount; shares whose rate is missing (ECB unreachable, a currency the ECB does not publish, an unknown currency) are left out of costs, kept in originalCosts and listed in reporting.missingRates. Without a request currency and an organization reporting currency, nothing is converted and the response has no reporting, originalCosts or conversions. Unassigned spend is never converted. Missing rates are fetched from the ECB on demand: one ECB call at most per request.

post/utility/series

Request

  • Base URL
    https://api.greentally.ai/v1
  • Auth
    HTTP bearer

Request body

currencystring

Reporting currency (ISO 4217) to convert costs into, overriding the organization's. EUR or a currency the ECB publishes; others answer 400. Absent: the organization's reporting currency, or no conversion when it has none.

endMonthstring required
rateBasis'bill_date' | 'period_end'

Which day's rate converts a cost; absent = the organization's fxRateBasis (default bill_date).

siteIdsstring[]

Keep rows stamped with one of these sites (site_…); the value "unassigned" keeps rows with no site (entity-only rows included), as the canonical list's siteIds. The filter applies to the rows before they are split over months, and to every part of the series (rows, costs, quantities, coverage, grossBills, unassigned, unmatched). Absent or empty: every row. A site of another organization matches nothing. At most 100 values; more answer 400.

startMonthstring required
usage'building' | 'vehicle'

Which utility rows to aggregate (building energy and water, or vehicle fuel).

Example request

{
  "currency": "GBP",
  "endMonth": "2025-12",
  "startMonth": "2025-01"
}

Response

Utility series

Example response

{
  "data": {
    "endMonth": "2025-12",
    "reporting": {
      "currency": "EUR",
      "missingRates": [
        {
          "date": "2026-01-15"
        }
      ]
    },
    "rows": [
      {
        "conversions": [
          {
            "date": "2026-01-15",
            "rateDate": "2026-01-14"
          }
        ],
        "month": "2025-01"
      }
    ],
    "startMonth": "2025-01"
  }
}

Changes

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the new optional request property

    4 more changes in this revision