Unit Converter
API Documentation

Overview

The Unit Converter API provides accurate conversions across 17 categories including length, weight, temperature, currency, area, volume, speed, time, data storage, bandwidth, pressure, energy, power, torque, frequency, fuel economy, and angle. With over 400 supported units, it offers a generic conversion endpoint, category-specific endpoints, category discovery, and a health check. Every request returns structured JSON with clear error codes.

Base URL & Authentication

Base URL

https://api.chemhub.com/api/v1

Authentication

Include your API credentials in every request header.

X-API-Key: your_api_key
X-API-Secret: your_secret
Content-Type: application/json

Get API Keys

Follow these steps to obtain your API credentials:

Endpoints

Health Check

Health check endpoint to verify the Unit Converter API status.

Response

{
  "success": true,
  "status": "healthy",
  "categories": ["length", "weight", "temperature", "currency", "area", "volume", "speed", "time", "storage", "bandwidth", "pressure", "energy", "power", "torque", "frequency", "fuel", "angle"],
  "timestamp": "2026-07-23T12:00:00"
}

Code Examples

import requests

url = "https://api.chemhub.com/api/v1/convert/health"

headers = {
    "X-API-Key": "your_api_key",
    "X-API-Secret": "your_secret"
}

res = requests.get(url, headers=headers)
print(res.json())

curl -X GET https://api.chemhub.com/api/v1/convert/health \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_secret"

fetch('https://api.chemhub.com/api/v1/convert/health', {
  method: 'GET',
  headers: {
    'X-API-Key': 'your_api_key',
    'X-API-Secret': 'your_secret'
  }
})
.then(res => res.json())
.then(console.log);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;

public class HealthCheck {
    private static final String BASE_URL = "https://api.chemhub.com/api/v1";
    private static final String API_KEY = "your_api_key";
    private static final String API_SECRET = "your_secret";

    private static final HttpClient client = HttpClient.newHttpClient();

    public static String checkHealth() throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/convert/health"))
            .header("X-API-Key", API_KEY)
            .header("X-API-Secret", API_SECRET)
            .GET()
            .build();

        HttpResponse response = client.send(
            request, BodyHandlers.ofString()
        );

        return response.body();
    }

    public static void main(String[] args) throws Exception {
        String result = checkHealth();
        System.out.println(result);
    }
}

Get Categories

Returns all available conversion categories with their supported units.

Response

{
  "success": true,
  "categories": [
    {
      "id": "length",
      "name": "Length",
      "units": ["meters", "kilometers", "centimeters", "millimeters", "micrometers", "nanometers", "miles", "yards", "feet", "inches", "nautical_miles"]
    },
    {
      "id": "weight",
      "name": "Weight",
      "units": ["kilograms", "grams", "milligrams", "micrograms", "metric_tons", "pounds", "ounces", "stones", "us_tons", "imperial_tons"]
    },
    {
      "id": "temperature",
      "name": "Temperature",
      "units": ["celsius", "fahrenheit", "kelvin"]
    }
  ]
}

Code Examples

import requests

url = "https://api.chemhub.com/api/v1/convert/categories"

headers = {
    "X-API-Key": "your_api_key",
    "X-API-Secret": "your_secret"
}

res = requests.get(url, headers=headers)
print(res.json())

curl -X GET https://api.chemhub.com/api/v1/convert/categories \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_secret"

fetch('https://api.chemhub.com/api/v1/convert/categories', {
  method: 'GET',
  headers: {
    'X-API-Key': 'your_api_key',
    'X-API-Secret': 'your_secret'
  }
})
.then(res => res.json())
.then(console.log);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpResponse.BodyHandlers;

public class GetCategories {
    private static final String BASE_URL = "https://api.chemhub.com/api/v1";
    private static final String API_KEY = "your_api_key";
    private static final String API_SECRET = "your_secret";

    private static final HttpClient client = HttpClient.newHttpClient();

