UnifyUnits Developers

A DEVELOPER DECISION GUIDE

Why UnifyUnits?

Unit conversion is easy. Reliable measurement handling isn't.

Anyone can multiply kilograms by a factor. Applications also need to decide which unit an input means, preserve decimal intent, reject incompatible quantities, and keep those decisions consistent across services. UnifyUnits is intended as measurement infrastructure for that growing work.

Try the API Read the API reference
CURRENT V1 Structured conversion and unit discovery ROADMAP Parsing, contextual resolution, normalization, and validation

01 / THE SIMPLE CASE

For a few fixed conversions, keep it local.

10 kglb

If this is all your application ever needs, a local library or a tested formula may be simpler. It avoids a network request and an external service dependency. The case for UnifyUnits starts when measurement rules spread beyond a few controlled values.

02 / WHERE THE WORK STARTS

Real inputs carry meaning, not just numbers.

Forms, imports, and external systems rarely arrive as a neat value, from, and to tuple.

INPUT YOUR APPLICATION MAY RECEIVE

82kg180 lbs5 ft 11 in 1m 82cm100 MB100 MiB 5 gal100 km/h

QUESTIONS THE APPLICATION MUST ANSWER

  • Where does the value end and the unit begin?
  • Does gallon mean US or Imperial? Is gal an explicit ID?
  • Is MB decimal data or MiB binary data?
  • Is this a bit or a B (byte), and does casing matter?
  • Is this unit compatible with the expected quantity?
  • What canonical form and precision should be stored?

CURRENT V1 Convert needs a separate decimal-string value and explicit unit identifiers. For free-form text, use Parse and Normalize, which return a canonical structure or an explicit error instead of guessing. See accepted input formats.

03 / BUILD OR BUY

Choose where measurement rules live.

A local library is a good choice when one application owns the inputs. A shared API can be useful when several systems need the same answers and one maintained unit catalog.

Build and maintain locally

  • Choose conversion factors and update the unit dataset.
  • Define aliases, regional meanings, and precision rules.
  • Test temperature, data units, invalid values, and boundaries.
  • Keep behavior aligned across languages and services.
  • Add parsing and domain-specific validation if needed.

Use the current UnifyUnits API

  • Send structured conversion requests to one HTTP contract.
  • Discover canonical units, categories, and aliases.
  • Receive decimal-string results and documented errors.
  • Share one versioned measurement behavior across callers.
  • Keep parsing and application-specific validation in your app today.

Compare the cost of an API dependency with the ongoing cost of definitions, tests, ambiguity policy, precision, and duplicated implementations. There is no universal winner and no assumed monetary saving.

04 / ARCHITECTURE

One measurement contract across services.

Without a shared contract, each service can make a different choice about aliases, rounding, or regional units. Callers of the same API contract use the same unit resolution and conversion rules. Record the X-UnifyUnits-Dataset-Version response header when reproducibility across dataset updates matters.

05 / CURRENT FOUNDATION

What v1 does today

CURRENT V1
  • Convert: one value by GET or POST, or independent values in a batch.
  • Parse: turn text such as 5 ft 11 in into a structured measurement with POST /v1/parse.
  • Normalize: read quantities such as 2x500ml or 10-12 cm into one canonical structure with POST /v1/normalize.
  • Currency: convert with European Central Bank reference rates, current or historical.
  • Substances: convert between mass and volume with a sourced reference density.
  • Unit price: compare offers by price per unit.
  • Locale formatting: add a display string next to the exact value with format_locale.
  • MCP: let agents call these tools through the remote MCP server.
  • Discover: list categories and units, including canonical IDs and aliases.
  • Reject ambiguity: return AMBIGUOUS_UNIT with candidate IDs instead of guessing.
  • Preserve decimal intent: accept decimal-string values and return decimal-string results.
  • Explain failures: distinguish invalid values, incompatible units, range errors, and authentication errors.

Precision is a contract, not a formatting detail.

JSON numbers can lose decimal intent before a request reaches the API. V1 requires decimal strings. The conversion core uses rational arithmetic to avoid intermediate rounding; terminating results retain their decimal value, while nonterminating results are rounded deterministically to 40 significant digits using half-even rounding. Callers may optionally set decimals (0-40) to round only the returned result string. Input size and magnitude are bounded. Read the precision guide.

AMBIGUITY IS REPORTED

gallonAMBIGUOUS_UNIT

Candidate IDs: gal (US) and imp-gal (Imperial).

MB and MiB are distinct canonical data units, as are bit and B. Use explicit IDs when the difference matters. See alias rules.

A real request

This POST request uses the current conversion endpoint. It requires a Bearer API key; the response uses the documented v1 envelope.

bash 
curl "https://api.unifyunits.com/v1/convert" \
  -X POST \
  -H "Authorization: Bearer $UNIFYUNITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "1",
    "from": "ft",
    "to": "m"
  }'
json 
{
  "data": {
    "input": { "value": "1", "unit": "ft" },
    "result": { "value": "0.3048", "unit": "m" },
    "category": "length"
  }
}

06 / DIRECTION

Where UnifyUnits is going

ROADMAP

Convert, Parse, and Normalize are implemented in v1. The remaining stages below describe intended product direction, not callable v1 endpoints or a release promise.

  1. CURRENT V1ConvertExplicit value and unit IDs to a decimal-string result.
  2. CURRENT V1ParseTurn input such as 5 ft 11 in into structured measurements.
  3. ROADMAPResolveUse context to resolve free-form unit meaning; v1 already resolves explicit IDs and unambiguous aliases.
  4. CURRENT V1NormalizeProduce a canonical representation for messy written quantities.
  5. ROADMAPValidateApply expected-dimension and application constraints to measurements.

Data ingestion CURRENT V1

Heights such as 5 ft 11 in, 182cm, and 70 inches can be read with Parse or Normalize and converted to one canonical unit. Unknown or ambiguous units return an error rather than a guess.

AI systems CURRENT V1

An agent can call the MCP server to parse and convert a measurement deterministically instead of doing the arithmetic itself. Expected-dimension validation of generated measurements is still roadmap.

Measurement schemas and expected-dimension validation are future exploration, not current v1 API capabilities.

07 / THE DECISION

When should you use UnifyUnits?

Consider the API when

  • Several services or languages need the same unit behavior.
  • You support multiple unit systems and external datasets.
  • Precision and explicit ambiguity handling matter.
  • Measurement logic is being duplicated or maintained repeatedly.
  • You want a shared catalog and documented error contract.

A local library may be better when

  • Only a handful of fixed conversions are needed.
  • Inputs are controlled inside one application.
  • You want to avoid a network and service dependency.
  • You are prepared to own the unit data and tests locally.

UnifyUnits does not remove every measurement task today. Its current value is shared conversion semantics and a maintained contract; the broader data-processing case depends on roadmap work.

08 / TRUST AND TRANSPARENCY

Inspect the contract and its limits.

The API reference and OpenAPI document describe the HTTP surface. The unit catalog exposes canonical identifiers and aliases. Error codes are documented, and responses include a dataset version header. Catalog entries currently report verification: "legacy"; that is not a standards certification or a claim that every factor is exact.