Measurement API

Quick Start

Make your first conversion in under a minute.

1. 1

   Request an API key

   Contact us to get a Bearer API key. Keys use the uu_live_ prefix for production.

   Request API Access →
2. 2

   Store it securely

   Set the key as an environment variable. Never commit it to source control or embed it in client-side code.

   bashCopy

   export UNIFYUNITS_API_KEY="uu_live_your_key_here"

3. 3

   Make your first conversion

   Convert 1 foot to meters using the GET endpoint:

   bashCopy

   curl "https://api.unifyunits.com/v1/convert?value=1&from=ft&to=m" \
     -H "Authorization: Bearer $UNIFYUNITS_API_KEY"

4. 4

   Read the response

   The result is always a decimal string. 1 ft = 0.3048 m exactly.

   json

   {
     "data": {
       "input":  { "value": "1",      "unit": "ft" },
       "result": { "value": "0.3048", "unit": "m"  },
       "category": "length"
     }
   }

5. 5

   Try batch conversion

   Convert multiple measurements in a single request with up to 100 items per call.

   bashCopy

   curl "https://api.unifyunits.com/v1/batch" \
     -X POST \
     -H "Authorization: Bearer $UNIFYUNITS_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"conversions":[
       {"value":"1","from":"ft","to":"m"},
       {"value":"32","from":"F","to":"C"}
     ]}'

Authentication

Conversion endpoints require a Bearer API key. Discovery endpoints (/v1/categories,/v1/units,/v1/health,/openapi.json) are public.

Authorization header

Authorization: Bearer uu_live_xxxxxxxxxxxxxxxxxxxxxxxxxx

Endpoint access table

Key rotation

Rotate keys without downtime by following these steps:

1. Request a replacement key
2. Deploy your service with the new key
3. Verify traffic is flowing correctly
4. Revoke the old key

Use separate keys for separate environments. Never reuse a key across production and development.

API Reference

Base URL: https://api.unifyunits.com

All responses use Content-Type: application/json. Values are always decimal strings, not JSON numbers. Every response includes an X-Request-Id header.

curl "https://api.unifyunits.com/v1/convert?value=10&from=kg&to=lb" \
  -H "Authorization: Bearer $UNIFYUNITS_API_KEY"

{
  "data": {
    "input": {
      "value": "10",
      "unit": "kg"
    },
    "result": {
      "value": "22.046226218487758",
      "unit": "lb"
    },
    "category": "mass"
  }
}

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"
  }'

{
  "data": {
    "input": {
      "value": "1",
      "unit": "ft"
    },
    "result": {
      "value": "0.3048",
      "unit": "m"
    },
    "category": "length"
  }
}

curl "https://api.unifyunits.com/v1/batch" \
  -X POST \
  -H "Authorization: Bearer $UNIFYUNITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversions": [
      { "value": "1", "from": "ft", "to": "m" },
      { "value": "32", "from": "F", "to": "C" }
    ]
  }'

{
  "data": [
    {
      "index": 0,
      "status": "success",
      "input": { "value": "1", "unit": "ft" },
      "result": { "value": "0.3048", "unit": "m" },
      "category": "length"
    },
    {
      "index": 1,
      "status": "success",
      "input": { "value": "32", "unit": "F" },
      "result": { "value": "0", "unit": "C" },
      "category": "temperature"
    }
  ],
  "meta": {
    "total": 2,
    "succeeded": 2,
    "failed": 0
  }
}

curl "https://api.unifyunits.com/v1/categories"

{
  "data": [
    { "id": "length",      "name": "Length",      "unit_count": 11 },
    { "id": "mass",        "name": "Mass",        "unit_count": 10 },
    { "id": "temperature", "name": "Temperature", "unit_count": 5  },
    { "id": "area",        "name": "Area",        "unit_count": 10 }
  ]
}

curl "https://api.unifyunits.com/v1/categories/mass"

{
  "data": {
    "id": "mass",
    "name": "Mass",
    "units": [
      { "id": "kg",  "name": "Kilogram", "symbol": "kg" },
      { "id": "lb",  "name": "Pound",    "symbol": "lb" },
      { "id": "g",   "name": "Gram",     "symbol": "g"  }
    ]
  }
}

# All units
curl "https://api.unifyunits.com/v1/units"

# Filter by category
curl "https://api.unifyunits.com/v1/units?category=mass"

{
  "data": [
    { "id": "kg", "name": "Kilogram", "symbol": "kg", "category": "mass" },
    { "id": "lb", "name": "Pound",    "symbol": "lb", "category": "mass" }
  ],
  "meta": { "count": 2 }
}

