curatedapi
Browse the docs

Guides

Finance

Excel functions

Late payments

E-invoices

Accounting

Number checks

VAT and GST

Billing and pricing

Money and currencies

Dates and time

Math

Unit conversion

Everyday

Health

Length converter API

Convert between metric, imperial/US, nautical and astronomical lengths.

POST https://api.curatedapi.com/v1/calc/units/length

Convert between metric, imperial/US, nautical and astronomical lengths. Conversion factors are exact values from the official unit definitions, so the result is exact before the single final rounding. Leave out to_unit to get the value in every supported unit.

Formula

result = value × factor(from_unit) ÷ factor(to_unit), factors in m
  • Unit definitions: 1 m = 1 m (SI base unit); 1 km = 1000 m (SI prefix); 1 cm = 0.01 m (SI prefix); 1 mm = 0.001 m (SI prefix); 1 um = 0.000001 m (SI prefix); 1 nm = 0.000000001 m (SI prefix); 1 in = 0.0254 m (international inch, exact since 1959); 1 ft = 0.3048 m (international foot = 12 in); 1 yd = 0.9144 m (international yard = 3 ft); 1 mi = 1609.344 m (international mile = 5280 ft); 1 nmi = 1852 m (international nautical mile, exact); 1 mil = 0.0000254 m (1/1000 inch); 1 fathom = 1.8288 m (6 ft); 1 chain = 20.1168 m (66 ft); 1 furlong = 201.168 m (660 ft); 1 ft_us = 1200/3937 m (1200/3937 m; retired by NIST at the end of 2022 but still in old land records); 1 au = 149597870700 m (IAU 2012 Resolution B2, exact); 1 ly = 9460730472580800 m (speed of light × Julian year (IAU)); 1 pc = see source m (648000/π au, IAU 2015 Resolution B2)

Inputs

Send numbers as strings to keep every digit. options sets precision and rounding (see numbers and rounding).

InputTypeDescription
value required decimal (string) The amount to convert.
from_unit required m | km | cm | mm | um | nm | in | ft | yd | mi | nmi | mil | fathom | chain | furlong | ft_us | au | ly | pc Unit of the value. Options: m: metre; km: kilometre; cm: centimetre; mm: millimetre; um: micrometre; nm: nanometre; in: inch; ft: foot; yd: yard; mi: mile; nmi: nautical mile; mil: mil (thou); fathom: fathom; chain: chain; furlong: furlong; ft_us: US survey foot; au: astronomical unit; ly: light-year; pc: parsec
to_unit m | km | cm | mm | um | nm | in | ft | yd | mi | nmi | mil | fathom | chain | furlong | ft_us | au | ly | pc Unit to convert to. Omit to convert to every unit. Options: m: metre; km: kilometre; cm: centimetre; mm: millimetre; um: micrometre; nm: nanometre; in: inch; ft: foot; yd: yard; mi: mile; nmi: nautical mile; mil: mil (thou); fathom: fathom; chain: chain; furlong: furlong; ft_us: US survey foot; au: astronomical unit; ly: light-year; pc: parsec
options.rounding half_even | half_up | half_down | up | down | ceiling | floor Rounding mode applied once to each result. Default half_even.
options.decimals integer Round results to this many digits after the decimal point.
options.significant_digits integer Round results to this many significant digits.

Result

Under result in the answer, next to exactness, precision, inputs, formula, references and warnings.

ResultTypeDescription
resultdecimal (string)The converted value.
factordecimal (string)How many to_unit make one from_unit (multiply by this to convert).
all_unitslist of objectThe value expressed in every supported unit.

Examples

One mile in kilometres

Requestcurl
curl https://api.curatedapi.com/v1/calc/units/length \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "1",
    "from_unit": "mi",
    "to_unit": "km"
  }'
