API reference
An HTTP API over the BAFU 2026 v1 life-cycle inventory, in two tiers: a public tier that answers how much, and an audit tier that answers and here is how to check it.
This platform is an unvalidated prototype. Impact scores are recomputed live with bw2calc and do not reproduce the values the BAFU publishes: across the catalogue the median climate-change result sits about 6 % below the published figure, and Ecological Scarcity totals diverge further. Treat every figure this API returns as indicative, and cite the BAFU:2026 database itself as the reference.
On availability: the explorer routes under /api/* answer here today;
/v1 is documented ahead of its release and may not yet be enabled on the
instance you are calling. Check with GET /v1/data-versions — if it 404s,
this build does not serve it yet.
Overview
Every figure is computed live with bw2calc from the Brightway
BAFU_2026_v1 database — no impact values are stored and replayed.
A request names a dataset and a quantity; the response carries the characterised indicators, what the answer depended on, and anything you should know that does not invalidate it. Two request-time modifiers compose with any estimate: a scenario year rewrites the electricity mixes, and a geography serves the inputs that cannot be transported from somewhere else. Neither writes anything — both are patches applied to the technosphere matrix for the duration of one solve.
Quickstart
# The headline indicators for 1 tonne of Portland cement curl -s https://bafuq.eco/v1/estimate \ -H "Authorization: Bearer $BAFUQ_KEY" \ -H "Content-Type: application/json" \ -d '{ "dataset": {"uid": "BAFU_b9430f24-d0b9-3422-a5ad-f874acbbef18", "data_version": "^1"}, "parameters": {"amount": 1000, "unit": "kg"} }'
Which surface you are calling
This reference documents /v1. The routes under /api/* are the
private back end of this explorer — unauthenticated, undocumented as a contract, and free
to change without notice. They are listed at the end so you can recognise them, not so you
can build on them.
Authentication
Every /v1 route requires a key. Some require more than a key.
Authorization: Bearer <key>
A bearer token identifies a caller; it does not commit them. If one leaks, its owner is indistinguishable from the thief — acceptable for asking how much, not acceptable for delivering an inventory. So the routes that disclose the inventory require an RFC 9421 signed request on top of the key. Each endpoint below carries the access it needs:
| Marker | Means |
|---|---|
| public key | Any valid key. |
| audit key | A key enrolled in the audit tier. A public key gets tier_required. |
| signed | Audit key and an Ed25519 request signature. See Signed requests. |
Core concepts
Five decisions shape every response. Worth five minutes before the first integration.
A dataset is named by its BAFU UID
BAFU_<uuid>, where the uuid is the one in the EcoSpold filename carried
through the import. All 11,947 activities carry it, with no exceptions, so the public
identity comes from the source rather than from a convention that would need defending. A
bare uuid is accepted and canonicalised.
A dataset we produce gets its own identifier
A scenario year or a relocation makes the answer a different inventory, so it is
returned as DERIV_<uuid> with derived_from pointing at the
original. The uuid is a UUIDv5 over a canonical string of
(source_uid, data_version, source, scenario, year, region, scope) —
deterministic, so you can recompute it, and two clients asking the same question get the
same identifier. The quantity is deliberately not part of it: 1 kg and 500 kg of
the same relocated cement are the same dataset.
data_version pins four things
A reproducible figure depends on the BAFU database, the registered LCIA methods, the
ingested scenario tables and the geography tables. One integer pins all four.
GET /v1/data-versions publishes the composition and a fingerprint of the live
state; a version whose fingerprint no longer matches reports drifted, and every
answer says so. Pass "^1" for the newest in a series.
Omitting it is allowed and always raises a notice. A caller who does not pin a version has not opted out of reproducibility — they have merely not noticed.
The server converts units, because the conversion is exact
Attributional LCA is linear in the functional unit, so 100 kg is 100× the reference flow.
That is arithmetic, not an approximation. Twelve unit types are derived from the sixteen
reference units the database carries; GET /v1/unit-types is the closed set you
may send. NormalVolume is deliberately separate from Volume:
turning a normal cubic metre into a cubic metre needs a gas and a state this API does not
know.
An unknown vocabulary value is refused, never absorbed
BAFU spells geography in two-letter codes, so location.region = "IND" is a
400 carrying did_you_mean: ["IN"] — not an empty relocation
reporting applied: false, which is indistinguishable from a geography that
genuinely cannot move. Likewise a year outside a source's coverage raises
scenario_year_out_of_range rather than silently answering with the nearest
year.
Estimate
The centre of the API. Everything else exists to tell you what you may put in this request, or how to check what came out of it.
Impacts for a quantity of one dataset, optionally in a scenario year and another geography.
Request
| Field | Type | Notes |
|---|---|---|
dataset.uid | string | Required. BAFU_<uuid> or the bare uuid. |
dataset.data_version | int │ string | Integer, or "^N" for the newest in series N. Omitting raises a notice. |
parameters.amount | float > 0 | Defaults to one reference unit. |
parameters.unit | string | Must belong to the dataset's unit type. See /v1/unit-types. |
scenario.source | string | ep2050plus, owid, … |
scenario.name | string | A scenario within that source. |
scenario.year | int | 1990–2100, inside the source's coverage. |
location.region | string | A BAFU location code — two letters for a country. |
location.scope | string | generic (default) or all. |
indicators | string[] | Method keys from /v1/methods. Omit for the headline set. |
include | string[] | lci or exchanges — both gated. See
Disclosure levels. |
Response
{
"uid": "DERIV_2f1c…", // DERIV_ when a modifier applied
"derived_from": "BAFU_b9430f24…", // only on a derived result
"dataset": { /* identity, reference unit, accepted units */ },
"requested": { "indicators": "headline", "include": [] },
"activity_data":{ "amount": 1000, "unit": "kg" },
"results": [
{ "key": "EF v3.1|climate change|global warming potential (GWP100)",
"impact_method": "EF v3.1", "category": "climate change",
"value": 710.9, "unit": "kg CO2-Eq" }
],
"vintage": { /* present when scenario.year was given */ },
"geography": { /* present when location.region was given */ },
"access": { /* your disclosure level on this dataset */ },
"lci": { "flows": [...], "amounts": [...],
"resolve_with": "/v1/flows" }, // include=lci only
"receipt": { /* signed, with its Merkle log entry */ }, // with the inventory
"data_version": 1,
"engine": "bw2calc over the graph",
"notices": [ { "severity": "info", "code": "…", "message": "…" } ]
}
The inventory arrives as parallel flows and amounts arrays —
integer indices into a table that is stable for a data version, resolved once against
GET /v1/flows rather than repeated on every response.
Batch
Up to 100 estimate operations. Each succeeds or fails on its own, under one HTTP 200.
{ "operations": [ { /* an EstimateRequest */ }, … ] }
// →
{ "results": [ { "ok": true, "result": { … } },
{ "ok": false, "error": { "error_code": "unknown_dataset", … } } ],
"succeeded": 1, "failed": 1, "notices": [] }
A bad row does not sink the batch, and the HTTP status does not encode partial failure —
branch on ok per result. Exceeding the limit is
batch_limit_exceeded.
Search
One ranked query over names, synonyms, CAS numbers and HS codes. Each hit says why it matched and carries its UID.
| Parameter | Default | Notes |
|---|---|---|
query | — | Free text; also matches synonyms, CAS numbers and HS codes. |
geography | — | Filter by location code. |
category, sub_category | — | Facet filters. |
hs_chapter | — | Two-digit HS chapter. |
has_cas, has_hs | false | Restrict to classified entries. |
data_version | — | Pin the vocabulary being searched. |
page | 1 | ≥ 1. |
results_per_page | 20 | 1–200. |
Each response carries possible_filters, so a client can build facets without
knowing the schema in advance. Restricted datasets never appear here — see
Disclosure levels.
Vocabulary endpoints
Everything a request may name, published so a client never has to guess and never has to hard-code.
127 indicators in 11 impact methods, each with the key to name in
indicators[]. ?impact_method= restricts to one.
The closed set of units you may send, by unit type.
Every code location.region accepts, with how well BAFU can actually serve
it — native_families and has_grid say whether relocating there
will move anything.
Sources, their scenarios, and the years each covers.
What each version pins, and whether the live state still matches its fingerprint.
One dataset: identity, reference unit, and the units accepted for it.
This key's consumption for the current period.
Scenario year
Rewrites the electricity mixes to a projected year before the inventory is solved, so the score is prospective.
"scenario": { "source": "ep2050plus", "name": "ZERO-Basis", "year": 2050 }
The response gains a vintage block naming the source, the scenario and what
the database could not represent. Asking for a year outside the source's coverage is an
error, not a silent nearest-year answer: OWID stops at 2025.
Geography
Computes the same product as if it were produced somewhere else.
Every input that cannot be transported — electricity, heat, water, wastewater, waste treatment, on-site services, immovable infrastructure — is served from the target, or from the nearest thing to it the database can serve. Traded commodities keep the origin they have, because where a plant stands says nothing about where its steel comes from.
| Scope | Moves |
|---|---|
generic |
Default. An input only moves if it currently sits at the activity's own location or at a region containing it — the part of the chain modelled as "here" or "generically European". Chilean copper keeps Chilean electricity. |
all |
Every non-tradable input, wherever it sits. Answers the broader "what if all of this happened in X". |
Read responsiveness first
A score that barely moved and a geography that makes no difference look identical.
geography.responsiveness separates them: it reports how much of the chain's
electricity the relocation actually reached. Portland cement [CH] relocated
to IN reaches 83.4% and moves +12.0%; a dataset aggregated at RER with no
electricity input of its own reaches almost nothing and returns the number you already
had.
Trade linking
Serves traded inputs from the countries that actually supply them, weighted by recorded trade.
Geography moves what cannot travel. Trade linking answers the other half: for a traded commodity with more than one origin in the database, consumption is redirected onto a weighted blend of the supplying countries, in the shares the BACI trade records give — the approach Regioinvent takes to the same question, computed here at request time rather than baked into a database.
Which year's import structure to read is a separate parameter from the scenario year, on
purpose: one says where goods came from, the other says how electricity will be generated.
Omitted, it resolves to the most recent year loaded, and the response reports which year
answered and how it was reached — exact, nearest or
latest.
Availability
Trade linking is exposed on the explorer routes
(?trade_linked=true&trade_year=). It is not yet a /v1
parameter, and the weighting has not been validated against a production graph — treat
any figure it produces as provisional.
Disclosure levels
Three levels, and the middle one carries the design.
- scores
- The characterised indicators — what this explorer shows. Public tier.
- lci
- Adds the aggregated inventory: 1,118 elementary flows, summed over the whole chain. Audit tier, entitled, signed.
- unit_process
- Adds the technosphere exchanges — the recipe. The owner, or a verifier acting under a recorded mandate.
The gap between lci and unit_process is what makes confidential
supplier data workable. A customer who asks a supplier for primary data gets a result they
can fully audit — recompute any method, check the arithmetic — while the supplier's bill of
materials never leaves. This is not approximate redaction: an aggregated inventory is a sum
over the chain and carries no decomposition, and because attributional LCA is linear,
querying it at different quantities reveals nothing further. It mirrors the ISO/ILCD
distinction between a unit process and an aggregated LCI result, which is how EPD
programmes have handled this for twenty years.
A restricted dataset is invisible, not forbidden
It returns 404 and never appears in search — never 403. For
commissioned work the existence of the dataset is itself confidential, and
"access denied" would tell a competitor that a supplier delivered something. Restricted
datasets also never join the shared background: if a supplier improves one customer's
data, another customer querying a generic product sees nothing move.
Signed requests
Non-repudiation, not just authentication.
The inventory is delivered only against an RFC 9421 signed request:
Ed25519, covering @method, @target-uri and
content-digest, with created and nonce against
replay. Nothing — including the operator — can then write a log entry claiming you asked for
something you did not.
An ssh-ed25519 public key is an Ed25519 key, so you register the
~/.ssh/id_ed25519.pub you already have and sign with
ssh-keygen -Y sign. The key, yes; the SSH transport, no.
Signature-Input: sig1=("@method" "@target-uri" "content-digest");\ created=1789330000;nonce="…";keyid="k_9f3c…" Signature: sig1=:MEUCIQD…: Content-Digest: sha-256=:X48E9qOok…:
Failures are explicit: signature_required, invalid_signature,
signature_expired, signature_replayed.
Receipts and the transparency log
Evidence without a blockchain.
Every delivery carries a 377-byte Ed25519 receipt — hashes of the inventory and the results, never the payloads, so it can be published without disclosing what it attests to. Receipt hashes are leaves of an append-only Merkle log (RFC 6962) with inclusion and consistency proofs; one signed tree head per hour covers every receipt in that hour, so anchoring costs about 8,760 items a year at any traffic level. Log leaves are hashes, so the log is publishable without revealing who asked what — necessary, because a customer's queries are their industrial strategy.
Resolve the indices an inventory carries. Stable for a data version.
Root hash and size, signed. The anchor everything else is checked against.
Inclusion proof for leaf_index — log₂(n) hashes, 24 at ten million entries.
Optional tree_size.
Proof between old_size and new_size — the one that catches a
rewritten past.
Hashes and timestamps only — never a receipt body, never a query. start,
limit ≤ 500.
Convenience only — you are expected to verify a receipt yourself, against a tree head you kept.
Stated limit
A transparency log proves provenance and non-rewriting, never correctness.
Correctness comes from the pinned data_version and from the inventory itself:
with the LCI, an auditor recomputes and checks us. That is what makes gating the inventory
coherent rather than defensive — verification power goes to the people whose job it
is.
Data quality
PEF/ILCD Data Quality Rating, not a scheme of our own.
The computed rating, plus the signed review if one stands. Optional
claim_year and claim_location rate the dataset against your
intended use rather than in the abstract.
A verifier files a verdict, signed with their own key.
TiR (time) and GeR (geography) are computed —
from the dataset vintage, and from the geography hierarchy rebuilt from BAFU's own regional
mixes. TeR (technology) and P (precision) can only be
declared. Undeclared criteria score at the neutral midpoint and are flagged
source: absent: a rating resting on them is not evidence.
Over that sits a verdict a named verifier signs with their own key, checked before storage and appended to the log so it cannot be quietly withdrawn. A review we could have written ourselves is worth our own opinion — which is what an independent review exists not to be.
Access administration
Enrolling keys, restricting datasets, and granting disclosure.
Enrol the key a principal will sign requests with — an ssh-ed25519 line, or
base64 of the 32 raw public bytes.
Put a dataset outside the published background. kind is
supplier_primary or commissioned.
Grant scores, lci or unit_process on one
restricted dataset. A mandate names who authorised it, for what scope, and
until when.
Revocation is forward-looking: receipts already issued stay valid, because they attest to a delivery that did happen.
The verifier paradox. A real quality review cannot be done on an aggregated inventory — judging technological representativeness needs the unit process. So the reviewer must see precisely what the customer must not. That third role is granted through a mandate, so the trail can always answer by whose authority.
Errors
One envelope for every failure. Branch on error_code; never parse
prose.
{ "error": true,
"error_code": "invalid_unit",
"message": "kWh is not a unit of Mass.",
"valid_values": { "unit": ["kg", "g", "t"] },
"request_id": "…" }
| Code | HTTP | Meaning |
|---|---|---|
missing_credentials | 401 | No Authorization header. |
invalid_credentials | 401 | Key not recognised. |
tier_required | 403 | Audit tier needed for this route or include. |
disclosure_denied | 403 | Your level is below what was asked. Carries your_disclosure and required. |
signature_required | 403 | This delivery needs a signed request. |
invalid_signature | 403 | Signature did not verify. |
signature_expired | 403 | created is outside the accepted window. |
signature_replayed | 403 | Nonce already seen. |
unknown_dataset | 404 | No such UID — or it is restricted and invisible to you. |
invalid_uid | 400 | Not a BAFU UID or bare uuid. |
unknown_indicator | 400 | Not a key from /v1/methods. |
invalid_unit | 400 | Unit outside the dataset's unit type. |
invalid_unit_type | 400 | Unit type not among the twelve. |
unknown_data_version | 400 | No such version. |
invalid_input | 400 | Schema violation; carries loc and msg. |
batch_limit_exceeded | 400 | More than 100 operations. |
no_datasets_found | 404 | A search that matched nothing. |
functionality_unsupported | 400 | Asked for something this build does not do. |
quota_exceeded | 429 | Period allowance spent. |
temporarily_rate_limited | 429 | Slow down; retry. |
engine_unavailable | 503 | bw2calc or the graph is not ready. |
index_unavailable | 503 | Search index still building. |
internal_error | 500 | Report it with the request_id. |
Notices
Things you should know that do not invalidate the answer.
"notices": [ { "severity": "warning",
"code": "relocation_not_applied",
"message": "No input of this dataset has a variant for PL…" } ]
| Code | Raised when |
|---|---|
data_version_defaulted | You did not pin a version. Always. |
relocation_not_applied | No input has a variant at the target; the unmodified database answered. |
scenario_out_of_region | The year and geography compose, but the shipped scenario covers Switzerland only. |
lci_flow_unresolved | Some elementary flows are not in the reference table and were omitted. |
Explorer routes
Listed so you recognise them — not a contract.
The routes under /api/* are the private back end of this explorer: no
authentication, shapes tuned to one screen, and free to change whenever that screen does.
Build on /v1.
One of them is genuinely useful to know about, because /v1 has no equivalent
yet: GET /api/item/{id} returns the exchange list, split into
inputs (technosphere, each with the producer_id of whoever makes
it) and outputs (the reference product plus elementary flows, tagged with
compartment). For 1-pentanol, at plant [RER] that is 12 inputs —
0.616 kg butene among them — and 12 outputs, including 0.0097 kg BOD5 to river water. It is
an ETL-sourced view keyed to readable flow names, not the uuid-indexed matrix the solver
uses; same underlying data, different representation.
The rest: /api/search, /api/suggest,
/api/item/{id}/lcia, /api/item/{id}/geographies,
/api/lcia/methods, /api/scenarios, /api/geographies,
/api/datasets, /api/products, /api/flow/{id},
/api/risks, /api/trades, /api/country/{id},
/api/stats, /api/health.
Limits and known gaps
Stated here rather than discovered in production.
| Area | Where it stands |
|---|---|
| External anchoring | Not configured. Append-only-ness holds only against tree heads you kept yourself,
and /v1/log/tree-head says so in its own response. |
| Scenario coverage | The shipped scenario source is Swiss-only. Relocating out of Switzerland moves the chain onto mixes it does not project, and the year stops changing the result. |
| Aggregated datasets | A dataset aggregated at RER often carries no electricity to move — geography can
barely act on it. Reported through responsiveness rather than
hidden. |
| Trade granularity | Trade records are aggregated to two-digit HS chapters, coarser than the six-digit detail the source publishes. |
| Solve cache | No persistent cache: a cold repeat of an identical query is recomputed. |
| Supplier ingestion | The access layer restricts datasets that already exist in the background; ingesting supplier datasets as first-class objects is not built. |