🔌 KalkuliloName

Overview

La API rulas la precize saman matematikon kiun la retejo uzas. Sendu kalkulilajn kampvalorojn kiel demandparametroj aŭ JSON kaj ricevu la kalkulitajn rezultojn kiel JSON - inkluzive de ajna amortizo aŭ diagramaj datumoj kiujn la kalkulilo produktas.

• 198+ kalkuliloj, ĉiu kun sia propra finopunkto
• Neniu API-ŝlosilo — anonima aliro, rapidec- limigita per IP
• CORS — Access-Control-Allow-Origin: * (uzebla klientflanke)
• Limito de rapideco: 60 petoj/ horo po IP (HTTP 429 se superita)
• Errors are free — only a successful (2xx) response uses one call from your monthly quota. Every 400, 401, 404, 429 and 500 costs you nothing.

Baza URLo

https://calculator.free/api/v1/

Indekso — listigas ĉiun kalkulilon

GET https://calculator.free/api/v1/

Redonas maŝinlegindajn listojn de ĉiuj kalkuliloj kun la kampoj de ĉiu (ŝlosilo, etikedo, tipo, defaŭlta, unuo) kaj rezultoŝlosiloj — sufiĉe por konstrui klienton dinamike. Each field also carries a required flag — true for the few fields that have no default (dates, mostly). Send those: a couple of calculators can infer one, the rest answer 400 without it.

Kalkuli — lanĉi unu kalkulilon

GET  https://calculator.free/api/v1/<slug>/?field=value&field=value
POST https://calculator.free/api/v1/<slug>/     (JSON or form body)

Respondoformo:

{
  "ok": true,
  "slug": "mortgage",
  "country": "us",
  "inputs":   { ... the values actually computed with ... },
  "results":  { ... computed result keys ... },
  "schedule": { "columns": [...], "rows": [...] } | null,
  "chart":    { "type": "pie", "slices": [...] } | null,
  "defaults_applied": ["tax", "insurance"]
}

Land-konsciaj kalkuliloj (hipoteko, prunto, enspezimposto, vend-imposto...) akceptas ?country=us|uk|ca|au|in|ie|nz|za. Nekonata ŝraŭbo redonas 404; nesubtenita lando aŭ malbona enigo redonas 400 kun helpa mesaĝo kaj la kampospecifo.

Parameters, defaults and errors

Send only the fields you care about. Anything you leave out is filled with that field's published default — the same value the calculator page pre-fills, so the API and the website always return the same numbers for the same inputs. Each response lists what it filled in under defaults_applied.

Anything the API cannot resolve honestly is an error, never a zero: a misspelled parameter, a value of the wrong type, an unknown dropdown option, or a missing field that has no default (the date fields — a birth date cannot be guessed). Every 400 names the offending parameter and echoes the full field spec so a client can correct itself.

$ curl "https://calculator.free/api/v1/mortgage/?price=350000&rate=6.5&term=30"
{
  "ok": false,
  "error": "unknown_parameter",
  "message": "Unknown parameter 'term' for calculator 'mortgage'. Did you mean 'years'? ...",
  "unknown_parameters": ["term"],
  "did_you_mean": { "term": "years" },
  "valid_parameters": ["down", "extra", "extra_onetime", "extra_yearly", "hoa",
                       "insurance", "other", "pmi", "price", "rate", "tax", "years"],
  "fields": [ ... ]
}

The /api/v1/ index publishes every field's key, type, unit, default and whether it is required — enough to build a client that never guesses.

Aŭtentigo

Vi povas voki la API sen ŝlosilo - anonimaj petoj estas limigitaj laŭ IP. Por pli alta, antaŭvidebla monata kvoto (kaj komerca uzo), kreu ŝlosilon en via kontpaĝo kaj sendu ĝin unu el tri manieroj:

GET  https://calculator.free/api/v1/mortgage/?price=350000&key=YOUR_KEY
curl -H "Authorization: Bearer YOUR_KEY" "https://calculator.free/api/v1/bmi/?units=metric&height=180&weight=80"
curl -H "X-Api-Key: YOUR_KEY"           "https://calculator.free/api/v1/bmi/?units=metric&height=180&weight=80"

• Libera — anonima (IP- limigita) aŭ libera ŝlosilo kun malgranda monata kotizo. Nekomerca.
• Programisto — $9/mo — 1000♠ 1000♠ 100♠ 1000
• Business — $49/mo — 100.000 personoj, ĉefe en la ĉefurbo.

What counts against your quota

Only a successful response does. One 2xx = one call. Every error is free: a 400 for a misspelled parameter, a bad value or a missing required field, a 404 for an unknown slug, a 401 for a bad key, a 429, and anything that goes wrong on our side. Explore the contract and fix your request as many times as you need — you are billed for answers, not for corrections.

Because errors are free they are rate-limited instead: if one key provokes more than 200 rejected responses in an hour, it gets HTTP 429 "too_many_invalid_requests" until the hour rolls over. Successful calls never count towards that, so a working integration will never see it — it only catches a client stuck in a retry loop.

Kiam la monata kvoto de ŝlosilo estas elĉerpita, la API redonas HTTP 429 kun eraro "quota_exceeded"; nekonata aŭ neaktiva ŝlosilo redonas HTTP 401. Vidu plenajn planojn kaj subskribu por la Prezoj paĝo.

Ekzemploj

curl

curl "https://calculator.free/api/v1/mortgage/?price=350000&down=70000&rate=6.9&years=30"

JavaScript fetch()

const r = await fetch(
  "https://calculator.free/api/v1/bmi/?" + new URLSearchParams({
    units: "metric", height: "180", weight: "80"
  }));
const { results } = await r.json();
console.log(results.bmi, results.category);

Python

import requests

r = requests.get("https://calculator.free/api/v1/mortgage/",
                 params={"price": 350000, "down": 70000,
                         "rate": 6.9, "years": 30},
                 headers={"Authorization": "Bearer YOUR_KEY"})
print(r.json()["results"])

POST JSON

curl -X POST "https://calculator.free/api/v1/income-tax/?country=uk" \
  -H "Content-Type: application/json" \
  -d '{"income": 60000}'

Ĉiuj finpunktoj

Unu finpunkto por kalkulilo. Kampaj kaj rezulto-klavoj por ĉiu estas en la /api/v1/ indekso.