200 OKResponse
{
  "calculator": "units/length@1",
  "result": {
    "result": "1.609344",
    "factor": "1.609344"
  },
  "exactness": {
    "result": "exact",
    "factor": "exact"
  },
  "precision": {
    "rounding": "half_even",
    "significant_digits": 15
  },
  "inputs": {
    "value": "1",
    "from_unit": "mi",
    "to_unit": "km"
  },
  "formula": "result = value × factor(from_unit) ÷ factor(to_unit), factors in m",
  "references": [
    {
      "title": "NIST Special Publication 811 (2008), Appendix B: conversion factors",
      "url": "https://www.nist.gov/pml/special-publication-811"
    },
    {
      "title": "IAU 2012 Resolution B2 (astronomical unit)",
      "url": "https://iauarchive.eso.org/static/resolutions/IAU2012_English.pdf"
    },
    {
      "title": "IAU 2015 Resolution B2 (parsec)",
      "url": "https://www.iau.org/static/resolutions/IAU2015_English.pdf"
    },
    {
      "title": "NIST: The U.S. survey foot (deprecation notice)",
      "url": "https://www.nist.gov/pml/us-surveyfoot"
    }
  ],
  "warnings": []
}

Six feet in metres

Requestcurl
curl https://api.curatedapi.com/v1/calc/units/length \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "6",
    "from_unit": "ft",
    "to_unit": "m"
  }'
200 OKResponse
{
  "calculator": "units/length@1",
  "result": {
    "result": "1.8288",
    "factor": "0.3048"
  },
  "exactness": {
    "result": "exact",
    "factor": "exact"
  },
  "precision": {
    "rounding": "half_even",
    "significant_digits": 15
  },
  "inputs": {
    "value": "6",
    "from_unit": "ft",
    "to_unit": "m"
  },
  "formula": "result = value × factor(from_unit) ÷ factor(to_unit), factors in m",
  "references": [
    {
      "title": "NIST Special Publication 811 (2008), Appendix B: conversion factors",
      "url": "https://www.nist.gov/pml/special-publication-811"
    },
    {
      "title": "IAU 2012 Resolution B2 (astronomical unit)",
      "url": "https://iauarchive.eso.org/static/resolutions/IAU2012_English.pdf"
    },
    {
      "title": "IAU 2015 Resolution B2 (parsec)",
      "url": "https://www.iau.org/static/resolutions/IAU2015_English.pdf"
    },
    {
      "title": "NIST: The U.S. survey foot (deprecation notice)",
      "url": "https://www.nist.gov/pml/us-surveyfoot"
    }
  ],
  "warnings": []
}

One parsec in light-years

Requestcurl
curl https://api.curatedapi.com/v1/calc/units/length \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "1",
    "from_unit": "pc",
    "to_unit": "ly"
  }'
200 OKResponse
{
  "calculator": "units/length@1",
  "result": {
    "result": "3.26156377716743",
    "factor": "3.26156377716743"
  },
  "exactness": {
    "result": "rounded",
    "factor": "rounded"
  },
  "precision": {
    "rounding": "half_even",
    "significant_digits": 15
  },
  "inputs": {
    "value": "1",
    "from_unit": "pc",
    "to_unit": "ly"
  },
  "formula": "result = value × factor(from_unit) ÷ factor(to_unit), factors in m",
  "references": [
    {
      "title": "NIST Special Publication 811 (2008), Appendix B: conversion factors",
      "url": "https://www.nist.gov/pml/special-publication-811"
    },
    {
      "title": "IAU 2012 Resolution B2 (astronomical unit)",
      "url": "https://iauarchive.eso.org/static/resolutions/IAU2012_English.pdf"
    },
    {
      "title": "IAU 2015 Resolution B2 (parsec)",
      "url": "https://www.iau.org/static/resolutions/IAU2015_English.pdf"
    },
    {
      "title": "NIST: The U.S. survey foot (deprecation notice)",
      "url": "https://www.nist.gov/pml/us-surveyfoot"
    }
  ],
  "warnings": []
}

References

Results follow each calculator's documented rules and the sources listed. They are not financial, tax or legal advice. Check that the rules fit your case before you rely on a result. See the terms.

Errors share one format; see errors. Billing, retries and batches work the same for every endpoint.