GreenCalculusGreenCalculusQuickstartGet a key

Quickstart

Your first carbon API call, in about five minutes.

Get a free key, describe the factor you need, look it up, then run a real calculation — each result traceable to its source. Plain HTTPS below; official Python and JavaScript clients if you want them.

Optional. Paste it and every example below becomes copy-paste ready — and runnable. It stays in this browser.

Try it right now — no key needed

Browsing the corpus is open. This is a real request against live data; press Run, or paste it into a terminal.

no key required
curl "https://api.greencalculus.com/v1/factors?search=uk+grid+electricity&limit=1"

You get 0.13096 kg CO2e per kWh — and source.cell_ref telling you it was read from 'UK electricity'!E25 of DEFRA 2026, with the date it was retrieved. That is the part nothing else gives you: every number can be traced back to the cell it came from.

A key unlocks the calculation engines and single-factor lookups. It takes one field and no card — get one →

1

Get a free API key

No credit card. The free tier includes 1,000 calls a month. Grab a key → then keep it handy as an environment variable:

shell
# paste the key you were given
export GC_KEY="gc_live_your_key_here"
2

Find the right factor

Not sure which of 16,554 keys you need? Describe what you’re measuring and resolve ranks the best matches — the very tool your AI agent uses. Feed the top key into the next step.

request
curl -s -X POST https://api.greencalculus.com/v1/calculate/resolve \
  -H "Authorization: Bearer $GC_KEY" -H "Content-Type: application/json" \
  -d '{ "description": "UK grid electricity", "limit": 3 }'
200 OK
{
  "matches": [
    { "key": "grid.gbr.electricity.location_based",
      "name": "UK grid electricity — location-based (generation)",
      "value": 0.13096, "unit": "kg CO2e per kWh",
      "confidence": 1, "geo_match": "exact" }
  ],
  "count": 2
}  // abridged — each match also carries its section, source and scope

Take the top key straight into the next step.

3

Look up a factor

Every value comes back with its exact source cell and data version — nothing is a black box.

request
# Ask for one factor by its key — get the value AND where it came from.
curl https://api.greencalculus.com/v1/factors/grid.gbr.electricity.location_based \
  -H "Authorization: Bearer $GC_KEY"
200 OK
{ "factor": { "factor": { "value": 0.13096, "unit": "kg CO2e per kWh" },
             "source": { "id": "DEFRA_2026", "cell_ref": "'UK electricity'!E25" } } }
4

Run a calculation

The calculation engine is on every tier, including free. Here’s PCAF financed emissions — send holdings, get each attribution factor, the total, and the audit trail.

request
# POST activity data → get a compliant result with the full working.
curl -X POST https://api.greencalculus.com/v1/calculate/pcaf \
  -H "Authorization: Bearer $GC_KEY" -H "Content-Type: application/json" \
  -d '{ "holdings": [{ "outstanding_amount": 1000000,
        "denominator": {"type":"evic","value":2500000000000},
        "company_emissions": {"value":20000000} }] }'
200 OK
{
  "portfolio": { "financed_emissions": { "value": 1284.6, "unit": "t CO2e" },
                 "data_quality_score": 3.0 },
  "holdings": [
    { "id": "acme", "attribution_factor": 0.042,
      "financed_emissions": { "value": 1284.6, "unit": "t CO2e" } }
  ],
  "audit": { "formula": "outstanding / EVIC \u00d7 company emissions",
             "source": "PCAF Standard Part A" },
  "receipt": { "id": "gcr_9f2c\u2026" }
}

Every figure carries its formula, its source and a reproducible receipt. That is the whole point — an auditor can recompute it.

5

If something comes back wrong

Every error is the same shape on every endpoint, so you never branch on which layer failed — read error.code and act on it.

401
{ "error": { "code": "unauthorized",
            "message": "Missing or invalid API key.",
            "docs": "https://greencalculus.com/developers/docs/#errors" } }

401 — the key is missing, mistyped, or you rotated it. 429 — you hit the per-minute burst or the monthly quota; honour Retry-After, and your account shows which limit you are near and when it resets. 422 — the request is well-formed but not calculable, usually an unknown factor key; a 404 on a lookup returns candidate keys rather than a dead end. Full list in the error reference.

6

Use it from your language

It’s just HTTPS + JSON, so any language works — Python or JavaScript, for example:

There are official clients if you would rather not hand-roll one: npm install greencalculus or pip install greencalculus (MIT, zero dependencies, source). Both wrap every endpoint below, and there is a Postman collection in the same repo.

first_call.py
# Python — same first request.
import os, requests
r = requests.get(
  "https://api.greencalculus.com/v1/factors/grid.gbr.electricity.location_based",
  headers={"Authorization": f"Bearer {os.environ['GC_KEY']}"},
)
print(r.json())
first-call.js
// JavaScript — same first request.
const res = await fetch(
  "https://api.greencalculus.com/v1/factors/grid.gbr.electricity.location_based",
  { headers: { Authorization: `Bearer ${process.env.GC_KEY}` } }
);
console.log(await res.json());

Next: build something real in a lunch break with the tutorials, read the full API reference, or wire up the MCP server for AI agents.