ConvertReference.org

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 when a_decimal is 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.

GET /api/v1/units/{id}.json

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.

GET /api/v1/quantities.json

The 12 quantities and the unit ids in each.

GET /api/v1/units.json

The whole registry in one file.

GET /api/v1/aliases.json

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.

GET /api/v1/converters.json

Every converter page on the site and its pair file.

GET /api/v1/index.json

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, tablespoon and teaspoon are US customary; imperial_gallon and imperial_pint are the UK units.
  • ton is the US short ton; metric_ton and long_ton are the others.
  • year is the Julian year (365.25 days) and month is 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_version in every file changes whenever a definition changes.
  • The API is versioned in the path. Fields may be added to v1 files but none will be removed or change meaning.
  • Conversion data is released under CC0 1.0. Calculator descriptions and page text remain © ConvertReference.