{"name":"convert","intro":"Unit conversion on top of Pint, with one rule the rest of the world skips: a unit with two meanings is never guessed. `ton` (metric, short, long), `gallon` (US, imperial), `oz` (mass or fluid), `cup`, `pint`, `calorie`, `KB`/`GB` (decimal, binary, bits) all come back as `ambiguous` with the concrete options, unless you pass `assume: common`. Everything else converts exactly, with the conversion factor returned alongside the result. Three families that a generic unit registry gets wrong have modes of their own: fuel economy (L/100 km is an inverse quantity), cooking measures (a cup of flour and a cup of sugar weigh different amounts) and shoe/clothing sizes (table lookups, named and flagged as approximate).","when_to_use":["Any length, mass, area, volume, speed, energy, power, pressure, data or time conversion.","Temperatures, where an absolute reading and a temperature difference are not the same sum.","Currency, which needs a rate you supply — this tool never invents an exchange rate.","Indian land units (bigha, katha, cent, ground, guntha, ankanam) and lakh/crore scaling.","mpg ↔ L/100 km ↔ km/L, with US and imperial gallons kept apart.","Recipe scaling that crosses cups and grams, with the ingredient's density stated.","Shoe and clothing sizes across US, UK and EU charts."],"network":false,"related":"[`scale`](/docs/tools/scale) when a unit change has to ripple through several line items · [`numbers`](/docs/tools/numbers) `format` to present the result for a locale · [`fx_rate`](/docs/tools/fx_rate) for live exchange rates.","docs_url":"/docs/tools/convert","modes":[{"name":"units","purpose":"Convert between physical units.","description":"Converts `value` from one unit to another. Aliases and human spellings are accepted (`sqft`, `kmph`, `lbs`, `cbm`, `mAh`-style compounds, `lakh`, `crore`), and the response includes the conversion `factor` — plus `factor_exact` when the factor is a clean rational, so `1 mile = 1609.344 m` can be checked rather than trusted. Assumptions that matter are surfaced: statute miles, SI vs binary bytes, the length of a “month”.\n\nThe arithmetic is exact whatever the magnitude — `1e400 km` really is `1e403 m`. Only `value` is a JSON number, and that has a range: past about 1.8e308 it reads `Infinity`, below about 5e-324 it reads `0`, and in either case the exact answer is in `value_exact` and the loss is named in `warnings`. An ordinary conversion carries neither.","parameters":[{"name":"value","type":"number \\| string","required":true,"doc":"The quantity to convert.","default":"1"},{"name":"from_unit","type":"string","required":true,"doc":"Source unit.","default":null},{"name":"to_unit","type":"string","required":true,"doc":"Target unit.","default":null},{"name":"assume","type":"string","required":false,"doc":"`common` resolves an ambiguous unit to its usual reading instead of failing.","default":null},{"name":"precision","type":"integer","required":false,"doc":"Significant digits in the result.","default":"10"}],"examples":[{"mode":"units","value":5,"from_unit":"km","to_unit":"miles"},{"mode":"units","value":1500,"from_unit":"sqft","to_unit":"sqm"},{"mode":"units","value":1,"from_unit":"gigabyte","to_unit":"gibibyte"},{"mode":"units","value":1,"from_unit":"ton","to_unit":"kg","assume":"common"},{"mode":"units","value":1,"from_unit":"bigha","to_unit":"sqft"},{"mode":"units","value":1,"from_unit":"ton","to_unit":"kg"},{"mode":"units","value":1,"from_unit":"gallon","to_unit":"liter"},{"mode":"units","value":8,"from_unit":"oz","to_unit":"g"},{"mode":"units","value":1,"from_unit":"GB","to_unit":"MB"},{"mode":"units","value":5,"from_unit":"km","to_unit":"kg"},{"mode":"units","value":5,"from_unit":"blorg","to_unit":"km"},{"mode":"units","value":5,"from_unit":"km"}]},{"name":"temperature","purpose":"Absolute temperatures and temperature differences.","description":"Temperature conversion, where the distinction that trips everyone up is explicit: an absolute reading (25 °C is 77 °F) and a difference (a rise of 25 °C is a rise of 45 °F) are different sums. Absolute is the default and is stated in `assumptions`; pass `delta: true` for a difference. `C`, `F`, `K`, `°C`, `celsius`, `degF` and friends all resolve. A *reading* below absolute zero is refused; a *difference* may be any sign.","parameters":[{"name":"value","type":"number \\| string","required":true,"doc":"The temperature.","default":"1"},{"name":"from_unit","type":"string","required":true,"doc":"Source scale: `C`, `F`, `K`, `degR`…","default":null},{"name":"to_unit","type":"string","required":true,"doc":"Target scale.","default":null},{"name":"delta","type":"boolean","required":false,"doc":"Treat the value as a difference, not a reading. A difference may be below absolute zero; a reading may not, and is refused.","default":"`false`"},{"name":"precision","type":"integer","required":false,"doc":"Significant digits in the result.","default":"10"}],"examples":[{"mode":"temperature","value":-500,"from_unit":"C","to_unit":"K"},{"mode":"temperature","value":100,"from_unit":"C","to_unit":"F"},{"mode":"temperature","value":100,"from_unit":"C","to_unit":"F","delta":true},{"mode":"temperature","value":98.6,"from_unit":"F","to_unit":"K"},{"mode":"temperature","value":100,"from_unit":"C","to_unit":"km"},{"mode":"temperature","value":100,"to_unit":"F"}]},{"name":"currency","purpose":"Convert money using a rate you supply.","description":"Converts an amount between ISO 4217 currency codes. There is no built-in rate table and no network call: pass `rate` (1 `from_unit` = `rate` `to_unit`) or a `rates` map, and the rate used is echoed in `assumptions`. Without either, the call fails with `needs_rates` and tells you how to get one. The result carries both the rounded value and `value_exact` as a fraction, so a chain of conversions never accumulates rounding error. A rate of zero or less is refused — a rate is how many `to_unit` one `from_unit` buys.","parameters":[{"name":"value","type":"number \\| string","required":true,"doc":"The amount.","default":"1"},{"name":"from_unit","type":"string","required":true,"doc":"Source ISO 4217 code, e.g. `USD`.","default":null},{"name":"to_unit","type":"string","required":true,"doc":"Target ISO 4217 code.","default":null},{"name":"rate","type":"number","required":false,"doc":"Direct rate: 1 `from_unit` = `rate` `to_unit`.","default":null},{"name":"rates","type":"object","required":false,"doc":"Rate table keyed by currency code.","default":null},{"name":"base","type":"string","required":false,"doc":"Base currency of the `rates` table.","default":null},{"name":"decimals","type":"integer","required":false,"doc":"Decimal places in the rounded value.","default":"2"},{"name":"date","type":"string","required":false,"doc":"Echoed back as `as_of`; the tool does not use it to look anything up.","default":null}],"examples":[{"mode":"currency","value":100,"from_unit":"USD","to_unit":"INR","rate":83.42},{"mode":"currency","value":250,"from_unit":"EUR","to_unit":"INR","rates":{"USD":1,"EUR":0.92,"INR":83.42},"base":"USD"},{"mode":"currency","value":100,"from_unit":"USD","to_unit":"JPY","rate":147.2,"decimals":0},{"mode":"currency","value":100,"from_unit":"USD","to_unit":"INR"},{"mode":"currency","value":100,"from_unit":"DOLLAR","to_unit":"INR","rate":83.42},{"mode":"currency","value":100,"from_unit":"AUD","to_unit":"INR","rates":{"USD":1,"EUR":0.92}}]},{"name":"fuel_economy","purpose":"mpg (US or UK), km/L and L/100 km.","description":"Converts between `mpg_us`, `mpg_uk`, `km_per_l` and `l_per_100km` with exact constants (mile 1.609344 km, US gallon 3.785411784 L, imperial gallon 4.54609 L). A bare `mpg` is refused with both gallons as options — they differ by 20%. L/100 km is an inverse quantity, and any conversion that crosses it says so in `assumptions`: doubling the mpg halves the L/100 km, but a 10 mpg improvement saves far more fuel at 20 mpg than at 50. The result carries `km_per_l` as the common intermediate so a chain of conversions can be checked.","parameters":[{"name":"value","type":"number \\| string","required":true,"doc":"The fuel economy figure; must be positive.","default":"1"},{"name":"from_unit","type":"string","required":true,"doc":"`mpg_us`, `mpg_uk`, `km_per_l` or `l_per_100km` (aliases `km/l`, `kmpl`, `l/100km`, `mpg (uk)`…).","default":null},{"name":"to_unit","type":"string","required":true,"doc":"Target figure, same choices.","default":null},{"name":"decimals","type":"integer","required":false,"doc":"Decimal places in the rounded value.","default":"2"}],"examples":[{"mode":"fuel_economy","value":30,"from_unit":"mpg_us","to_unit":"l_per_100km"},{"mode":"fuel_economy","value":6.5,"from_unit":"l_per_100km","to_unit":"mpg_uk"},{"mode":"fuel_economy","value":15,"from_unit":"km/l","to_unit":"mpg_us","decimals":4},{"mode":"fuel_economy","value":30,"from_unit":"mpg","to_unit":"l_per_100km"},{"mode":"fuel_economy","value":0,"from_unit":"mpg_us","to_unit":"l_per_100km"}]},{"name":"cooking","purpose":"Cups, spoons, ml and grams by ingredient density.","description":"Converts kitchen measures: volume (`cup`, `tbsp`, `tsp`, `ml`, `l`, `fl_oz`) and mass (`g`, `kg`, `oz_weight`, `lb`). Volume to volume and mass to mass need nothing else. Crossing between them needs `ingredient`, looked up in a built-in density table (water, milk, cream, yogurt, oil, honey, maple syrup, flour, cornstarch, cocoa, sugar, brown sugar, powdered sugar, butter, peanut butter, rice, oats, salt); a missing or unknown ingredient comes back as `ambiguous` with the table as `needs.options`, and the grams-per-cup used are stated in `assumptions`. The cup system defaults to US (240 ml cup, 15 ml tbsp) and is declared; `cup: metric|uk|au` switches to the 250 ml cup — and the Australian 20 ml tablespoon. `oz` alone is refused: weight or fluid.","parameters":[{"name":"value","type":"number \\| string","required":true,"doc":"The quantity.","default":"1"},{"name":"from_unit","type":"string","required":true,"doc":"Source measure.","default":null},{"name":"to_unit","type":"string","required":true,"doc":"Target measure.","default":null},{"name":"ingredient","type":"string","required":false,"doc":"Required for mass ↔ volume: `flour`, `sugar`, `butter`… (`plain flour`, `icing sugar` and similar spellings resolve).","default":null},{"name":"cup","type":"string","required":false,"doc":"Cup system: `us`, `metric`, `uk` or `au`.","default":"`us`"},{"name":"decimals","type":"integer","required":false,"doc":"Decimal places in the rounded value.","default":"2"}],"examples":[{"mode":"cooking","value":1,"from_unit":"cup","to_unit":"g","ingredient":"flour"},{"mode":"cooking","value":200,"from_unit":"g","to_unit":"cups","ingredient":"sugar"},{"mode":"cooking","value":2,"from_unit":"tbsp","to_unit":"ml","cup":"au"},{"mode":"cooking","value":1,"from_unit":"cup","to_unit":"g"},{"mode":"cooking","value":1,"from_unit":"cup","to_unit":"g","ingredient":"quinoa"},{"mode":"cooking","value":8,"from_unit":"oz","to_unit":"g","ingredient":"butter"}]},{"name":"sizes","purpose":"Shoe and clothing size charts.","description":"Table lookups, not arithmetic, so every result carries a warning that sizes are approximate and names the chart. `category: shoe` converts between `us_men`, `us_women`, `uk`, `eu` and `cm` (foot length) on a generic adult chart (US men = UK + 1, US women = US men + 1.5); a plain `us` is refused unless `gender` is given, and a value between rows snaps to the nearest half size with a warning. `category: clothing` maps `alpha` (XS–XXL) to `chest_cm` and `waist_cm` bands and back for a chart chosen by `region` and `gender`, both required: `us` is the generic inch-based retail chart, `eu` the EN 13402-3 letter codes (chest/bust only — `waist_cm` there is `unsupported`). The whole chart `row` is returned alongside the value.","parameters":[{"name":"value","type":"number \\| string","required":true,"doc":"The size: a number, or a letter size (`M`, `XL`) when `from_unit` is `alpha`.","default":"1"},{"name":"from_unit","type":"string","required":true,"doc":"Shoes: `us_men`, `us_women`, `uk`, `eu`, `cm`. Clothing: `alpha`, `chest_cm`, `waist_cm`.","default":null},{"name":"to_unit","type":"string","required":true,"doc":"Target scale, same choices.","default":null},{"name":"category","type":"string","required":true,"doc":"`shoe` or `clothing`.","default":null},{"name":"region","type":"string","required":false,"doc":"Clothing chart: `us` or `eu`. Shoes carry the region in the scale name.","default":null},{"name":"gender","type":"string","required":false,"doc":"`men` or `women`; required for clothing, resolves a plain `us` shoe size.","default":null},{"name":"decimals","type":"integer","required":false,"doc":"Decimal places for cm bands (clothing).","default":"1"}],"examples":[{"mode":"sizes","category":"shoe","value":9,"from_unit":"us_men","to_unit":"eu"},{"mode":"sizes","category":"shoe","value":25,"from_unit":"cm","to_unit":"us_women"},{"mode":"sizes","category":"clothing","value":100,"from_unit":"chest_cm","to_unit":"alpha","region":"us","gender":"men"},{"mode":"sizes","category":"clothing","value":"M","from_unit":"alpha","to_unit":"chest_cm","region":"eu","gender":"women"},{"mode":"sizes","category":"shoe","value":9,"from_unit":"us","to_unit":"eu"},{"mode":"sizes","category":"clothing","value":100,"from_unit":"chest_cm","to_unit":"alpha","gender":"men"},{"mode":"sizes","value":9,"from_unit":"us_men","to_unit":"eu"}]},{"name":"auto","purpose":"Pick units or currency from the arguments.","description":"The default mode. If both units look like ISO 4217 currency codes — three upper-case letters — the call is treated as a currency conversion; otherwise it is a unit conversion. Everything else behaves exactly as in the mode it dispatches to, ambiguity refusals included. Name the mode explicitly when you want to be certain which path you get; `fuel_economy`, `cooking` and `sizes` are never chosen by `auto`.","parameters":[{"name":"value","type":"number \\| string","required":true,"doc":"The quantity or amount.","default":"1"},{"name":"from_unit","type":"string","required":true,"doc":"Source unit or currency code.","default":null},{"name":"to_unit","type":"string","required":true,"doc":"Target unit or currency code.","default":null},{"name":"rate","type":"number","required":false,"doc":"Rate, when the arguments resolve to a currency conversion.","default":null},{"name":"rates","type":"object","required":false,"doc":"Rate table, as in `currency`.","default":null},{"name":"assume","type":"string","required":false,"doc":"`common`, as in `units`.","default":null}],"examples":[{"mode":"auto","value":10,"from_unit":"km","to_unit":"mi"},{"mode":"auto","value":100,"from_unit":"USD","to_unit":"INR","rate":83.42},{"mode":"auto","value":100,"from_unit":"USD","to_unit":"INR"},{"mode":"auto","value":1,"from_unit":"ton","to_unit":"kg"}]}]}