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

Mass and weight converter API

Convert between metric, avoirdupois (pounds and ounces), troy and carat units.

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

Convert between metric, avoirdupois (pounds and ounces), troy and carat units. 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 kg
  • Unit definitions: 1 kg = 1 kg (SI base unit); 1 g = 0.001 kg (SI prefix); 1 mg = 0.000001 kg (SI prefix); 1 ug = 0.000000001 kg (SI prefix); 1 t = 1000 kg (1000 kg); 1 lb = 0.45359237 kg (international pound, exact since 1959); 1 oz = 0.028349523125 kg (1/16 lb); 1 st = 6.35029318 kg (14 lb); 1 short_ton = 907.18474 kg (2000 lb); 1 long_ton = 1016.0469088 kg (2240 lb); 1 gr = 0.00006479891 kg (1/7000 lb); 1 ozt = 0.0311034768 kg (480 grains); 1 lbt = 0.3732417216 kg (12 troy ounces); 1 ct = 0.0002 kg (200 mg)

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. Allowed: >= 0.
from_unit required kg | g | mg | ug | t | lb | oz | st | short_ton | long_ton | gr | ozt | lbt | ct Unit of the value. Options: kg: kilogram; g: gram; mg: milligram; ug: microgram; t: tonne (metric ton); lb: pound (avoirdupois); oz: ounce (avoirdupois); st: stone; short_ton: short ton (US); long_ton: long ton (UK); gr: grain; ozt: troy ounce; lbt: troy pound; ct: carat (metric)
to_unit kg | g | mg | ug | t | lb | oz | st | short_ton | long_ton | gr | ozt | lbt | ct Unit to convert to. Omit to convert to every unit. Options: kg: kilogram; g: gram; mg: milligram; ug: microgram; t: tonne (metric ton); lb: pound (avoirdupois); oz: ounce (avoirdupois); st: stone; short_ton: short ton (US); long_ton: long ton (UK); gr: grain; ozt: troy ounce; lbt: troy pound; ct: carat (metric)
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 pound in kilograms

Requestcurl
curl https://api.curatedapi.com/v1/calc/units/mass \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "1",
    "from_unit": "lb",
    "to_unit": "kg"
  }'
200 OKResponse
{
  "calculator": "units/mass@1",
  "result": {
    "result": "0.45359237",
    "factor": "0.45359237"
  },
  "exactness": {
    "result": "exact",
    "factor": "exact"
  },
  "precision": {
    "rounding": "half_even",
    "significant_digits": 15
  },
  "inputs": {
    "value": "1",
    "from_unit": "lb",
    "to_unit": "kg"
  },
  "formula": "result = value × factor(from_unit) ÷ factor(to_unit), factors in kg",
  "references": [
    {
      "title": "NIST Special Publication 811 (2008), Appendix B: conversion factors",
      "url": "https://www.nist.gov/pml/special-publication-811"
    },
    {
      "title": "NIST Handbook 44, Appendix C: General tables of units of measurement",
      "url": "https://www.nist.gov/pml/owm/nist-handbook-44-current-edition"
    }
  ],
  "warnings": []
}

One troy ounce in grams

Requestcurl
curl https://api.curatedapi.com/v1/calc/units/mass \
  -H "Authorization: Bearer $CURATEDAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "1",
    "from_unit": "ozt",
    "to_unit": "g"
  }'
200 OKResponse
{
  "calculator": "units/mass@1",
  "result": {
    "result": "31.1034768",
    "factor": "31.1034768"
  },
  "exactness": {
    "result": "exact",
    "factor": "exact"
  },
  "precision": {
    "rounding": "half_even",
    "significant_digits": 15
  },
  "inputs": {
    "value": "1",
    "from_unit": "ozt",
    "to_unit": "g"
  },
  "formula": "result = value × factor(from_unit) ÷ factor(to_unit), factors in kg",
  "references": [
    {
      "title": "NIST Special Publication 811 (2008), Appendix B: conversion factors",
      "url": "https://www.nist.gov/pml/special-publication-811"
    },
    {
      "title": "NIST Handbook 44, Appendix C: General tables of units of measurement",
      "url": "https://www.nist.gov/pml/owm/nist-handbook-44-current-edition"
    }
  ],
  "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.