curl "https://api.unifyunits.com/v1/units/kg"

{
  "data": {
    "id": "kg",
    "name": "Kilogram",
    "symbol": "kg",
    "category": "mass",
    "aliases": ["kilogram", "kilograms"]
  }
}

curl "https://api.unifyunits.com/v1/health"

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2026-09-24T00:00:00Z"
}

curl "https://api.unifyunits.com/openapi.json"

{
  "openapi": "3.1.0",
  "info": {
    "title": "UnifyUnits Measurement API",
    "version": "0.1.0"
  },
  "paths": { ... }
}

Code Examples

Complete integration examples for the most common languages. All examples assume you have set UNIFYUNITS_API_KEY in your environment.

# GET conversion
curl "https://api.unifyunits.com/v1/convert?value=10&from=kg&to=lb" \
  -H "Authorization: Bearer $UNIFYUNITS_API_KEY"

# POST conversion
curl "https://api.unifyunits.com/v1/convert" \
  -X POST \
  -H "Authorization: Bearer $UNIFYUNITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"value":"10","from":"kg","to":"lb"}'

curl "https://api.unifyunits.com/v1/batch" \
  -X POST \
  -H "Authorization: Bearer $UNIFYUNITS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "conversions": [
      {"value":"10","from":"kg","to":"lb"},
      {"value":"100","from":"km","to":"mi"},
      {"value":"32","from":"F","to":"C"}
    ]
  }'

# List all categories
curl "https://api.unifyunits.com/v1/categories"

# Units in a category
curl "https://api.unifyunits.com/v1/units?category=mass"

# Look up a unit
curl "https://api.unifyunits.com/v1/units/kg"

const response = await fetch(
  "https://api.unifyunits.com/v1/convert?value=1&from=ft&to=m",
  {
    headers: {
      Authorization: `Bearer ${process.env.UNIFYUNITS_API_KEY}`,
    },
  }
);

if (!response.ok) {
  const error = await response.json();
  throw new Error(`${error.error.code}: ${error.error.message}`);
}

const body = await response.json();
console.log(body.data.result.value); // "0.3048"

const response = await fetch("https://api.unifyunits.com/v1/batch", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.UNIFYUNITS_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    conversions: [
      { value: "10", from: "kg", to: "lb" },
      { value: "100", from: "km", to: "mi" },
    ],
  }),
});

const { data, meta } = await response.json();

for (const item of data) {
  if (item.status === "success") {
    console.log(`Item ${item.index}: ${item.result.value} ${item.result.unit}`);
  } else {
    console.error(`Item ${item.index} failed: ${item.error.code}`);
  }
}

async function convert(value: string, from: string, to: string) {
  const url = new URL("https://api.unifyunits.com/v1/convert");
  url.searchParams.set("value", value);
  url.searchParams.set("from", from);
  url.searchParams.set("to", to);

  const res = await fetch(url, {
    headers: { Authorization: `Bearer ${process.env.UNIFYUNITS_API_KEY}` },
  });

  const body = await res.json();

  if (!res.ok) {
    // Use error.code for programmatic handling, not error.message
    switch (body.error.code) {
      case "UNKNOWN_UNIT":
        throw new Error(`Unknown unit. Check GET /v1/units for valid IDs.`);
      case "INCOMPATIBLE_UNITS":
        throw new Error(`Cannot convert between ${from} and ${to}. Different categories.`);
      case "RATE_LIMIT_EXCEEDED":
        // Implement exponential backoff here
        throw new Error("Rate limited. Retry after backoff.");
      default:
        throw new Error(`API error: ${body.error.code}`);
    }
  }

  return body.data.result.value;
}

import os
import requests

response = requests.get(
    "https://api.unifyunits.com/v1/convert",
    params={"value": "1", "from": "ft", "to": "m"},
    headers={"Authorization": f"Bearer {os.environ['UNIFYUNITS_API_KEY']}"},
    timeout=10,
)

response.raise_for_status()

data = response.json()
print(data["data"]["result"]["value"])  # "0.3048"

import os
import requests

response = requests.post(
    "https://api.unifyunits.com/v1/batch",
    json={
        "conversions": [
            {"value": "10", "from": "kg", "to": "lb"},
            {"value": "100", "from": "km", "to": "mi"},
        ]
    },
    headers={"Authorization": f"Bearer {os.environ['UNIFYUNITS_API_KEY']}"},
    timeout=10,
)

