UnifyUnitsDevelopers

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 V1Structured conversion and unit discoveryROADMAPParsing, 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 neatvalue, from, and to tuple.

INPUT YOUR APPLICATION MAY RECEIVE

82kg180 lbs5 ft 11 in1m 82cm100 MB100 MiB5 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?

ROADMAP BOUNDARYThe v1 API does not parse these free-form or mixed-unit strings. Callers must provide a separate decimal-string value and explicit unit identifiers.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.
  • 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. 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 MiBare 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 is the implemented foundation. The 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. ROADMAPParseTurn 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. ROADMAPNormalizeProduce a chosen canonical representation for heterogeneous data.
  5. ROADMAPValidateApply expected-dimension and application constraints to measurements.

Data ingestion ROADMAP

A future normalization workflow could turn heights such as5 ft 11 in, 182cm, and70 inches into a chosen canonical unit. Today, your application must parse and structure those inputs before calling Convert.

AI systems ROADMAP

An agent may generate a measurement in natural language. A future deterministic parse and validation layer could check it before an application stores or acts on it. Today, the API can convert already-structured measurements only.

Measurement schemas, compound-unit processing, and AI/MCP integration are also 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 andOpenAPI document describe the HTTP surface. The unit catalog exposes canonical identifiers and aliases. Error codes aredocumented, and responses include a dataset version header. Catalog entries currently reportverification: "legacy"; that is not a standards certification or a claim that every factor is exact.