Chemical Equation
Balancer API

Overview

The Chemical Equation Balancer API balances chemical equations and returns normalized coefficients with step-by-step balancing details. It also validates equation syntax, exposes element metadata (atomic number, mass, group, period), and provides 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

Balance Equation

Balances a chemical equation and returns coefficients plus balancing steps.

Request

{
  "equation": "CH4 + O2 -> CO2 + H2O"
}

Response

{
  "success": true,
  "balanced_equation": "CH4 + 2O2 -> CO2 + 2H2O",
  "elements_found": ["C","H","O"],
  "coefficients": [1,2,1,2]
}

Code Examples

import requests

url = "https://api.chemhub.com/api/v1/chemical_equation_balancer/balance"

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

data = {"equation": "CH4 + O2 -> CO2 + H2O"}

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

curl -X POST https://api.chemhub.com/api/v1/chemical_equation_balancer/balance \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_secret" \
-H "Content-Type: application/json" \
-d '{"equation":"CH4 + O2 -> CO2 + H2O"}'

fetch('https://api.chemhub.com/api/v1/chemical_equation_balancer/balance', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key',
    'X-API-Secret': 'your_secret'
  },
  body: JSON.stringify({ equation: 'CH4 + O2 -> CO2 + H2O' })
})
.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 ChemicalBalancer {
    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 balanceEquation(String equation) throws Exception {
        String json = String.format("{\"equation\": \"%s\"}", equation);
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/chemical_equation_balancer/balance"))
            .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 = balanceEquation("CH4 + O2 -> CO2 + H2O");
        System.out.println(result);
    }
}

Validate Equation

Validates chemical equation syntax without balancing.

Request

{
  "equation": "H2 + O2 -> H2O"
}

Response

{
  "success": true,
  "valid": true,
  "message": "Equation is valid"
}

Code Examples

import requests

url = "https://api.chemhub.com/api/v1/chemical_equation_balancer/validate"

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

data = {"equation": "H2 + O2 -> H2O"}

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

curl -X POST https://api.chemhub.com/api/v1/chemical_equation_balancer/validate \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_secret" \
-H "Content-Type: application/json" \
-d '{"equation":"H2 + O2 -> H2O"}'

fetch('https://api.chemhub.com/api/v1/chemical_equation_balancer/validate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': 'your_api_key',
    'X-API-Secret': 'your_secret'
  },
  body: JSON.stringify({ equation: 'H2 + O2 -> H2O' })
})
.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 ChemicalValidator {
    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 validateEquation(String equation) throws Exception {
        String json = String.format("{\"equation\": \"%s\"}", equation);
        
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/chemical_equation_balancer/validate"))
            .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 = validateEquation("H2 + O2 -> H2O");
        System.out.println(result);
    }
}

Element Info

Gets information about a chemical element (name, atomic number, mass, etc.).

Response

{
  "name": "Hydrogen",
  "symbol": "H",
  "atomic_number": 1,
  "mass": 1.008,
  "group": 1,
  "period": 1
}

Code Examples

import requests

url = "https://api.chemhub.com/api/v1/chemical_equation_balancer/element_info/H"

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/chemical_equation_balancer/element_info/H \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_secret"

fetch('https://api.chemhub.com/api/v1/chemical_equation_balancer/element_info/H', {
  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 ElementInfo {
    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 getElementInfo(String element) throws Exception {
        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + "/chemical_equation_balancer/element_info/" + element))
            .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 = getElementInfo("H");
        System.out.println(result);
    }
}

Health Check

Health check endpoint to verify API status.

Response

{
  "success": true,
  "status": "healthy",
  "chemical_equation_balancer_backends": ["default"],
  "max_equation_length": 500
}

Code Examples

import requests

url = "https://api.chemhub.com/api/v1/chemical_equation_balancer/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/chemical_equation_balancer/health \
-H "X-API-Key: your_api_key" \
-H "X-API-Secret: your_secret"

fetch('https://api.chemhub.com/api/v1/chemical_equation_balancer/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 + "/chemical_equation_balancer/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);
    }
}

Python SDK

Complete Python SDK with all endpoints and error handling.

import requests
import json

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():
    response = session.get(f"{BASE_URL}/api/v1/chemical_equation_balancer/health")
    return response.json()

# --- Validate Equation ---
def validate_equation(equation):
    response = session.post(
        f"{BASE_URL}/api/v1/chemical_equation_balancer/validate",
        json={"equation": equation}
    )
    return response.json()

# --- Balance Equation ---
def balance_equation(equation):
    response = session.post(
        f"{BASE_URL}/api/v1/chemical_equation_balancer/balance",
        json={"equation": equation}
    )
    
    if response.status_code == 200:
        result = response.json()
        if result['success']:
            return {
                'balanced': result['balanced_equation'],
                'elements': result['elements_found'],
                'steps': result['balancing_steps'],
                'coefficients': result['coefficients']
            }
    return None

# --- Get Element Information ---
def get_element_info(element):
    response = session.get(
        f"{BASE_URL}/api/v1/chemical_equation_balancer/element_info/{element}"
    )
    return response.json()

# --- Test All Endpoints ---
def test_chemical_api():
    print("=== Chemical Equation Balancer API Test ===")
    
    # Health check
    health = check_health()
    print(f"Health: {health.get('status', 'unknown')}")
    
    # Test equations
    equations = [
        "H2 + O2 -> H2O",
        "CH4 + O2 -> CO2 + H2O",
        "Fe + O2 -> Fe2O3",
        "KMnO4 + HCl -> KCl + MnCl2 + Cl2 + H2O"
    ]
    
    for equation in equations:
        print(f"\nTesting: {equation}")
        
        # Validate
        validation = validate_equation(equation)
        print(f"Valid: {validation.get('valid', False)}")
        
        # Balance
        result = balance_equation(equation)
        if result:
            print(f"Balanced: {result['balanced']}")
            print(f"Elements: {', '.join(result['elements'])}")
        else:
            print("Balancing failed")
    
    # Test element info
    elements = ["H", "O", "C", "Fe", "Au"]
    for element in elements:
        info = get_element_info(element)
        # API returns element data directly, not wrapped in success/element_info
        if 'name' in info and info['name'] != 'Unknown':
            print(f"{element}: {info['name']} (#{info['atomic_number']})")
        else:
            print(f"{element}: Unknown element")

if __name__ == "__main__":
    test_chemical_api()

Errors & Status Codes

Error Response Format

{
  "success": false,
  "error": {
    "code": 400,
    "message": "Invalid equation syntax"
  }
}

Status Codes

• 200Success
• 400Bad Request
• 401Unauthorized
• 429Rate Limited

Rate Limits