Data version 2026-11-09
ConvertReference API
A free JSON API of exact unit conversion factors — 123 units in 12 quantities and a file for every pair — plus every calculator on the site and a small engine to run them. It is all static files: no key, no sign-up, no quota, and CORS is open. The conversion data is public domain (CC0), so you can use it in any project, commercial or not.
How it works
Instead of sending a value to a server, you fetch the conversion factor and do the arithmetic yourself. Every unit pair has its own file:
https://convertreference.org/api/v1/convert/millimeter-to-inch.json
{
"forward": {
"expression": "y = a * x + b",
"a": 0.03937007874015748,
"b": 0.0,
"a_decimal": "0.0393700787401574803150",
"b_decimal": "0",
"a_rational": "5/127"
},
"reverse": {
"expression": "x = c * y + d",
"c": 25.4,
"d": 0.0,
"c_decimal": "25.4",
"d_decimal": "0",
"c_rational": "127/5"
}
}
Convert with y = a × x + b, and back with x = c × y + d. For every quantity except temperature, b and d are 0, so it is a single multiplication. The files are cached worldwide, so fetch once and reuse the factor.
a,c— the factor as a JSON number (double precision).a_decimal,c_decimal— the factor as a string, complete when it terminates and otherwise to 21 significant digits.a_rational,c_rational— the exact fraction, for units that are exactly defined (null for the parsec, Bohr radius and Planck length).factor_exact— true whena_decimalis the complete, exact value.
Files
Base URL https://convertreference.org/api/v1/. Unit ids use underscores (pound_force_per_square_inch); in pair file names they use hyphens.
GET /api/v1/convert/{from}-to-{to}.json
One file per pair of units within a quantity — 1,537 in all. Forward and reverse factors, the definition of each unit, and a link to the converter page when there is one.
One unit: name, symbol, system, value in the SI unit (decimal and exact fraction), definition, other spellings, and links to all its pair files.
GET /api/v1/quantities/{id}.json
Every unit of one quantity with its value in the SI unit — enough to convert between any two of them locally.
The 12 quantities and the unit ids in each.
The whole registry in one file.
Names, plurals, symbols and spellings (lbs, metres, psi, °F) mapped to unit ids, so you can turn user input into a file name. Keys with two ids are ambiguous: pc is a pica or a parsec, c is degrees Celsius or the speed of light.
Every converter page on the site and its pair file.
This list, as JSON.
Prefer a spreadsheet? The same data is in CSV downloads.
Examples
JavaScript, one pair:
// Convert 150 lb to kg
const r = await fetch("https://convertreference.org/api/v1/convert/pound-to-kilogram.json");
const { forward } = (await r.json()).conversion.affine;
const kg = forward.a * 150 + forward.b; // 68.0388555
Python, a whole quantity at once:
import requests
# Load one quantity once, then convert anything within it locally
q = requests.get("https://convertreference.org/api/v1/quantities/pressure.json").json()
to_si = {u["id"]: float(u["to_si"]) for u in q["units"]}
def convert(value, frm, to):
return value * to_si[frm] / to_si[to]
convert(32, "pound_force_per_square_inch", "kilopascal") # 220.632...
Exact arithmetic with the fractions:
from fractions import Fraction
pair = requests.get("https://convertreference.org/api/v1/convert/inch-to-millimeter.json").json()
a = Fraction(pair["conversion"]["affine"]["forward"]["a_rational"]) # 127/5
a * 12 # Fraction(1524, 5) = 304.8 exactly
Temperature has an offset, so use both terms — celsius-to-fahrenheit.json gives °F = 1.8 × °C + 32:
{
"expression": "y = a * x + b",
"a": 1.8,
"b": 32.0,
"a_decimal": "1.8",
"b_decimal": "32",
"a_rational": "9/5"
}
For a temperature difference (a 10 °C rise), use a alone and ignore b.
Conventions
gallon,quart,pint,cup,fluid_ounce,tablespoonandteaspoonare US customary;imperial_gallonandimperial_pintare the UK units.tonis the US short ton;metric_tonandlong_tonare the others.yearis the Julian year (365.25 days) andmonthis one twelfth of it.- Acre, chain, furlong, fathom and league use the international foot (the US survey foot was retired in 2023).
- Data storage:
kilobyte= 1000 bytes,kibibyte= 1024 bytes.
Calculators
Every published calculator is also a static file, with its inputs, outputs, formulas and sources. The files are served straight from storage at data.convertreference.org and update within about ten minutes of a calculator going live or being withdrawn.
GET https://data.convertreference.org/api/v1/calculators/index.json
The fields (home, science, food…), how many calculators each has, and a link to each field's list.
GET https://data.convertreference.org/api/v1/calculators/fields/{field}.json
Every calculator in a field: title, description, page URL and file URL.
GET https://data.convertreference.org/api/v1/calculators/{slug}.json
One calculator: inputs with defaults, limits and allowed units; outputs; sources; and an engine block with the formulas.
GET /api/v1/calculator-engine.js
A small ES module (about 20 KB, no dependencies) that runs any calculator file in your own code — browser, Node, Deno or a Worker. It is the same engine our calculator pages use.
import { computeCalculator } from "https://convertreference.org/api/v1/calculator-engine.js";
const file = await (await fetch("https://data.convertreference.org/api/v1/calculators/concrete-slab-bags.json")).json();
const r = computeCalculator(file, {
inputs: { length: 3, width: 4, thick: 10 },
units: { length: "m", width: "m", thick: "cm" },
output_units: { volume: "m3" },
});
// r =
{
"ok": true,
"inputs": { "length": { "value": 3, "unit": "m" }, "width": { "value": 4, "unit": "m" }, "thick": { "value": 10, "unit": "cm" }, ... },
"outputs": {
"volume": { "label": "Concrete to order", "value": 1.32, "unit": "m3", "display": "1.32 m³" },
"bags": { "label": "Bags needed", "value": 78, "unit": "bags", "display": "78 bags" },
...
}
}
When inputs are invalid, computeCalculator returns {"ok": false, "errors": [{"id": "length", "msg": "Length must be at least 0.5 ft"}]}. Units are chosen with units for inputs and output_units for outputs, using the ids listed in each file.
Limits, updates and licence
- No key and no quota. Files are cached for an hour at Cloudflare's edge and in browsers. Very heavy automated traffic from one address is briefly rate-limited, so cache files on your side or download the datasets for bulk use.
- The files are rebuilt from the unit registry on every site deploy, so new converters appear here automatically.
data_versionin every file changes whenever a definition changes. - The API is versioned in the path. Fields may be added to
v1files but none will be removed or change meaning. - Conversion data is released under CC0 1.0. Calculator descriptions and page text remain © ConvertReference.