    public static String getCategories() throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/convert/categories"))
            .header("X-API-Key", API_KEY)
            .header("X-API-Secret", API_SECRET)
            .GET()
            .build();

        HttpResponse response = client.send(
            request, BodyHandlers.ofString()
        );

        return response.body();
    }

    public static void main(String[] args) throws Exception {
        String result = getCategories();
        System.out.println(result);
    }
}

Generic Convert

Generic conversion endpoint. Specify the category, value, source unit, and target unit.

Request Parameters

• category: string, required — Conversion category (e.g. length, weight)
• value: number, required — Numeric value to convert
• from: string, required — Source unit name
• to: string, required — Target unit name

Request Body

{
  "category": "length",
  "value": 100,
  "from": "meters",
  "to": "feet"
}

Response

{
  "success": true,
  "category": "length",
  "category_name": "Length",
  "value": 100,
  "from_unit": "meters",
  "to_unit": "feet",
  "result": 328.0839895013123,
  "formula": "100 meters = 328.0839895013123 feet"
}

Code Examples

import requests

url = "https://api.chemhub.com/api/v1/convert"

headers = {
    "X-API-Key": "your_api_key",
    "X-API-Secret": "your_secret"
}

data = {
    "category": "length",
    "value": 100,
    "from": "meters",
    "to": "feet"
}

res = requests.post(url, json=data, headers=headers)
print(res.json())

curl -X POST https://api.chemhub.com/api/v1/convert \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_secret" \
-H "Content-Type: application/json" \
-d '{"category":"length","value":100,"from":"meters","to":"feet"}'

fetch('https://api.chemhub.com/api/v1/convert', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key',
    'X-API-Secret': 'your_secret'
  },
  body: JSON.stringify({
    category: 'length',
    value: 100,
    from: 'meters',
    to: 'feet'
  })
})
.then(res => res.json())
.then(console.log);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse.BodyHandlers;

public class UnitConverter {
    private static final String BASE_URL = "https://api.chemhub.com/api/v1";
    private static final String API_KEY = "your_api_key";
    private static final String API_SECRET = "your_secret";

    private static final HttpClient client = HttpClient.newHttpClient();

    public static String convert(String category, double value, String from, String to) throws Exception {
        String json = String.format(
            "{\"category\":\"%s\",\"value\":%f,\"from\":\"%s\",\"to\":\"%s\"}",
            category, value, from, to
        );

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/convert"))
            .header("Content-Type", "application/json")
            .header("X-API-Key", API_KEY)
            .header("X-API-Secret", API_SECRET)
            .POST(BodyPublishers.ofString(json))
            .build();

        HttpResponse response = client.send(request, BodyHandlers.ofString());
        return response.body();
    }

    public static void main(String[] args) throws Exception {
        String result = convert("length", 100, "meters", "feet");
        System.out.println(result);
    }
}

Category Convert

Category-specific conversion endpoint. Replace <category> with one of the supported categories. Supports the same request/response format as the generic endpoint.

Request Parameters

• value: number, required — Numeric value to convert
• from: string, required — Source unit name
• to: string, required — Target unit name

Request Body

{
  "value": 1,
  "from": "kilograms",
  "to": "pounds"
}

Response

{
  "success": true,
  "category": "weight",
  "category_name": "Weight",
  "value": 1,
  "from_unit": "kilograms",
  "to_unit": "pounds",
  "result": 2.2046226218487757,
  "formula": "1 kilograms = 2.2046226218487757 pounds"
}

Code Examples

import requests

url = "https://api.chemhub.com/api/v1/convert/weight"

headers = {
    "X-API-Key": "your_api_key",
    "X-API-Secret": "your_secret"
}

data = {
    "value": 1,
    "from": "kilograms",
    "to": "pounds"
}

res = requests.post(url, json=data, headers=headers)
print(res.json())

