🔌 פֿרײַער קאַלקולאַטאָר API

איבער־פֿאַרבײַטונג

דער API װײַזט די זעלבע מאטעמאטיק װי דער וועבזייַטל. שיקן אַ קלײנערס פעלד־באַטרעף װי אַ פֿראַגע־פּאַראַמעטער אָדער JSON און באַקומען די קלײנער־רײַז װי JSON — אַרײַנגעזעצט װידער אַ װײַטער־צוגײן־סקעטש אָדער שריפֿט־דאַטעס װאָס דער קלײנער פּראָדוצירט

• 198+ קלײַב אַלץ אױסselect-action
• ניט קיין API קײן — אַנאָנימישער צוטריט, IP־געבײט
• CORS — Access-Control-Allow-Origin: * (ניצלעך קלײַן־סײַט)
• װײַז װײַז: 60 פֿראַגעס/שעה אױף IP (HTTP 429 אױב איבערגעגאַנגען)
• 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.

בילדל

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

אינדעקס — װײַז אױף אײן קלײנער

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

װײַזט אַ מײַזעלע־לײענלעכע רשימה פֿון אַלע קלײַבער מיט יעדער פֿעלדער (קלאַװיש, הענטל, טיפּ, געװײנטלעכער, יחידה) און רעזולטאַט־קלײַבער — גענוג צו שאַפֿן אַ קלײַבער דינאַמיש 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.

קלײַב אַלץ אױסselect-action

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

ענטפֿער־פֿאָרעם:

{
  "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"]
}

לאַנד־בײַדעדיקע קלאַסאַפאַקאַציעס (האָרדער, לײענער, אַרײַנפֿאַל־בײַטל, פֿאַרקויף־בײַטל...) אַרײַננעמען ?country=us|uk|ca|au|in|ie|nz|za. אומבאַקאַנטער סלאָג װײַזט צוריק 404; ניט־געשטיצטע לענדער אָדער שלעכטע אַרײַנשרײַבונג װײַזט צוריק 400 מיט אַ הילף־װירוס־באַריכט און דעם פעלד־ספּעציפֿיקאַציע

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.

אױטאָמאַטישע אױטענטיפֿאַקציע

דו קענסט אַרײַנשרײַבן די API אָן קײן קײל — אַנאָנימישע פֿראַגעס זײַנען באַגרענעצט דורך IP. פֿאַר אַ העכערער, פֿאַרװאַנדללעכער מײַנלעך קװיטאַציע (און קאָמוניקאַציע־נוץ), שאַפֿ אַ קײל אױף דיין קאָנטאָן־װײַז און שיקן עס אױף אײן פֿון די דרייַ אופֿןן:

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"

• פֿרײַ — אַנאָנימישן (IP־רײט־געבײענעטן) אָדער אַ פֿרײַן קײן מיט אַ קלענערע מײַנלעך קװיטאַציע. ניט־קאָמערסיאַל
• װײַז פֿאָרױסװײַז — 10,000 טעלעפאָן רופן/חודש, קעמפּעריאלער ניצן.
• געשעפט — 100,000 טעלעפֿאָנירן/מײַן, פּריאָריטעט דורכפֿאַל.

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.

ווען אַ קלײַב האָט אַ מײַנלעך קװיטאַציע, װעט די API צוריקגעבן HTTP 429 מיט אַ טעות "quota_exceeded"; אַ אומבאַקאַנטער אָדער ניט־אַקטיווער קלײַב װעט צוריקגעבן HTTP 401 װײַז די פֿולע פּלאָנים און אַרײַנשרײַבן זיך אױף דעם װײַז פֿאָרױסװײַז בלעטער.

פֿאַרב:

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

אַלע סוף־פּראָצעסן

אײן סוף־פּונקט פֿאַר יעדער קלײַב־אַרײַנשטעל. פֿעלדער־קלאַװישן און רעזולטאט־קלאַװישן פֿאַר װײניקע זײַנען אין /api/v1/ אינדעקס.