AnvilJSON utilities

Anvil › Docs › /v1/units

Unit converter API: length, mass, temperature, data sizes and Mbps to MB/s

Pass a number plus two units and get the converted value back as JSON. Covers everyday length and mass, careful temperature formulae (C, F, K), and the decimal-vs-binary data-size trap (KB is 1000 bytes; KiB is 1024).

In one line: GET /v1/units?value=5&from=km&to=mi returns JSON. No key, CORS on, 60 requests a minute.
GET

/v1/units

Convert length, mass, temperature, data-size or data-rate units. Change the values and press Send request to call the live API.



Parameters
NameTypeWhat it doesDefault
value requiredstringNumber to convert—
from requiredstringSource unit (m, km, lb, C, MiB, Mbps, MB/s…)—
to requiredstringTarget unit—
categorystringOptional: length, mass, temperature, data or rate (disambiguates)—


Example
Request:
GET https://api.oddlathe.com/v1/units?value=5&from=km&to=mi


Response (generated by the real code when these docs were last built; random or time-based values will differ for you):
{
 "value": 5,
 "from": "km",
 "to": "mi",
 "category": "length",
 "result": 3.10685596119
}


Code examples
curl
curl 'https://api.oddlathe.com/v1/units?value=5&from=km&to=mi'
JavaScript (browser or Node 18+)
const params = new URLSearchParams({
  value: "5",
  from: "km",
  to: "mi"
});
const res = await fetch(`https://api.oddlathe.com/v1/units?${params}`);
if (!res.ok) throw new Error((await res.json()).error.message);
const data = await res.json();
console.log(data);
Python (standard library only)
import json, urllib.parse, urllib.request

params = urllib.parse.urlencode({"value": "5", "from": "km", "to": "mi"})
url = "https://api.oddlathe.com/v1/units?" + params
# Send a User-Agent: the edge network refuses Python's default one.
req = urllib.request.Request(url, headers={"User-Agent": "my-script/1.0"})
with urllib.request.urlopen(req, timeout=10) as r:
    data = json.load(r)
print(data)


When it's useful
  • Scripts that normalise mixed units from spreadsheets or CSV without pulling in a conversion library
  • Showing "5 km is about 3.1 mi" next to a measurement in a UI
  • Turning an advertised broadband speed in Mbps into the MB/s a download bar will actually show
  • Checking whether a file-size limit is 5 MB (5,000,000 bytes) or 5 MiB (5,242,880 bytes)
  • Teaching the difference between Celsius, Fahrenheit and Kelvin with a live example


Good to know
  • value, from and to are required. Optional category=length|mass|temperature|data rejects units from the wrong family.
  • Length base is the metre: m, km, cm, mm, mi, yd, ft, in, nmi (international nautical mile).
  • Mass base is the kilogram: kg, g, mg, lb, oz, t (metric tonne = 1000 kg, not the US/UK ton).
  • Temperature uses offset formulae via Kelvin, not a multiply. Values below absolute zero (0 K) are rejected. A short note is included.
  • Data sizes: B, KB/MB/GB/TB are SI (1000-based); KiB/MiB/GiB/TiB are IEC binary (1024-based). The response note reminds you which is which.
  • Data rates (category=rate): base is bits per second. bps, kbps, Mbps, Gbps are bits; B/s, KB/s, MB/s, GB/s are bytes (×8); KiB/s, MiB/s, GiB/s are binary byte rates. Case matters for the compact forms: Mbps is megabits, MBps is megabytes. URL-encode the slash (MB%2Fs) or use MBps.
  • Aliases like kilometre, pounds, celsius or mebibyte are accepted and normalised to the short form in the response.
  • Both units must be in the same category. Pure maths on the query string; nothing is stored.
  • Browser UI: Tooltern unit converter (same maths, nothing leaves your device). Plain-words companions: KB vs KiB / MB vs MiB, Celsius ↔ Fahrenheit ↔ Kelvin, metric tonne vs ton.


Convert a number between common units of length, mass, temperature or digital data size. Length uses metres as the base (m, km, cm, mm, mi, yd, ft, in, nmi). Mass uses kilograms (kg, g, mg, lb, oz, t for the metric tonne). Temperature accepts C, F and K with proper offset formulae. Data sizes distinguish SI (KB/MB/GB/TB = 1000) from IEC binary (KiB/MiB/GiB/TiB = 1024). Data rates convert between bits and bytes per second (Mbps, MB/s, MiB/s…; lower-case b = bits). Optional category disambiguates. Pure maths; nothing is stored.


Errors
Errors are JSON like {"error": {"code": "…", "message": "…"}}. The ones this endpoint can return:
  • missing_param (400): a required parameter is missing or empty
  • bad_param (400): a value is the wrong type or out of range (the message says which)
  • rate_limited (429): over 60 requests a minute; wait for Retry-After seconds


Questions
Why is 1 KB not 1024 bytes?
Hard-drive makers and the SI standard use 1000. Memory and many OS tools historically used 1024 and later renamed that to KiB (kibibyte). This API keeps both: KB = 1000, KiB = 1024.
Can I convert pounds to kilometres?
No. Units must share a category (length, mass, temperature or data). Mixing them returns bad_param.
How is temperature converted?
Everything goes through Kelvin with the standard offsets (C = K − 273.15, F = C × 9/5 + 32). Absolute zero and below are rejected.
How many MB/s is 100 Mbps?
12.5. <code>/v1/units?value=100&amp;from=Mbps&amp;to=MBps</code> returns 12.5, because one byte is 8 bits. Real downloads land a little lower after protocol overhead.
Is t a US ton?
No. t is the metric tonne (1000 kg). US short ton and UK long ton are not supported.
Is anything stored?
Never. Pure maths on the query string.


Related endpoints


Prefer a page to an API?


Published , updated  · OpenAPI 3.1 spec · Limits and privacy