Every response returns the stored factor, the offset, the display precision and the page that documents the definition — so you can reproduce the number instead of trusting it.
No key needed for light use:
curl "https://api.allunits.org/v1/convert?from=km&to=mi&value=10"
{
"ok": true,
"input": { "value": 10, "from": "km" },
"output": { "value": 6.213712, "unit": "mi" },
"pair": "km-to-miles",
"factor": 0.6213711922,
"offset": 0,
"decimals": 6,
"unrounded": 6.213711922,
"formula": "mi = km x 0.621371",
"definition_page": "https://allunits.org/km-to-miles/",
"category": "length",
"attribution": "AllUnits.org - https://allunits.org/",
"quota": { "plan": "anonymous", "remaining_today": 99 }
}
Unit names work as well as symbols — kilometers, pounds, fahrenheit, celsius. The reverse direction needs no second pair: ?from=mi&to=km uses (value − offset) / factor.
Up to 100 conversions per request. One bad row does not fail the batch — each item comes back with ok and either output or error, in the same order.
curl -X POST https://api.allunits.org/v1/convert \
-H "Content-Type: application/json" \
-H "x-api-key: $ALLUNITS_KEY" \
-d '{"batch":[
{"from":"kg","to":"lb","value":2.5},
{"from":"psi","to":"bar","value":35}
]}'
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/health | Liveness and dataset version |
| GET | /v1/pairs | The 30 supported pairs |
| GET | /v1/factors | Full dataset with factors, formulas, pages |
| GET | /v1/convert | One conversion from query parameters |
| POST | /v1/convert | One conversion or a batch |
| GET | /v1/usage | Quota for the calling key or IP |
Machine-readable spec: /openapi.json (OpenAPI 3.1). The same dataset is downloadable as factors.json.
| Tier | How | Daily limit |
|---|---|---|
| Anonymous | no key | 100 requests per IP |
| API Basic | x-api-key: YOUR_KEY | 10,000 |
| API Creator | x-api-key: YOUR_KEY | 100,000 |
Authorization: Bearer YOUR_KEY works as well. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (seconds until reset); a 429 includes Retry-After.
All errors are { "ok": false, "error": { "code": "...", "message": "..." } }.
| Code | HTTP | Meaning |
|---|---|---|
missing_units | 400 | from or to absent |
missing_value | 400 | value absent |
invalid_value | 400 | Not a finite number |
value_too_large | 400 | Beyond ±1e15 |
unknown_pair | 400 | Includes available_pairs_from_source |
batch_too_large | 400 | More than 100 items |
invalid_key | 401 | Key not found or inactive |
rate_limited | 429 | Daily quota exhausted |
not_found | 404 | Unknown route |
factor and offset are the values the site computes with; decimals is what the site displays. Rounding happens only at the display step — unrounded is always in the response, and ?decimals= accepts 0–12.
Some definitions are exact and some are working precision. A pair is exact when the underlying standard defines it exactly (1 mile = 1,609.344 m, 1 lb = 0.45359237 kg, 1 in = 25.4 mm, 1 yd = 0.9144 m). Binary prefixes (KiB, MiB, GiB) follow IEC 80000-13. Temperature uses the offset form: result = value × factor + offset.
The definition_page field points at the page that states which convention is in use — US vs imperial gallon, statute vs nautical mile. If your use case depends on a convention, read that page rather than assuming.
Keys are delivered by email, usually within a few hours. Cancel any time; keys stay valid until the end of the paid period.
Request a key — contact@allunits.orgThe data is published under CC BY 4.0. Using it in a product, a report or a dataset requires attribution:
Unit conversion data: AllUnits.org — https://allunits.org/
Every successful response already includes an attribution field you can render. If you cannot carry a visible attribution (internal tooling, a paid product, a printed datasheet), the one-time data licence removes the requirement.