Skip to main content

Unit Conversion API

REAL DATA

Deterministic unit conversion across 14 categories — length, mass, pressure, energy, power, force, angle, time and more — with exact standard factors.

Authoritative reference data or standards computation

Base URL
/api/units
Category
Developer Tools
Capabilities
2 routes
Last updated
July 29, 2026
Data sources · 4
+1 more
  • IEC 80000-13 — binary (kibi/mebi/gibi/tebi) prefixes used by the data category

GET /api/units/convert Convert a value between two units of the same category

Pure computation: value × exact factors (or the temperature formulas). Unit ids are case-insensitive; the response echoes the canonical ids.

Live requestRuns against the public API
No key required
GET/api/units/convert?value=5&from=km&to=mi

Request parameters

The numeric value to convert (|value| ≤ 10¹⁵).

Source unit id, case-insensitive (see the table at /api/units).

Target unit id, case-insensitive — must be in the same category as 'from'.

Advanced response options4 options

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/units/convert?value=5&from=km&to=mi"
const res = await fetch("https://randomapi.dev/api/units/convert?value=5&from=km&to=mi");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/units/convert?value=5&from=km&to=mi").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/units/convert?value=5&from=km&to=mi"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 3
value float required

The numeric value to convert (|value| ≤ 10¹⁵).

allowed: -1000000000000000 – 1000000000000000
example: value=5
from string required

Source unit id, case-insensitive (see the table at /api/units).

example: from=km
to string required

Target unit id, case-insensitive — must be in the same category as 'from'.

example: to=mi
Universal parameters Shared response and formatting options 4
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=value,from
exclude list

Return all fields except these (comma-separated).

example: exclude=formula
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 6
value float

The input value, echoed back.

example: 5

from string

Canonical id of the source unit.

example: km

to string

Canonical id of the target unit.

example: mi

result float

The converted value — accurate to at least 9 significant digits, and exact conversions (e.g. 1 acre → 4046.8564224 m², 1 atm → 101325 Pa) are returned exactly.

example: 3.10685596

category string

The (shared) category of both units.

example: length

formula string

The conversion rule that was applied, e.g. '1 mi = 1.609344 km' or '°F = °C × 9/5 + 32'.

example: 1 km = 0.621371192237334 mi

Documented examples

