🔌 מחשבון חינם API

סקירה

The API runs the exact same math the website uses. Send a calculator's field values as query parameters or JSON and get the computed results back as JSON — including any amortization schedule or chart data the calculator produces.

• 198+ מחשבונים, כל אחד עם נקודת קצה משלו
• אין מפתח API — גישה אנונימית, שיעור מוגבל על ידי IP
• CORS — Access-Control-Allow-Origin: * (לקוח זמין)
• רמת הגבלת קצב: 60 בקשות/ שעה ל- IP (HTTP 429 כאשר חרג)
• שגיאות הן בחינם — 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/

Index — list every calculator

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.

מחשבון אחד

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 עם הודעה מועילה ומפרט השדה.

פרמטרים, ברירת מחדל וטעויות

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/ אינדקס מפרסם את המפתח, הסוג, היחידה, ברירת המחדל של כל שדה, והאם הוא נדרש מספיק כדי לבנות לקוח שלעולם לא מנחש.

אימות ותוכניות

You can call the API with no key at all — anonymous requests are rate-limited by IP. For a higher, predictable monthly quota (and commercial use), create a key on your account page and send it one of three ways:

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-Limited) או מפתח חינם עם מכסה חודשית קטנה.
• מפתח & mdash; 9/mo — 10,000 שיחות/חודש, שימוש מסחרי.
• עסקים & מדש; 49/ מו — 100,000 calls/month, priority throughput.

מה שחשוב נגד המכסה שלך

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.

בגלל שטעויות הן חופשיות הן מוגבלות בקצב במקום: אם מפתח אחד מעורר יותר מאשר 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 עם שגיאה "qua_exeed"; מפתח לא ידוע או לא פעיל מחזיר 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/ אינדקס.