GET /api/v1/
What this API is, where to start, and the daily allowance
Parameters: none
The HumanToll API
An API is a set of web addresses that programs can read instead of people. This one gives everything the pages show, in a machine-readable form (JSON), with the same details — free, with no account needed, and read-only.
Send GET requests to https://quiescence.eu/humantoll/api/v1/. Every response includes its status, scenario, calculation, method and data versions, the figures, the sources behind them with their licences, the licence the response may be reused under, warnings and a citation. Until a checked calculation is published, figures are held back and every response says so.
Where it stands
Figures are published. Each response names the calculation, scenario, method version and data version it reads.
Start here
GET /api/v1/— what the API is, its endpoints and the daily allowanceGET /api/v1/product/croissant— one product: deaths and injuries by both methods, its list of materials, and the chain it reachesGET /api/v1/compare?a=electric-car&b=petrol-car— two products calculated together: how many times larger one is, with its rangeGET /api/v1/spend?category=07&amount=250— €250 of EU households’ spending on transportGET /api/v1/openapi.json— this API as an OpenAPI 3.1 document
How to quote a figure
- With its range, every time: "an estimated 0.4–3.5 × 10⁻⁶ deaths per unit", never the central value alone.
- No more than two meaningful digits. A figure graded INDICATIVE has no central value (
valueis null,range_onlyis true). - Name the scenario, the calculation (run) and the method version, as every response does.
- Say "attributed to the supply chain of", never "caused by". Production phase only; every figure is a floor.
- Cite as the response’s
citationdoes: HumanToll <year>, run <id>, methodology v<version>. <page URL>
What every response carries
The same keys on every endpoint. A key is never missing; where it has no value it is null, and withheld says why.
status- published, preview (an operator’s view of an unpublished calculation) or withheld (no figure anywhere in the response).
scenario · run- The scenario, and the calculation the figures come from: its number, year, trade table and software version.
methodology_version · data_version- Which versions of the method and the data the calculation used.
metrics- One product’s figures: deaths and injuries, each by the materials method (per item, per kg) and the money method (per €1,000).
data- What the address itself returns, in three parts: facts from the project’s lists,
recordsfrom the publishers’ data, andresultsthe calculation produced. withheld- Every part that is not shown, and why: nothing is published yet, or a licence does not allow it.
sources- Every version of data behind the response, with its licence and the credit its licence asks for.
licence- What the response may be reused under: the strictest licence among its sources that requires reuse on the same terms. For any figure the model calculates, CC BY-NC-SA 3.0 IGO while WHO’s Global Health Estimates are among the sources.
caveats · citation- What the figures are not, and how to cite them.
A figure
Every figure is an object: value (the middle result, or null when the grade is INDICATIVE), low and high (the low and high ends of the range: the calculation is run 2,000 times with its uncertain inputs varied, and nine in ten results fall between them), confidence (HIGH, MEDIUM, LOW or INDICATIVE), range_only and unit. It is built by the same software that writes every figure on the pages, so the API cannot show a number the pages would refuse.
Endpoints
All GET. Scenario, where it applies, is one of S-MAX (the default), S-EVID, S-RES, S-ARMS and S-CONS. An unknown parameter is refused by name.
GET /api/v1/products
The product catalogue; with a published run, each product's deaths per unit and per kg
Parameters:
tier— semi_finished or finished.
one of:semi_finished·finishedcategory— A product category code, as each product's `category.code` gives it.sort— name, toll (deaths per kg on the material route), confidence or complete.
one of:name·toll·confidence·completescenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/product/{slug}
One product: both routes and both metrics, the bill of materials and the chain it reaches
Parameters:
slug(required) — The product's permanent slug, as in its page's address.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/product/{slug}/contributions
What carries one figure: its breakdown by material, country, conflict, channel or industry
Parameters:
slug(required) — The product's permanent slug, as in its page's address.metric— deaths or injuries.
one of:deaths·injuriesmethod— material (the route through the bill of materials) or mrio (per €1,000).
one of:material·mriotype— One breakdown; all of the route's when absent.
one of:material·country·conflict·channel·sectorscenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/product/{slug}/explain
The audit trail of one figure: every stage, each summing to the headline
Parameters:
slug(required) — The product's permanent slug, as in its page's address.metric— deaths or injuries.
one of:deaths·injuriesscenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/compare
Two products drawn together: the interval of their ratio, and a verdict only where it holds
Parameters:
a(required) — The first product's slug.b(required) — The second product's slug.metric— deaths or injuries.
one of:deaths·injuriesscenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/spend
EU households' spending on each consumption category: the harm in €amount, grouped against all spending
Parameters:
category— A COICOP 2018 category code; all of them when absent.amount— Euros spent; every figure and its interval scale with it.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/material/{slug}
A raw material: who produces it, which products use it, and what it carries in a run
Parameters:
slug(required) — The material's permanent slug, as in its page's address.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/conflict/{slug}
A scored conflict: the deaths UCDP counted, the model's attribution, and the products it reaches
Parameters:
slug(required) — The conflict's permanent slug, as in its page's address.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/country/{iso3}
A country: the harm counted there, and the products it reaches
Parameters:
iso3(required) — ISO 3166-1 alpha-3, in either case.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/channel/{code}
A harm channel: what it counts, how it is attributed, and what it reaches
Parameters:
code(required) — C1 conflict · C2 work · C3 deprivation · C4 exposure.scenario— The attribution scenario. The default is the published default (S-MAX).
one of:S-MAX·S-EVID·S-RES·S-ARMS·S-CONS
GET /api/v1/scenarios
The five attribution scenarios and their parameters
Parameters: none
GET /api/v1/runs
The published runs; none while figures are withheld
Parameters: none
GET /api/v1/runs/{id}
One published run and the verdict of each validation gate
Parameters:
id(required) — The run id a figure's citation names.
GET /api/v1/methodology
The versions of the methodology
Parameters: none
GET /api/v1/sources
The source register: every source, its licence, and the basis it is used on
Parameters: none
GET /api/v1/search
Find a product, material, conflict, country or channel
Parameters:
q(required) — Two to 64 characters.
GET /api/v1/openapi.json
This API as an OpenAPI 3.1 document, generated from the route table
Parameters: none
Errors
Real status codes, and one shape: {"ok": false, "error": {"code", "message", "detail"}}. The code is stable; detail names the parameter and what it accepts.
400- A parameter is missing, unknown or malformed.
401- A key was presented and is not valid — unknown, revoked or expired. It is refused, never served as if there were none.
404- No such address, product, material, war, country, kind of harm, kind of spending or published calculation.
405- Anything but GET, HEAD or OPTIONS.
429- This address has used its requests for today.
500- A fault on our side, logged. A figure that fails its own checks is a 500, never a number.
503- The database is unavailable.
The daily allowance
100 requests a day from one address, reset at 00:00 UTC; every response says how many remain (X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset). The OpenAPI document is not counted.
No internet address is stored. The count is kept under a scrambled code made with a secret that is created each day and destroyed, with the counts, when the day ends, so nobody can work back to who made the requests.
HumanToll is a research project, not a commercial service. For advanced API access, contact us at info@quiescence.eu. info@quiescence.eu
With a key
For research that needs more than the daily allowance, a key is issued on request, free of charge: write to info@quiescence.eu with what the work is and how much it needs. Send the key as Authorization: Bearer <key> (or X-API-Key); the allowance then counts per key instead of per address, and each response says how much of it remains.
A key is shown once, when it is issued, and HumanToll keeps only its fingerprint. A lost key is revoked and replaced — there is nothing to recover. A key that is not valid is refused with 401. Send it in a header, never in the URL: URLs are written to logs.
From a browser
Any origin may read the API (Access-Control-Allow-Origin: *). No cookie is set, and none is needed.