response.raise_for_status()
result = response.json()

for item in result["data"]:
    if item["status"] == "success":
        print(f"Item {item['index']}: {item['result']['value']} {item['result']['unit']}")
    else:
        print(f"Item {item['index']} failed: {item['error']['code']}")

import os
import requests
from requests.exceptions import HTTPError

def convert(value: str, from_unit: str, to_unit: str) -> str:
    try:
        r = requests.get(
            "https://api.unifyunits.com/v1/convert",
            params={"value": value, "from": from_unit, "to": to_unit},
            headers={"Authorization": f"Bearer {os.environ['UNIFYUNITS_API_KEY']}"},
            timeout=10,
        )
        r.raise_for_status()
        return r.json()["data"]["result"]["value"]
    except HTTPError as e:
        err = e.response.json()["error"]
        raise ValueError(f"{err['code']}: {err['message']}")

<?php

$url = 'https://api.unifyunits.com/v1/convert?value=1&from=ft&to=m';

$ch = curl_init($url);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('UNIFYUNITS_API_KEY'),
    ],
    CURLOPT_TIMEOUT => 10,
]);

$response = curl_exec($ch);
$status   = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

if ($status < 200 || $status >= 300) {
    $error = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
    throw new RuntimeException($error['error']['code'] . ': ' . $error['error']['message']);
}

$data = json_decode($response, true, 512, JSON_THROW_ON_ERROR);
echo $data['data']['result']['value']; // "0.3048"

<?php

$payload = json_encode([
    'conversions' => [
        ['value' => '10',  'from' => 'kg', 'to' => 'lb'],
        ['value' => '100', 'from' => 'km', 'to' => 'mi'],
    ],
]);

$ch = curl_init('https://api.unifyunits.com/v1/batch');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => $payload,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . getenv('UNIFYUNITS_API_KEY'),
        'Content-Type: application/json',
    ],
    CURLOPT_TIMEOUT => 10,
]);

$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true, 512, JSON_THROW_ON_ERROR);

foreach ($result['data'] as $item) {
    if ($item['status'] === 'success') {
        echo "Item {$item['index']}: {$item['result']['value']} {$item['result']['unit']}\n";
    } else {
        echo "Item {$item['index']} failed: {$item['error']['code']}\n";
    }
}

Precision & Numeric Values

{"value": "0.1", "from": "m", "to": "cm"}

{"value": 0.1, "from": "m", "to": "cm"}

Accepted numeric formats

Temperature conversions

Temperature uses affine conversion (offset + scale), not simple multiplication. Results are deterministic for the same input under the same API version.

Error Reference

All errors follow the same envelope. Use error.code for programmatic handling — never match on error.message which may change.

{
  "error": {
    "code":       "ERROR_CODE",
    "message":    "Human-readable developer message.",
    "details":    {},           // optional, endpoint-specific
    "request_id": "01K..."     // present for server errors
  }
}

{
  "error": {
    "code":    "INCOMPATIBLE_UNITS",
    "message": "Units 'kg' and 'km' are not compatible.",
    "details": { "from": "kg", "to": "km" }
  }
}

Rate Limits & Pricing

Quota accounting

Versioning

The API uses three independent version dimensions. These should not be confused with each other.

Breaking vs non-breaking changes

Security Best Practices

CORS & Browser Clients

The API supports GET and POST with the Authorization header from browser origins. However, CORS is not a security boundary — any key visible to a browser can be extracted. Use browser-side API access only for scenarios where you intentionally accept the exposure risk (e.g., a developer playground where the key can be rotated freely).

For unifyunits.com itself, the website uses the shared core library locally and does not call the authenticated API from the browser.

Troubleshooting

# Browse all units
curl "https://api.unifyunits.com/v1/units"

# Check if a specific ID exists
curl "https://api.unifyunits.com/v1/units/kg"

// Check for Retry-After header
const retryAfter = response.headers.get("Retry-After");
const delay = retryAfter ? parseInt(retryAfter, 10) * 1000 : 2000;
await new Promise((r) => setTimeout(r, delay));

for (const item of body.data) {
  if (item.status === "error") {
    console.error(`Item ${item.index}: ${item.error.code} - ${item.error.message}`);
  }
}

Support & Resources

Contacting support

When reporting an issue, please include:

• The X-Request-Id header value from the failing response
• The endpoint and HTTP method you called
• Approximate timestamp (UTC)
• The error code from error.code
• Expected vs actual behaviour