UnifyUnits Developers

POST /v1/substance/convert Requires API key

Convert between mass and volume for a substance

Converts between mass and volume using a substance's reference density, for example litres of ethanol to kilograms. The response includes the substance with its density, conditions, and source, because real density varies with temperature, pressure, and composition. Same-kind conversions (mass to mass) pass straight through. `GET /v1/substance/convert` accepts the same fields as query parameters. Requires the Developer plan or higher.

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
value string Yes Decimal amount as a string (e.g. "1")
from string Yes Mass or volume unit identifier
to string Yes Mass or volume unit identifier
substance string Yes Substance id from GET /v1/substances (e.g. "ethanol")
decimals integer No Round the result to this many fractional places (0-40, half-even).
format_locale string No Language tag such as de-DE. Adds a formatted display string to the result.

Possible errors

INVALID_REQUEST · INVALID_VALUE · UNKNOWN_UNIT · UNKNOWN_SUBSTANCE · INCOMPATIBLE_UNITS · OUT_OF_RANGE · PLAN_REQUIRED · UNAUTHORIZED · INVALID_API_KEY · RATE_LIMIT_EXCEEDED · QUOTA_EXCEEDED

All endpoints · Error reference

cURL
curl "https://api.unifyunits.com/v1/substance/convert" \
  -X POST \
  -H "Authorization: Bearer $UNIFYUNITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value":"1","from":"l","to":"kg","substance":"ethanol"}'

Response 200

json
{
  "data": {
    "input": { "value": "1", "unit": "l" },
    "result": { "value": "0.7893", "unit": "kg" },
    "substance": {
      "id": "ethanol",
      "name": "Ethanol (ethyl alcohol)",
      "category": "liquid",
      "density": { "value": "789.3", "unit": "kg-m3" },
      "conditions": "NIST radiation-calculation reference density; temperature and pressure not specified",
      "source": {
        "organization": "National Institute of Standards and Technology",
        "title": "STAR material composition: Ethyl alcohol",
        "url": "https://physics.nist.gov/cgi-bin/Star/compos.pl?matno=153",
        "accessed_date": "2026-09-13"
      }
    }
  }
}