curl -X POST https://api.chemhub.com/api/v1/convert/weight \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_secret" \
-H "Content-Type: application/json" \
-d '{"value":1,"from":"kilograms","to":"pounds"}'

fetch('https://api.chemhub.com/api/v1/convert/weight', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key',
    'X-API-Secret': 'your_secret'
  },
  body: JSON.stringify({
    value: 1,
    from: 'kilograms',
    to: 'pounds'
  })
})
.then(res => res.json())
.then(console.log);

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.http.HttpRequest.BodyPublishers;
import java.net.http.HttpResponse.BodyHandlers;

public class WeightConverter {
    private static final String BASE_URL = "https://api.chemhub.com/api/v1";
    private static final String API_KEY = "your_api_key";
    private static final String API_SECRET = "your_secret";

    private static final HttpClient client = HttpClient.newHttpClient();

    public static String convertWeight(double value, String from, String to) throws Exception {
        String json = String.format(
            "{\"value\":%f,\"from\":\"%s\",\"to\":\"%s\"}",
            value, from, to
        );

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/convert/weight"))
            .header("Content-Type", "application/json")
            .header("X-API-Key", API_KEY)
            .header("X-API-Secret", API_SECRET)
            .POST(BodyPublishers.ofString(json))
            .build();

        HttpResponse response = client.send(request, BodyHandlers.ofString());
        return response.body();
    }

    public static void main(String[] args) throws Exception {
        String result = convertWeight(1, "kilograms", "pounds");
        System.out.println(result);
    }
}

Python SDK

Complete Python SDK with all endpoints and error handling.

import requests

BASE_URL = "https://your-api-domain.com"
API_KEY = "YOUR_API_KEY"
API_SECRET = "YOUR_API_SECRET"

session = requests.Session()
session.headers.update({
    "Content-Type": "application/json",
    "Accept": "application/json",
    "X-API-Key": API_KEY,
    "X-API-Secret": API_SECRET
})

# --- Health Check ---
def check_health():
    return session.get(f"{BASE_URL}/api/v1/convert/health").json()

# --- Get Categories ---
def get_categories():
    return session.get(f"{BASE_URL}/api/v1/convert/categories").json()

# --- Generic Convert ---
def convert(category, value, from_unit, to_unit):
    response = session.post(
        f"{BASE_URL}/api/v1/convert",
        json={
            "category": category,
            "value": value,
            "from": from_unit,
            "to": to_unit
        }
    )
    return response.json()

# --- Category-Specific Convert ---
def convert_length(value, from_unit, to_unit):
    response = session.post(
        f"{BASE_URL}/api/v1/convert/length",
        json={"value": value, "from": from_unit, "to": to_unit}
    )
    return response.json()

def convert_weight(value, from_unit, to_unit):
    response = session.post(
        f"{BASE_URL}/api/v1/convert/weight",
        json={"value": value, "from": from_unit, "to": to_unit}
    )
    return response.json()

# --- Test All Endpoints ---
def test_converter():
    print("=== Unit Converter API Test ===")

    health = check_health()
    print(f"Health: {health.get('status', 'unknown')}")

    cats = get_categories()
    print(f"Categories: {len(cats.get('categories', []))}")

    tests = [
        ("Generic length", convert("length", 100, "meters", "feet")),
        ("Weight", convert_weight(1, "kilograms", "pounds")),
        ("Temperature", convert("temperature", 100, "celsius", "fahrenheit")),
        ("Currency", convert("currency", 100, "us_dollars", "euros")),
    ]

    for name, result in tests:
        status = "OK" if result.get("success") else "FAIL"
        print(f"  {name}: {status}")

if __name__ == "__main__":
    test_converter()

Supported Categories

All 17 supported categories with their endpoint paths and sample units.

Errors & Status Codes

Error Response Format

{
  "success": false,
  "error": "Invalid input format"
}

Status Codes

• 200Success
• 400Bad Request
• 401Unauthorized
• 429Rate Limited
• 500Internal Server Error

Rate Limits