🔌 ھەقسىز ھېسابلىغۇچ API

ئومۇمىي

API تور بېكەتتە ئىشلىتىلگەن ماتېماتىكا بىلەن ئوخشاش. ھېسابلىغۇچنىڭ زېمىن قىممىتىنى سورۇن پارامېتىرلىرى ياكى JSON شەكلىدە ئەۋەتىپ، ھېسابلانغان نەتىجىلەرنى JSON شەكلىدە قايتۇرۇۋېلىپ، ھېسابلىغۇچ ئىشلەتكەن ھەرقانداق قىممەت ئۆسۈش ۋاقتى ياكى خەرىتىلەر سانلىق-مەلۇماتلىرىنى كىرگۈزىدۇ.

• 198+ ھېسابلىغۇچلار، ھەر بىرى ئۆزىنىڭ ئاخىرقى نۇقتىسى بار
• 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.

ئاساسىي URL

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.

ھېسابلاش — بىر خىل ھېسابلاش پروگراممىسى

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. نامەلۇم slug 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 سۈرئىتى چەكلەنگەن) ياكى ئايلىق ئازراق كوتىېت بىلەن ھەقسىز ئاچقۇچ. تىجارەتچىلەرگە ئىشلىتىلمەيدۇ.
• ئىجادىيەتچى — 100
• تىجارەت — $49/ئاي — 100

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/ ئىزنا.