Build-generated requests and complete responses 6
5 km in miles
GET /api/units/convert?value=5&from=km&to=mi 
{
  "data": {
    "value": 5,
    "from": "km",
    "to": "mi",
    "result": 3.10685596,
    "category": "length",
    "formula": "1 km = 0.621371192237334 mi"
  },
  "meta": {
    "endpoint": "units",
    "route": "/convert",
    "params": {
      "value": 5,
      "from": "km",
      "to": "mi"
    },
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}
Boiling point in Fahrenheit
GET /api/units/convert?value=100&from=c&to=f 
{
  "data": {
    "value": 100,
    "from": "c",
    "to": "f",
    "result": 212,
    "category": "temperature",
    "formula": "°F = °C × 9/5 + 32"
  },
  "meta": {
    "endpoint": "units",
    "route": "/convert",
    "params": {
      "value": 100,
      "from": "c",
      "to": "f"
    },
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}
1 GiB in megabytes (10⁶)
GET /api/units/convert?value=1&from=gib&to=mb 
{
  "data": {
    "value": 1,
    "from": "gib",
    "to": "mb",
    "result": 1073.741824,
    "category": "data",
    "formula": "1 gib = 1073.741824 mb"
  },
  "meta": {
    "endpoint": "units",
    "route": "/convert",
    "params": {
      "value": 1,
      "from": "gib",
      "to": "mb"
    },
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}
1 atmosphere in psi
GET /api/units/convert?value=1&from=atm&to=psi 
{
  "data": {
    "value": 1,
    "from": "atm",
    "to": "psi",
    "result": 14.6959488,
    "category": "pressure",
    "formula": "1 atm = 14.6959488 psi"
  },
  "meta": {
    "endpoint": "units",
    "route": "/convert",
    "params": {
      "value": 1,
      "from": "atm",
      "to": "psi"
    },
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}
150 mechanical horsepower in kW
GET /api/units/convert?value=150&from=hp&to=kw 
{
  "data": {
    "value": 150,
    "from": "hp",
    "to": "kw",
    "result": 111.854981,
    "category": "power",
    "formula": "1 hp = 0.745699872 kw"
  },
  "meta": {
    "endpoint": "units",
    "route": "/convert",
    "params": {
      "value": 150,
      "from": "hp",
      "to": "kw"
    },
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}
A quarter turn in radians
GET /api/units/convert?value=90&from=deg&to=rad 
{
  "data": {
    "value": 90,
    "from": "deg",
    "to": "rad",
    "result": 1.57079633,
    "category": "angle",
    "formula": "1 deg = 0.0174532925 rad"
  },
  "meta": {
    "endpoint": "units",
    "route": "/convert",
    "params": {
      "value": 90,
      "from": "deg",
      "to": "rad"
    },
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}

GET /api/units The supported unit table (ids, names, exact base factors)

Live requestRuns against the public API
No key required
GET/api/units

Request parameters

Only list units of this category.

Advanced response options6 options

Limit the number of returned records (1–100). Defaults to all matches.

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

Return all fields except these (comma-separated).

Response format: json envelope, ndjson (one record per line) or csv.

Pretty-print the JSON response.

Drop the envelope: return the raw array/object without data/meta wrapper.

Response

Example parameters are ready. Send the request to inspect the live response.

Route reference

Code, request parameters, response fields and verified examples
Code samples Ready-to-copy requests in 4 languages
Choose a code sample language 
curl "https://randomapi.dev/api/units"
const res = await fetch("https://randomapi.dev/api/units");
const { data, meta } = await res.json();
import requests

data = requests.get("https://randomapi.dev/api/units").json()["data"]
$json = json_decode(file_get_contents(
  "https://randomapi.dev/api/units"
), true);
$data = $json["data"];
Parameters Route-specific request inputs 1
category enum

Only list units of this category.

default: any
allowed: length | mass | temperature | volume | data | speed | area | pressure | energy | power | force | angle | time | frequency | any
example: category=data
Universal parameters Shared response and formatting options 6
count int

Limit the number of returned records (1–100). Defaults to all matches.

default: all matches
allowed: 1 – 100
example: count=3
fields list

Return only these fields (comma-separated). Mutually exclusive with 'exclude'.

example: fields=id,name
exclude list

Return all fields except these (comma-separated).

example: exclude=toBase
format enum

Response format: json envelope, ndjson (one record per line) or csv.

default: json
allowed: json | ndjson | csv
example: format=csv
pretty boolean

Pretty-print the JSON response.

default: false
example: pretty=true
unwrap boolean

Drop the envelope: return the raw array/object without data/meta wrapper.

default: false
example: unwrap=true
Response schema Fields returned in each record 4
id string

The unit id to pass as 'from'/'to' on /convert.

example: mi

name string

Full human-readable name.

example: mile

category string

One of: length, mass, temperature, volume, data, speed, area, pressure, energy, power, force, angle, time, frequency.

example: length

toBase string

Relation to the category's base unit (m, kg, °C, l, b, kmh, m2, pa, j, w, n, deg, s, hz), e.g. '1 mi = 1609.344 m'. Exact wherever an exact decimal exists; where none does (1 torr, 1 rad) the text says 'rounded' and gives the exact definition.

example: 1 mi = 1609.344 m

Documented examples

Build-generated requests and complete responses 4
The whole table
GET /api/units 
{
  "data": [
    {
      "id": "mm",
      "name": "millimeter",
      "category": "length",
      "toBase": "1 mm = 0.001 m"
    },
    {
      "id": "cm",
      "name": "centimeter",
      "category": "length",
      "toBase": "1 cm = 0.01 m"
    },
    {
      "id": "m",
      "name": "meter",
      "category": "length",
      "toBase": "1 m = 1 m"
    },
    {
      "id": "km",
      "name": "kilometer",
      "category": "length",
      "toBase": "1 km = 1000 m"
    },
    {
      "id": "in",
      "name": "inch",
      "category": "length",
      "toBase": "1 in = 0.0254 m"
    },
    {
      "id": "ft",
      "name": "foot",
      "category": "length",
      "toBase": "1 ft = 0.3048 m"
    },
    {
      "id": "yd",
    …
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}
Decimal vs binary byte units
GET /api/units?category=data 
{
  "data": [
    {
      "id": "b",
      "name": "byte",
      "category": "data",
      "toBase": "1 b = 1 b"
    },
    {
      "id": "kb",
      "name": "kilobyte (10^3 bytes)",
      "category": "data",
      "toBase": "1 kb = 1000 b"
    },
    {
      "id": "mb",
      "name": "megabyte (10^6 bytes)",
      "category": "data",
      "toBase": "1 mb = 1000000 b"
    },
    {
      "id": "gb",
      "name": "gigabyte (10^9 bytes)",
      "category": "data",
      "toBase": "1 gb = 1000000000 b"
    },
    {
      "id": "tb",
      "name": "terabyte (10^12 bytes)",
      "category": "data",
      "toBase": "1 tb = 1000000000000 b"
    },
    {
      "id": "kib",
      "name": "kibibyte (2^10 bytes)",
      "category": "data",
      "toBase": "1 kib = 1024 b"
    },
    {
      "id": "mib",
    …
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}
Pressure units and their exact factors
GET /api/units?category=pressure 
{
  "data": [
    {
      "id": "pa",
      "name": "pascal",
      "category": "pressure",
      "toBase": "1 pa = 1 pa"
    },
    {
      "id": "hpa",
      "name": "hectopascal (10^2 Pa)",
      "category": "pressure",
      "toBase": "1 hpa = 100 pa"
    },
    {
      "id": "kpa",
      "name": "kilopascal (10^3 Pa)",
      "category": "pressure",
      "toBase": "1 kpa = 1000 pa"
    },
    {
      "id": "mpa",
      "name": "megapascal (10^6 Pa)",
      "category": "pressure",
      "toBase": "1 mpa = 1000000 pa"
    },
    {
      "id": "bar",
      "name": "bar",
      "category": "pressure",
      "toBase": "1 bar = 100000 pa"
    },
    {
      "id": "mbar",
      "name": "millibar (= hectopascal)",
      "category": "pressure",
      "toBase": "1 mbar = 100 pa"
    },
    {
      "id": "atm",
    …
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}
Length ids and factors only
GET /api/units?category=length&fields=id,toBase 
{
  "data": [
    {
      "id": "mm",
      "toBase": "1 mm = 0.001 m"
    },
    {
      "id": "cm",
      "toBase": "1 cm = 0.01 m"
    },
    {
      "id": "m",
      "toBase": "1 m = 1 m"
    },
    {
      "id": "km",
      "toBase": "1 km = 1000 m"
    },
    {
      "id": "in",
      "toBase": "1 in = 0.0254 m"
    },
    {
      "id": "ft",
      "toBase": "1 ft = 0.3048 m"
    },
    {
      "id": "yd",
      "toBase": "1 yd = 0.9144 m"
    },
    {
      "id": "mi",
      "toBase": "1 mi = 1609.344 m"
    }
  ],
  "meta": {
    "endpoint": "units",
    "count": 8,
    "params": {
      "category": "length"
    },
    "generatedAt": "2026-07-29T08:14:28.000Z"
  }
}

About this API

Coverage, behavior and common use cases

Coverage & behavior

Converts between 110 units in 14 categories using the exact legal/standard definitions, not lookup-table approximations:

  • length — mm, cm, m, km, in, ft, yd, mi (1 in = 0.0254 m and 1 mi = 1609.344 m, exact per the 1959 international yard & pound agreement)
  • mass — mg, g, kg, t, oz, lb, st (1 lb = 0.45359237 kg exact; oz = lb/16; st = 14 lb)
  • temperature — c, f, k (real offset formulas, so 100 °C → 212 °F and 0 °C → 273.15 K exactly)
  • volume — ml, l, m3, tsp, tbsp, floz, cup, pt, qt, gal (US liquid measures; 1 gal = 3.785411784 l exact, and cup/floz/tbsp/tsp derive from it)
  • data — b, kb, mb, gb, tb (decimal SI: kb = 1000 b) and kib, mib, gib, tib (binary IEC: kib = 1024 b). The two ladders are deliberately distinct: 1 gb = 10⁹ bytes while 1 gib = 2³⁰ = 1 073 741 824 bytes.
  • speed — ms, kmh, mph, knot (1 knot = 1.852 km/h and 1 mph = 1.609344 km/h, exact)
  • area — m2, km2, ft2, yd2, acre, ha (1 acre = 4046.8564224 m² exact)
  • pressure — pa, hpa, kpa, mpa, bar, mbar, atm, torr, mmhg, inhg, psi, ksi (1 bar = 10⁵ Pa and 1 atm = 101325 Pa exactly. torr and mmhg are different units: 1 torr = 101325/760 Pa while the conventional mmHg = 133.322387415 Pa)
  • energy — j, kj, mj, wh, kwh, mwh, cal, kcal, calit, btu, therm, erg, ev, ftlbf (cal is the thermochemical calorie, 4.184 J exactly — the one behind US nutrition labels; calit is the International Table calorie, 4.1868 J; btu is the IT Btu, 1055.05585262 J; 1 eV = 1.602176634 × 10⁻¹⁹ J, exact since the 2019 SI redefinition fixed the elementary charge)
  • power — w, kw, mw, gw, hp, ps, btuh (hp is the mechanical horsepower, 550 ft·lbf/s = 745.69987158227022 W; ps is the metric horsepower, 75 kgf·m/s = 735.49875 W — different units, both exact)
  • force — n, kn, kgf, lbf, ozf, kip, dyn, pdl (kgf and lbf use the standard gravity g_n = 9.80665 m/s², exact by the 3rd CGPM, 1901)
  • angle — deg, rad, mrad, grad, arcmin, arcsec, turn (the degree is the base so grad/arcmin/arcsec/turn stay exact rationals; the radian is 180/π degrees and the table says so rather than printing a decimal as "exact")
  • time — ns, us, msec, s, min, h, day, week, year (year is the Julian year, exactly 365.25 days. Calendar months and years are deliberately absent: no exact factor exists for them)
  • frequency — hz, khz, mhz, ghz, thz, rpm (1 rpm = 1/60 Hz exactly)

Id collisions are documented, never silent. ms is meter per second — it shipped before the time category existed and renaming it would break callers — so the millisecond is msec. ps is metric horsepower, mb is megabyte (the millibar is mbar), mw is megawatt and mpa is megapascal. Ask for a conversion that mixes those up and the 400 says which unit you actually named.

Rounded is labelled as rounded. Most factors are exact decimals. A few cannot be — 1 torr = 101325/760 Pa and 1 psi = 1 lbf ÷ 1 in² never terminate, 1 rad = 180/π° is irrational, and 1 hp = 550 ft·lbf/s has more digits than a double can round-trip. Those rows print the exact definition in toBase instead of pretending a decimal is exact.

Every /convert response includes the formula that was applied, so results are auditable. Unit ids are case-insensitive. Converting across categories (km → kg) is a 400 naming both categories, and an unknown unit is a 400 listing every supported id — plus a "did you mean" when your input is close to a real one. Nothing is ever silently guessed. Results are pure functions of the inputs: same query, same answer, forever.

Use it for

  • Server-side conversion for user-facing settings (imperial ⇄ metric) without shipping a library
  • Sanity-check stored values in tests: assert 1 gib is exactly 1073741824 bytes, not 10⁹
  • Show 'X mi = Y km' style strings straight from the formula field
  • Normalise engineering inputs — psi ⇄ bar, kWh ⇄ MJ, hp ⇄ kW, rpm ⇄ Hz — before storing them

Frequently asked questions

Practical answers about this endpoint 6
Are the conversion factors exact?

Where an exact legal definition exists, yes — 1 inch = 25.4 mm, 1 lb = 0.45359237 kg, 1 atm = 101325 Pa — and the response's formula shows the math. Where no decimal can be exact (1 torr = 101325/760 Pa, 1 rad = 180/π°) the table says rounded and gives the exact definition.

Which categories are supported?

Length, mass, temperature, volume, data, speed, area, pressure, energy, power, force, angle, time and frequency — 14 in all, and the reference route lists every unit per category.

How does temperature conversion work?

Via the exact offset formulas (°F = °C × 9/5 + 32), not linear factors — so 100 °C converts to exactly 212 °F.

How do I convert milliseconds?

Use msec. The id ms was already the speed unit meter per second before the time category existed, and breaking existing callers would be worse than an unusual id — so millisecond is msec, and ps is metric horsepower rather than picosecond.

Is hp the mechanical or the metric horsepower?

hp is the mechanical (imperial) horsepower, exactly 550 ft·lbf/s = 745.69987158227022 W. The metric horsepower (PS/CV, 75 kgf·m/s = 735.49875 W exactly) is a separate unit with the id ps.

What about unknown units?

/convert with an unknown from/to answers 400 with the full list of supported ids, and a did-you-mean suggestion when your input is close to a real one — never a silent guess.

Related APIs

Useful next tools in the catalog
Random Number Generator API MOCK DATA

Random integers or floats in any range — control decimal precision, draw guaranteed-unique values, and pin a seed for reproducible sequences.
ISO 4217 Currency Codes API REAL DATA

Every active ISO 4217 currency — code, name, symbol, minor-unit decimals and the countries using it. Search the list or look up one code, with honest 404s.
Date Info API REAL DATA

Real calendar facts for any date — weekday, ISO week, day of year, quarter, leap year, days in month, weekend flag and Unix timestamp. Defaults to today.
ISO 8601 Duration Parser & Calculator API REAL DATA

Parse ISO 8601 durations, add them with documented end-of-month clamping, break down the gap between two dates, and humanize a span in any locale.