diff --git a/CITATION.cff b/CITATION.cff index ac8ebc5..866957d 100644 --- a/CITATION.cff +++ b/CITATION.cff @@ -5,7 +5,7 @@ title: "GreenCalculus SDKs" abstract: > Official Python and JavaScript/TypeScript clients for the GreenCalculus carbon API, plus a Google Sheets add-in and a Postman collection. Every emission factor - returned carries the exact cell it was read from and the data version it was read + returned carries the exact place in the source it was read from and the data version it was read at, and every calculation returns its full working with a deterministic receipt hash, so a published figure can be reproduced and checked rather than trusted. The corpus reads without an API key. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2a25629..0601772 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -17,7 +17,7 @@ names often differ from what you'd guess. [Report a wrong value](https://github.com/greencalculus/greencalculus-sdk/issues/new?template=wrong-value.yml). A carbon figure that is quietly wrong is worse than one that is missing. Every factor carries a verification link (`citation.proof_url`) showing the publisher, -the document and the exact cell — if that cell doesn't say what we say it says, +the document and the exact place within it — if that place doesn't say what we say it says, we want to know, and we'd rather hear it in public. ## Code diff --git a/README.md b/README.md index 056b84e..1b944cf 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ [![smithery](https://smithery.ai/badge/greencalculus/api)](https://smithery.ai/servers/greencalculus/api) [![Google Workspace Marketplace](https://img.shields.io/badge/Google%20Sheets-add--on-34A853)](https://workspace.google.com/marketplace/app/greencalculus_emission_factors/172913449875) -Official client libraries for the **[GreenCalculus API](https://greencalculus.com/developers?ref=github-sdk)** — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with **the exact cell it came from and the data version it was read at**, so you return citable numbers instead of guesses. +Official client libraries for the **[GreenCalculus API](https://greencalculus.com/developers?ref=github-sdk)** — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with **the exact place in the source it came from and the data version it was read at**, so you return citable numbers instead of guesses. Not writing code? The same corpus is a spreadsheet formula: the **[Google Sheets add-on](https://workspace.google.com/marketplace/app/greencalculus_emission_factors/172913449875)** has been listed and Google-verified since 11 September 2026 — see [`sheets/`](./sheets). @@ -68,10 +68,10 @@ print(r["emissions"]["value"], r["source"]["id"]) ## What you get -- **16,000+ sourced factors** across grid, fuels, freight, refrigerants, AFOLU, CBAM, construction and spend-based EEIO. Every value returns its source cell, licence and uncertainty. +- **16,000+ sourced factors** across grid, fuels, freight, refrigerants, AFOLU, CBAM, construction and spend-based EEIO. Every value returns its source reference, licence and uncertainty. - **Seven calculation engines** — GHG Protocol activity, PCAF financed emissions, embodied EN 15978, electricity, freight, spend-based, business travel. The full working, never just a total. - **Reproducible** — a deterministic receipt hash on every result, and `as_of=` pins any factor to a past data version so a figure re-runs identically in an audit. -- **Checkable by the reader** — every factor has a permanent verification page showing the publisher, the document, the exact cell and whether it may be republished. +- **Checkable by the reader** — every factor has a permanent verification page showing the publisher, the document, the exact place within it and whether it may be republished. - **Agent-native** — the same data over MCP at `mcp.greencalculus.com`. ## Use it from an AI agent (MCP) diff --git a/js/README.md b/js/README.md index c4bb877..d956dd4 100644 --- a/js/README.md +++ b/js/README.md @@ -1,6 +1,6 @@ # greencalculus -The official JavaScript / TypeScript client for the [GreenCalculus API](https://greencalculus.com/developers?ref=npm) — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with the exact cell it came from and the data version it was read at. +The official JavaScript / TypeScript client for the [GreenCalculus API](https://greencalculus.com/developers?ref=npm) — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with the exact place in the source it came from and the data version it was read at. Zero dependencies. Uses the platform `fetch` (Node 18+ or any browser). Ships with TypeScript types. diff --git a/js/src/co2js.ts b/js/src/co2js.ts index 6be0226..f6b510e 100644 --- a/js/src/co2js.ts +++ b/js/src/co2js.ts @@ -3,7 +3,7 @@ * * CO2.js bundles one unversioned average per country (Ember). This helper * fetches the same quantity from GreenCalculus — with the publisher, the - * exact source cell, the data version and a public proof URL — and shapes it + * exact source reference, the data version and a public proof URL — and shapes it * as the `gridIntensity` option CO2.js already accepts, so a web-carbon * estimate can carry an audit trail. No dependency on @tgwf/co2; pass the * result into its `perVisitTrace` / `perByteTrace` options yourself. diff --git a/js/src/index.ts b/js/src/index.ts index 81cb83b..93b8439 100644 --- a/js/src/index.ts +++ b/js/src/index.ts @@ -2,7 +2,7 @@ * GreenCalculus — the carbon-accounting API. * * Sourced greenhouse-gas emission factors and audit-traced calculations, every - * value traceable to its source cell and data version. Zero dependencies (uses + * value traceable to its source reference and data version. Zero dependencies (uses * the platform `fetch`; Node 18+ or any browser). * * import { GreenCalculus } from "greencalculus"; @@ -146,7 +146,7 @@ export class GreenCalculus { /** * Browse the corpus — keyless, edge-cached. Full rows including the value, - * source cell and licence. Params: key_prefix, section, family, search, limit, offset, cursor. + * source reference and licence. Params: key_prefix, section, family, search, limit, offset, cursor. */ browse(params: Record = {}): Promise { return this.request("GET", "/v1/factors", { params }); diff --git a/postman/description.md b/postman/description.md index 5d2a8db..48077d2 100644 --- a/postman/description.md +++ b/postman/description.md @@ -1,6 +1,6 @@ **Emission factors you can cite, and calculations an auditor can re-run.** -16,000+ greenhouse-gas emission factors from 137 publishers — DEFRA, EPA, Ember, IPCC, ECCC, ÖKOBAUDAT. Every value comes back with the exact spreadsheet cell it was read from: +16,000+ greenhouse-gas emission factors from 137 publishers — DEFRA, EPA, Ember, IPCC, ECCC, ÖKOBAUDAT. Every value comes back with the exact place in the source it was read from — here, a spreadsheet cell: ```json "value": 0.13096, "unit": "kg CO2e per kWh", diff --git a/postman/greencalculus.postman_collection.json b/postman/greencalculus.postman_collection.json index 39be4d9..7d0526a 100644 --- a/postman/greencalculus.postman_collection.json +++ b/postman/greencalculus.postman_collection.json @@ -2,7 +2,7 @@ "info": { "_postman_id": "6230755a-8812-51b9-8803-8b2303d66ea8", "name": "GreenCalculus API", - "description": "**Emission factors you can cite, and calculations an auditor can re-run.**\n\n16,000+ greenhouse-gas emission factors from 137 publishers — DEFRA, EPA, Ember, IPCC, ECCC, ÖKOBAUDAT. Every value comes back with the exact spreadsheet cell it was read from:\n\n```json\n\"value\": 0.13096, \"unit\": \"kg CO2e per kWh\",\n\"source\": { \"cell_ref\": \"'UK electricity'!E25\", \"retrieved\": \"2026-06-18\" },\n\"licence\": { \"name\": \"Open Government Licence v3.0\", \"redistributable\": true },\n\"citation\": { \"proof_url\": \"https://verify.greencalculus.com/grid.gbr.electricity.location_based@2026.192\" }\n```\n\nThat proof link resolves the value **as it stood at that data version**. So a report re-run in eleven months lands on the same number instead of a quietly-revised one — and the reviewer who asks \"where did 0.13096 come from?\" gets a cell reference, not a shrug. Most carbon APIs hand you a figure and bury its origin.\n\n## Press Send right now\n\n**Ten of these 28 requests need no key and no signup.** Everything in **Discovery** is open: browse the corpus, read the change feed, check country coverage, and see which factors we deliberately *don't* hold and why. Open any of them and send it — nothing to configure.\n\n## For the other eighteen\n\nSet the `api_key` collection variable. Free, no card: **https://greencalculus.com/developers/**\n\nThat unlocks the calculation engines, which return the full working rather than a bare total — GHG Protocol activity, Scope 2 location + market, PCAF financed emissions, EN 15978 embodied carbon, GLEC freight, spend-based EEIO. Each response shows the factor used, its source, and the arithmetic.\n\n## For agents\n\nThe same corpus is an MCP server with twelve tools at `https://mcp.greencalculus.com`, on the official MCP registry as `com.greencalculus/api` — so a model can pull a sourced number mid-conversation instead of inventing one.\n\n---\n\nDocs: https://greencalculus.com/developers/docs/ · OpenAPI: https://api.greencalculus.com/openapi.json · SDKs for [Python and JavaScript](https://github.com/greencalculus/greencalculus-sdk) · [Google Sheets add-on](https://workspace.google.com/marketplace/app/greencalculus_emission_factors/172913449875)", + "description": "**Emission factors you can cite, and calculations an auditor can re-run.**\n\n16,000+ greenhouse-gas emission factors from 137 publishers — DEFRA, EPA, Ember, IPCC, ECCC, ÖKOBAUDAT. Every value comes back with the exact place in the source it was read from — here, a spreadsheet cell:\n\n```json\n\"value\": 0.13096, \"unit\": \"kg CO2e per kWh\",\n\"source\": { \"cell_ref\": \"'UK electricity'!E25\", \"retrieved\": \"2026-06-18\" },\n\"licence\": { \"name\": \"Open Government Licence v3.0\", \"redistributable\": true },\n\"citation\": { \"proof_url\": \"https://verify.greencalculus.com/grid.gbr.electricity.location_based@2026.192\" }\n```\n\nThat proof link resolves the value **as it stood at that data version**. So a report re-run in eleven months lands on the same number instead of a quietly-revised one — and the reviewer who asks \"where did 0.13096 come from?\" gets a cell reference, not a shrug. Most carbon APIs hand you a figure and bury its origin.\n\n## Press Send right now\n\n**Ten of these 28 requests need no key and no signup.** Everything in **Discovery** is open: browse the corpus, read the change feed, check country coverage, and see which factors we deliberately *don't* hold and why. Open any of them and send it — nothing to configure.\n\n## For the other eighteen\n\nSet the `api_key` collection variable. Free, no card: **https://greencalculus.com/developers/**\n\nThat unlocks the calculation engines, which return the full working rather than a bare total — GHG Protocol activity, Scope 2 location + market, PCAF financed emissions, EN 15978 embodied carbon, GLEC freight, spend-based EEIO. Each response shows the factor used, its source, and the arithmetic.\n\n## For agents\n\nThe same corpus is an MCP server with twelve tools at `https://mcp.greencalculus.com`, on the official MCP registry as `com.greencalculus/api` — so a model can pull a sourced number mid-conversation instead of inventing one.\n\n---\n\nDocs: https://greencalculus.com/developers/docs/ · OpenAPI: https://api.greencalculus.com/openapi.json · SDKs for [Python and JavaScript](https://github.com/greencalculus/greencalculus-sdk) · [Google Sheets add-on](https://workspace.google.com/marketplace/app/greencalculus_emission_factors/172913449875)", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { diff --git a/python/README.md b/python/README.md index c4f2594..4a9acd6 100644 --- a/python/README.md +++ b/python/README.md @@ -1,6 +1,6 @@ # greencalculus -The official Python client for the [GreenCalculus API](https://greencalculus.com/developers?ref=pypi) — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with the exact cell it came from and the data version it was read at, so you hand back citable numbers, not guesses. +The official Python client for the [GreenCalculus API](https://greencalculus.com/developers?ref=pypi) — sourced greenhouse-gas emission factors and audit-traced calculations. Every value comes back with the exact place in the source it came from and the data version it was read at, so you hand back citable numbers, not guesses. Zero third-party dependencies (standard library only). diff --git a/python/greencalculus/__init__.py b/python/greencalculus/__init__.py index f68c8fe..7594a26 100644 --- a/python/greencalculus/__init__.py +++ b/python/greencalculus/__init__.py @@ -1,7 +1,7 @@ """GreenCalculus — the carbon-accounting API. Sourced greenhouse-gas emission factors and audit-traced calculations, every -value traceable to its source cell and data version. +value traceable to its source reference and data version. from greencalculus import GreenCalculus @@ -166,7 +166,7 @@ def factor(self, key: str, as_of: Optional[str] = None) -> Dict[str, Any]: def browse(self, **params: Any) -> Dict[str, Any]: """Browse the corpus — keyless, edge-cached. Full rows including the - value, source cell and licence. + value, source reference and licence. Params: ``key_prefix``, ``section``, ``family``, ``search``, ``limit``, ``offset``, ``cursor``. diff --git a/sheets/README.md b/sheets/README.md index 6531039..e16f966 100644 --- a/sheets/README.md +++ b/sheets/README.md @@ -1,6 +1,6 @@ # GreenCalculus for Google Sheets -`=GC_FACTOR("grid.gbr.electricity.location_based")` → a sourced emission factor in a cell, with the publisher's exact source cell, the data version and a citation one column over. The spreadsheet is where carbon accounting actually happens; this puts cited factors inside it. +`=GC_FACTOR("grid.gbr.electricity.location_based")` → a sourced emission factor in a cell, with the publisher's exact source reference, the data version and a citation one column over. The spreadsheet is where carbon accounting actually happens; this puts cited factors inside it. Keyless by default — the GreenCalculus corpus is open to read. An API key (free) adds `as_of` version pinning. @@ -21,7 +21,7 @@ Find keys at [greencalculus.com/factors](https://greencalculus.com/factors/) or ## First run -Installing from the Marketplace opens the sidebar (`onInstall` runs in `AuthMode.FULL`, so it may). Until this user has tried it once, the sidebar leads with a one-line "why" (source cell, data version, citation, stays current) and one button, **Build me a starter sheet**: at the selected cell it writes a header row and two rows — UK grid electricity for 1,000 kWh and UK diesel for 500 litres — each with `=GC_EMISSIONS(key, amount)` and a linked short citation `=HYPERLINK(GC_FACTOR(key,"proof"), GC_CITE(key,"short"))`. Cited numbers in one click, no key needed. **Skip** hides the panel. The same block is under *Extensions → GreenCalculus → Build me a starter sheet*. Seen-state is per user (`GC_WELCOMED` in user properties), not per workbook. +Installing from the Marketplace opens the sidebar (`onInstall` runs in `AuthMode.FULL`, so it may). Until this user has tried it once, the sidebar leads with a one-line "why" (source reference, data version, citation, stays current) and one button, **Build me a starter sheet**: at the selected cell it writes a header row and two rows — UK grid electricity for 1,000 kWh and UK diesel for 500 litres — each with `=GC_EMISSIONS(key, amount)` and a linked short citation `=HYPERLINK(GC_FACTOR(key,"proof"), GC_CITE(key,"short"))`. Cited numbers in one click, no key needed. **Skip** hides the panel. The same block is under *Extensions → GreenCalculus → Build me a starter sheet*. Seen-state is per user (`GC_WELCOMED` in user properties), not per workbook. ## Sidebar (Extensions → GreenCalculus → Open GreenCalculus) diff --git a/sheets/Sidebar.html b/sheets/Sidebar.html index 31dd937..33c5496 100644 --- a/sheets/Sidebar.html +++ b/sheets/Sidebar.html @@ -48,7 +48,7 @@