🔌 I-Calculator API

Umbono

I-API isebenzisa i-matematics efanayo newebhusayithi esebenzisayo. Thumela amaxabiso endawo ye-calculator njengezilungiselelo zombuzo noma i-JSON bese uthola izimpendulo ezibalolwe emuva njenge-JSON — kufaka phakathi noma yisiphi isikhashana sokubuyiselwa noma i-data ye-chart i-calculator ekhiqiza.

• 198+ ama-calculators, ngayinye inesimo sayo sokuphela
• Akukho kinomsindo we-API — anonymous access, rate-limited by IP
• CORS — Access-Control-Allow-Origin: * (usayizi ofanele)
• Izinga lokukhawulela: 60 izicelo/ihora ngalinye le-IP (HTTP 429 uma kudlula)
• Iphutha likhululekile — kuphela uphendule ophumelelayo (2xx) usebenzisa umlayezo owodwa kusuka ku-quota yakho yenyanga. Wonke 400, 401, 404, 429 ne-500 awudingi lutho.

Isisekelo URL

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

Isingeniso - thola uhlu lwazo zonke izibalo

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

Ibuyisela uhlu olufundeka yimishini lwazo zonke izibalo ezinama-fields (isinqumo, isiphawuli, uhlobo, okuzenzakalelayo, isiyunithi) kanye nemiphumela yesinqumo - okunembile ukuthuthukisa umxhasi ngokuzenzakalela. Indawo ngayinye ifaka neflegi edingekayo — ngempela kulezi zindawo ezincane ezingaba nephutha (izinsuku, ikakhulukazi). Thumela lezi: ama-calculators ambalwa angathola enye, okunye impendulo 400 ngaphandle kwayo.

Linganisa — sebenzisa i-calculator eyodwa

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

Uhlobo lwesinqumo:

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

I-calculators eyaziwayo yezwe (i-mortgage, i-loan, i-income-tax, i-sales-tax…) ivunyelwe ?country=us|uk|ca|au|in|ie|nz|za. Isihlungi esingaziwa sibuyisela 404; izwe elingaxhaswa noma isingeniso esibi sibuyisela 400 nomlayezo osiza kanye nendawo ecacisiwe.

Amapharamitha, amaphutha namaphutha

Thumela kuphela ama-fields owaziyo. Noma yini ongayishiya ngaphandle igcwele nge-default eshicilelwe ye-field - ixabiso elifanayo ikhasi le-calculator ligcwalisa, ngakho-ke i-API ne-website zihlala zibuyisela inani elifanayo le-inputs. Uphendulo ngalunye lubonisa ukuthi yini egcwele ngaphansi defaults_applied.

Noma yini i-API engaxazululi ngokuvumelana nayo iphutha, ayikho i-zero: ipharamitha ebhalwe kabi, ixabiso lohlobo olungalunganga, ukhetho lokuhlanganiswa okungaziwa, noma indawo elahlekile elingasebenzi ngokuzenzakalela (izindaweni zosuku - usuku lokuzalwa alukwazi ukucashunwa). Zonke i-400 zibiza ipharamitha ephula umthetho futhi ziphinde zi

$ 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": [ ... ]
}

I- /api/v1/ i-index ishicilela isithonjana somhlaba wonke, uhlobo, isibalo, okuzenzakalelayo kanye nokuthi ngabe kudingeka — okunembile ukuthuthukisa umxhasi ongazange acabanga.

Ukuqinisekisa nezinhlelo

Ungabiza i-API ngaphandle kwesithonjana ngaso sonke isikhathi - izicelo ezingaziwayo zikhawulelwe yi-IP. Ukuthola i-quota ephakeme, elindelekile ngenyanga (nokusetshenziswa kokuthengiswayo), yenza isithonjana kwikhasi le-akhawunti yakho bese uyithumela ngenye yezindlela ezintathu:

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"

• Ikhululekile — i-anonymize (IP rate-limited) noma inkinobho ekhululekile enesibalo esincane sonyaka. Ayikho emakethe.
• Umthuthukisi — $9/ngonyaka — 10,000 ukuxhuma/inyanga, ukusetshenziswa kwezokuhweba.
• Ibhizinisi — $49/ngonyaka — 100,000 ukubiza/inyanga, ukudluliswa okuphambili.

Izinto ezibangelwa i-quota yakho

Umbuzo ophumelelayo kuphela owenza lokhu. 2xx eyodwa = ucingo olulodwa. Iphutha ngalinye likhululekile: 400 ku parameter ebhalwe kabi, inzuzo ebi noma indawo edingekayo elahlekile, 404 ku slug engaziwayo, 401 ku key ebi, 429, noma yini ehamba kahle engxenyeni yethu. Thola isivumelwano futhi lungisa isicelo sakho izikhathi eziningi njengoba ufuna — ukhokhwa ngemibuzo, hhayi ngezinhlekelele.

Ngenxa yokuthi iphutha likhululekile likhawulelwe ngezinga endaweni: uma inkinobho eyodwa ibangela okungaphezu kwe 200 iphoqeleke ukuphendula ngehora, ithola i-HTTP 429 "too_many_invalid_requests" kuze kube yihora lidlula. Izinhlamvu eziphumelelayo azikho ezibalayo, ngakho-ke ukuhlanganisa okusebenza ngeke kubone - ithola kuphela umxhasi okhubazekile ekwenzeni ukuphindaphinda.

Uma isithonjana sisebenzisa i-quota yenyanga, i-API ibuyisela i-HTTP 429 nephutha "quota_exceeded"; isithonjana esingaziwa noma esingasebenzi sibuyisela i-HTTP 401. Uhlelo lwe-E-Learning Ukulinganisa ikhasi.

Isibonelo

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

Zonke iziqongo eziphele

Ingxenye yesiphelo eyodwa nge-calculator. Amakinombho endawo kanye nemiphumela yamakinombho ngayinye ikhona ku /api/v1/ isibonisi.