greencalculus-com Bulk API

openapi: 3.2.0
info:
  title: GreenCalculus Bulk API
  version: v1
  description: 'Sourced greenhouse-gas emission factors and audit-traced carbon calculations. Every value returns with its exact source reference and data version — reproducible and citable. Free key at https://greencalculus.com/developers/.


    SCOPE: this document describes every endpoint we publish a callable example for — the data, calculation, discovery and watch endpoints. It deliberately excludes the control plane behind greencalculus.com (billing, sign-in, key management, admin), which is not a customer contract and is free to change, and /v1/account/webhook, whose configuration is session-only by design and therefore cannot be exercised with the bearer token this document describes. Those exclusions are enumerated and enforced by scripts/check-openapi-drift.mjs, so an endpoint is absent here because it was excluded, never because it was forgotten.'
  contact:
    name: GreenCalculus
    url: https://greencalculus.com/developers/
    email: jeremiah@greencalculus.com
  license:
    name: Attribution required except on Enterprise
    url: https://greencalculus.com/developers/docs/#attribution
servers:
- url: https://api.greencalculus.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Bulk
  description: Consolidated corpus feed
paths:
  /v1/corpus:
    get:
      tags:
      - Bulk
      summary: Full consolidated factor feed (Business plan and above)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: All factors with values + provenance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Corpus'
        '403':
          description: Requires Business plan
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      operationId: getV1Corpus
      x-operation-id-source: derived
