BAFUquery
BAFUQ.eco · Swiss LCA data platform

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.

Base path /v1
Activities 7,673
Products 11,947
Indicators 127 in 11 impact methods
Auth Bearer + Ed25519
Proof of concept — read before integrating

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:

MarkerMeans
public keyAny 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.

POST /v1/estimate public key

Impacts for a quantity of one dataset, optionally in a scenario year and another geography.

Request

FieldTypeNotes
dataset.uidstring Required. BAFU_<uuid> or the bare uuid.
dataset.data_versionint │ string Integer, or "^N" for the newest in series N. Omitting raises a notice.
parameters.amountfloat > 0 Defaults to one reference unit.
parameters.unitstring Must belong to the dataset's unit type. See /v1/unit-types.
scenario.sourcestring ep2050plus, owid, …
scenario.namestringA scenario within that source.
scenario.yearint1990–2100, inside the source's coverage.
location.regionstring A BAFU location code — two letters for a country.
location.scopestring generic (default) or all.
indicatorsstring[] Method keys from /v1/methods. Omit for the headline set.
includestring[] 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

POST/v1/estimate/batch public key

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.

Vocabulary endpoints

Everything a request may name, published so a client never has to guess and never has to hard-code.

GET /v1/methodspublic key

127 indicators in 11 impact methods, each with the key to name in indicators[]. ?impact_method= restricts to one.

GET /v1/unit-typespublic key

The closed set of units you may send, by unit type.

GET /v1/geographiespublic key

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.

GET /v1/scenariospublic key

Sources, their scenarios, and the years each covers.

GET /v1/data-versionspublic key

What each version pins, and whether the live state still matches its fingerprint.

GET /v1/datasets/{uid}public key

One dataset: identity, reference unit, and the units accepted for it.

GET /v1/usagepublic key

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.

ScopeMoves
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.

GET /v1/flowsaudit key

Resolve the indices an inventory carries. Stable for a data version.

GET /v1/log/tree-headaudit key

Root hash and size, signed. The anchor everything else is checked against.

GET /v1/log/proofaudit key

Inclusion proof for leaf_index — log₂(n) hashes, 24 at ten million entries. Optional tree_size.

GET /v1/log/consistencyaudit key

Proof between old_size and new_size — the one that catches a rewritten past.

GET /v1/log/entriesaudit key

Hashes and timestamps only — never a receipt body, never a query. start, limit ≤ 500.

POST /v1/receipts/verifyaudit key

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.

GET /v1/datasets/{uid}/qualityaudit key

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.

POST /v1/reviewssigned

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.

POST /v1/keysaudit key

Enrol the key a principal will sign requests with — an ssh-ed25519 line, or base64 of the 32 raw public bytes.

POST /v1/restricted-datasetsaudit key

Put a dataset outside the published background. kind is supplier_primary or commissioned.

POST /v1/grantsaudit key

Grant scores, lci or unit_process on one restricted dataset. A mandate names who authorised it, for what scope, and until when.

DELETE /v1/grants/{grant_id}audit key

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": "…" }
CodeHTTPMeaning
missing_credentials401No Authorization header.
invalid_credentials401Key not recognised.
tier_required403Audit tier needed for this route or include.
disclosure_denied403Your level is below what was asked. Carries your_disclosure and required.
signature_required403This delivery needs a signed request.
invalid_signature403Signature did not verify.
signature_expired403created is outside the accepted window.
signature_replayed403Nonce already seen.
unknown_dataset404No such UID — or it is restricted and invisible to you.
invalid_uid400Not a BAFU UID or bare uuid.
unknown_indicator400Not a key from /v1/methods.
invalid_unit400Unit outside the dataset's unit type.
invalid_unit_type400Unit type not among the twelve.
unknown_data_version400No such version.
invalid_input400Schema violation; carries loc and msg.
batch_limit_exceeded400More than 100 operations.
no_datasets_found404A search that matched nothing.
functionality_unsupported400Asked for something this build does not do.
quota_exceeded429Period allowance spent.
temporarily_rate_limited429Slow down; retry.
engine_unavailable503bw2calc or the graph is not ready.
index_unavailable503Search index still building.
internal_error500Report 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…" } ]
CodeRaised when
data_version_defaultedYou did not pin a version. Always.
relocation_not_appliedNo input has a variant at the target; the unmodified database answered.
scenario_out_of_regionThe year and geography compose, but the shipped scenario covers Switzerland only.
lci_flow_unresolvedSome 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.

AreaWhere 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.