UnifyUnits Developers

POST /v1/normalize Requires API key

Normalize a messy quantity

Turns written quantities such as `2x500ml`, `1 lb 4 oz`, `10-12 cm`, `approx 5kg`, or `1,5 kg` into one canonical structure with the value in the category base unit. Deterministic: it never guesses units, so unknown or ambiguous units return the usual errors. See Normalize for the supported forms.

Prefer a language client when available: JavaScript / TypeScript, Python, or PHP (Laravel). Samples on this page stay raw HTTP so they match the OpenAPI contract.

Parameters

Name Type Required Description
text string Yes Written quantity (e.g. "2x500ml")
locale string No Language tag that decides ambiguous separators, e.g. "de-DE" reads "1,500" as 1.5. Default reads "1,500" as 1500.
decimals integer No Round the base-unit values to this many fractional places (0-40, half-even).

Possible errors

INVALID_REQUEST · INVALID_VALUE · UNKNOWN_UNIT · AMBIGUOUS_UNIT · INCOMPATIBLE_UNITS · OUT_OF_RANGE · UNAUTHORIZED · INVALID_API_KEY · RATE_LIMIT_EXCEEDED · QUOTA_EXCEEDED

All endpoints · Error reference

cURL
curl "https://api.unifyunits.com/v1/normalize" \
  -X POST \
  -H "Authorization: Bearer $UNIFYUNITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"2x500ml"}'

Response 200

json
{
  "data": {
    "kind": "multipack",
    "qualifier": null,
    "category": "volume",
    "base_unit": "l",
    "count": 2,
    "each": { "value": "500", "unit": "ml" },
    "total": { "value": "1000", "unit": "ml" },
    "min": null,
    "max": null,
    "base": { "value": "1", "unit": "l" },
    "base_min": null,
    "base_max": null
  }
}