components:
  schemas:
    Error:
      type: object
      description: The single error envelope, on every non-2xx response from every endpoint. Stated on /developers/docs and enforced at the gateway for origin-raised errors too — read the code from error.code.
      required:
      - error
      additionalProperties: true
      properties:
        error:
          type: object
          required:
          - code
          - message
          additionalProperties: true
          properties:
            code:
              type: string
              description: 'Stable machine-readable code. Transport-level: unauthorized, forbidden_tier, not_found, rate_limited, quota_exceeded, overage_cap_reached, busy, origin_unavailable, invalid_request. Validation codes are namespaced gc_* and named per endpoint (gc_unknown_param, gc_limit_too_large, gc_offset_invalid, gc_cursor_invalid, gc_section_conflict, and the per-engine gc_<engine>_* set).'
              example: gc_unknown_param
            message:
              type: string
              description: Human-readable and specific — a 4xx names the offending parameter and lists the accepted set.
              example: 'Unknown query parameter: bogus. This endpoint accepts: offset, cursor, limit, section, key_prefix, family, search. Free-text lookup is ?search=.'
            docs:
              type: string
              format: uri
              example: https://greencalculus.com/developers/docs/#errors
            details:
              type: object
              additionalProperties: true
              description: Present only when the failing endpoint attached structured detail beyond the HTTP status.
    Corpus:
      type: object
      description: 'Bulk feed, Business and above. Redistributable rows ONLY — filtering is driven by a per-source licence tier recorded against the data, and a source whose position has not been assessed is withheld. Every row carries redistributable: true so you can verify what you received.'
      additionalProperties: true
      properties:
        meta:
          type: object
          additionalProperties: true
        factors:
          type: array
          items:
            $ref: '#/components/schemas/FactorRow'
    FactorCitation:
      type: object
      description: 'The canonical citation for one factor row, built by the API (src/citation.ts) and printed VERBATIM by every official client (Sheets add-in, JS and Python SDKs, MCP). Format: "<factor name>. <source name> — <publisher>, cell <cell_ref>, retrieved <date>. via GreenCalculus data version <version>, factor <key>. <proof URL>". On GET /v1/factors/{key} the version is the one actually SERVED, so a ?as_of= lookup cites the pin. Present on rows from 2026-09-09. The format is a published specification, free for anyone to implement against their own data: https://greencalculus.com/developers/citation/'
      externalDocs:
        description: The factor citation specification
        url: https://greencalculus.com/developers/citation/
      additionalProperties: true
      properties:
        text:
          type: string
          example: UK grid electricity — location-based (generation). UK Government GHG Conversion Factors 2026 — Department for Energy Security and Net Zero (DESNZ), cell 'UK electricity'!E25, retrieved 2026-06-18. via GreenCalculus data version 2026.186, factor grid.gbr.electricity.location_based. https://verify.greencalculus.com/grid.gbr.electricity.location_based@2026.186
        source_id:
          type:
          - string
          - 'null'
          example: DEFRA_2026
        cell_ref:
          type:
          - string
          - 'null'
          example: '''UK electricity''!E25'
        version:
          type:
          - string
          - 'null'
          example: '2026.186'
        proof_url:
          type:
          - string
          - 'null'
          example: https://verify.greencalculus.com/grid.gbr.electricity.location_based@2026.186
    Uncertainty:
      type:
      - object
      - 'null'
      additionalProperties: true
      description: The publisher's own stated range, never derived by us. null means NOT RECORDED — explicitly not a claim that no uncertainty exists.
      properties:
        low:
          type:
          - number
          - 'null'
        high:
          type:
          - number
          - 'null'
        basis:
          type:
          - string
          - 'null'
          example: published
        published_as:
          type:
          - string
          - 'null'
          description: The publisher's exact wording, e.g. "±30-50%".
    FactorRow:
      type: object
      description: 'One corpus row as returned by browse/search. Carries the full row INCLUDING factor.value — the browse endpoint is open and unmetered by design, because our data is overwhelmingly open-licensed at source and gating it would make this API worse than the original publisher. What a paid plan adds is the right to REDISTRIBUTE, not the ability to read. (Note: the MCP search_factors tool DOES project rows down to key/name/section — that projection is deliberate and specific to that tool.)'
      additionalProperties: true
      properties:
        key:
          type: string
          example: grid.gbr.electricity.location_based
        name:
          type:
          - string
          - 'null'
        section:
          type:
          - string
          - 'null'
          example: grid
        activity_type:
          type:
          - string
          - 'null'
          example: purchased_energy
        factor:
          type: object
          additionalProperties: true
          properties:
            value:
              type:
              - number
              - 'null'
            unit:
              type:
              - string
              - 'null'
              example: kg CO2e per kWh
            gas:
              type:
              - string
              - 'null'
              example: CO2e
            basis:
              type:
              - string
              - 'null'
            gwp_set:
              type:
              - string
              - 'null'
              example: AR5_100
            gwp_set_basis:
              type:
              - string
              - 'null'
              description: How we know the GWP set — "published" where the source states it, "inferred" where we deduced it. null means not recorded, which is deliberately NOT the same as published.
            country_iso3:
              type:
              - string
              - 'null'
              example: gbr
            uncertainty:
              $ref: '#/components/schemas/Uncertainty'
            uncertainty_basis:
              type:
              - string
              - 'null'
              description: '"none_published" means the publisher states plainly that no range exists. null means not recorded — a different fact from silence.'
        source:
          $ref: '#/components/schemas/SourceRef'
        scope:
          type:
          - object
          - 'null'
          additionalProperties: true
          properties:
            ghg_protocol:
              type:
              - string
              - 'null'
              example: scope2
            category:
              type:
              - string
              - 'null'
        components:
          type:
          - object
          - 'null'
          description: Per-gas decomposition keyed by gas (co2, ch4, n2o…), each with its own cell_ref. Lets a consumer re-base AR5↔AR6 without us.
          additionalProperties:
            type: object
            additionalProperties: true
        note:
          type:
          - string
          - 'null'
          description: Includes what the publisher did NOT provide, stated verbatim.
        citation:
          $ref: '#/components/schemas/FactorCitation'
        licence:
          type: object
          additionalProperties: true
          description: 'The licence this row is published under, and whether the Business redistribution grant covers it. Present on the open browse from MB v2026.181 — the full terms, the required credit and the publisher are listed once per source under meta.licences. Absent (not empty) where no licence is on record: an empty value would read as "no licence applies".'
          properties:
            name:
              type: string
              example: Open Government Licence v3.0
            redistributable:
              type: boolean
    SourceRef:
      type: object
      description: Provenance to the line. Carried on 100% of rows — where in the source document the value was read, not just which document. A workbook cell where the publisher ships a workbook (DEFRA); otherwise the table, annex clause or page they did ship (IPCC, CBAM, ECCC).
      additionalProperties: true
      properties:
        id:
          type: string
          example: DEFRA_2026
        cell_ref:
          type: string
          example: '''UK electricity''!E25'
        retrieved:
          type: string
          format: date
          example: '2026-06-18'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your API key, e.g. "Bearer gc_live_…". Get one free at https://greencalculus.com/developers/.
externalDocs:
  description: The factor citation specification — the line that travels with every number
  url: https://greencalculus.com/developers/citation/