API Documentation

Technical reference for developers and integrations with Calcula.club.

Configuration schema

Each calculator is defined by a CalculatorConfig JSON object:

interface CalculatorConfig {
  name: string;             // Calculator name
  description: string;      // Short description
  icon: string;             // Emoji icon
  fields: Field[];          // Input fields
  formula: string;          // Main formula
  resultLabel: string;      // Result label text
  resultFormat: FormatType; // "number" | "currency" | "percent" | "integer"
  category?: string;
  theme?: { primary: string };
  extraResults?: ExtraResult[];
  resultThresholds?: ResultThreshold[];
  breakdown?: BreakdownItem[];
  pieConfig?: { segments: PieSegment[] };
}

Field:

interface Field {
  id: string;        // Unique identifier (used in formulas)
  label: string;     // Display text
  type: "number" | "slider" | "select" | "checkbox" | "section" | "radio" | "date" | "range" | "divider";
  default: number;
  min?: number;
  max?: number;
  step?: number;
  options?: { label: string; value: number }[];
  suffix?: string;
  helpText?: string;
  content?: string;  // For section/divider
  imageUrl?: string; // For divider
  showIf?: string;   // Conditional visibility formula
}

Formula engine

The formula engine supports:

Operators (by precedence):

^ — Power

*, /, % — Multiplication, division, modulo

+, - — Addition, subtraction

>, <, >=, <=, ==, != — Comparisons (return 1 or 0)

Unary operator: - (negation)

Functions:

Function	Signature	Description
`pow`	`pow(base, exp)`	Power
`sqrt`	`sqrt(x)`	Square root
`abs`	`abs(x)`	Absolute value
`round`	`round(x)`	Round to nearest integer
`floor`	`floor(x)`	Round down
`ceil`	`ceil(x)`	Round up
`min`	`min(a, b, ...)`	Minimum
`max`	`max(a, b, ...)`	Maximum
`avg`	`avg(a, b, ...)`	Arithmetic mean
`sum`	`sum(a, b, ...)`	Sum
`factorial`	`factorial(n)`	Factorial (n!)
`sin`	`sin(x)`	Sine (radians)
`cos`	`cos(x)`	Cosine
`tan`	`tan(x)`	Tangent
`asin`	`asin(x)`	Arcsine
`acos`	`acos(x)`	Arccosine
`atan`	`atan(x)`	Arctangent
`ln`	`ln(x)`	Natural logarithm
`log`	`log(x)`	Natural logarithm
`log10`	`log10(x)`	Base-10 logarithm
`exp`	`exp(x)`	e^x
`if`	`if(cond, then, else)`	Conditional (lazy evaluation)
`lookup`	`lookup(val, t1, r1, ..., default)`	Threshold-based lookup

Constants: pi (3.14159...), e (2.71828...)

Intermediate variables: Use name = expression; to define local variables. The last expression is the return value.

URL format

Calculators are encoded in the URL:

https://calcula.club/c/{encoded_config}
https://calcula.club/es/c/{encoded_config}

The configuration is serialized as JSON, compressed with deflate, and encoded as base64url. For embedding, use the /embed/{config} path.

Query parameters for initial values:

/embed/{config}?field1=50&field2=100

Each parameter corresponds to a field's id. Only numeric values are accepted.

Embedding

To embed a calculator, use an iframe:

<iframe
  src="https://calcula.club/embed/{config}"
  width="100%"
  height="600"
  frameborder="0"
  style="border: none; border-radius: 12px;"
></iframe>

Or download the self-contained HTML from the Builder to host your own copy.

Message API: The iframe communicates height changes to the parent via postMessage for automatic size adjustment.