🔌 Free Calculator API

Përmbledhja

API kryen saktësisht të njëjtën matematikë që përdor uebsajti. Dërgo vlerat e fushës së një kalkulatori si parametra kërkimi ose JSON dhe merr rezultatet e llogaritura si JSON — duke përfshirë çdo planifikimin e amortizimit apo të dhënat e diagramit që prodhon kalkulatori.

• 198+ kalkulatorë, secili me pikën e vet përfundimtare
• Asnjë kyç API — hyrje anonime, me kufizim nga IP
• CORS — Access-Control-Allow-Origin: * (e përdorshme në anën e klientit)
• Limiti i shpejtësisë: 60 kërkesa/orë për IP (HTTP 429 kur tejkalohet)
• Gabimet janë të lira — vetëm një përgjigje e suksesshme (2xx) përdor një thirrje nga kuota juaj mujore. Çdo 400, 401, 404, 429 dhe 500 nuk ju kushton asgjë.

URL e bazë

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

Treguesi — listë e çdo kalkulatori

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

Kthen një listë të lexueshme nga makina e të gjithë kalkulatorëve me fushat e secilit (key, label, type, default, unit) dhe çelësat e rezultatit - mjaftueshëm për të ndërtuar një klient dinamikisht. Çdo fushë gjithashtu mban një flamur të kërkuar - të vërtetë për fushat e pakta që nuk kanë të paracaktuar (data, kryesisht). Dërgoji ato: disa kalkulatorë mund të nxjerrin një, pjesa tjetër përgjigjet 400 pa të.

llogaritje

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

Përgjigja

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

Kalkulatorë të njohur nga vendi (hipoteka, kredia, taksat e të ardhurave, taksat e shitjeve...) pranohen ?country=us|uk|ca|au|in|ie|nz|za. Slug i panjohur kthen 404; shteti i pasuportuar ose hyrja e gabuar kthen 400 me një mesazh ndihmës dhe specifikimin e fushës.

Parametrat, të paracaktuarit dhe gabimet

Dërgo vetëm fushat që të interesojnë. Çdo gjë që lë jashtë mbushet me vlerën e paracaktuar të publikuar të fushës - e njëjta vlerë që para-plotësohet nga faqja e kalkulatorit, kështu që API dhe website kthejnë gjithmonë të njëjtat numra për të njëjtat hyrje. Çdo përgjigje liston atë që ka mbushur nën defaults_applied.

Çdo gjë që API nuk mund ta zgjidhë sinqerisht është një gabim, kurrë një zero: një parametri i shkruar gabim, një vlerë e llojit të gabuar, një opsion i panjohur i zbritshëm, ose një fushë që mungon dhe nuk ka asnjë të paracaktuar (fushat e datës - data e lindjes nuk mund të gjehet). Çdo 400 emërton parametrin e gabuar dhe përsërit specifikimin e plotë të fushës në mënyrë që një klient të mund të korrigjojë veten.

$ 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/ indeksi publikon kyçin, llojin, njësin, të paracaktuarin dhe nëse është i nevojshëm për çdo fushë — mjaftueshëm për të ndërtuar një klient që nuk e gjej kurrë.

Autentifikimi

Mund të thirrni API pa asnjë kyç — kërkesat anonime janë të kufizuara nga IP. Për një kuotë më të lartë, të parashikuar mujore (dhe përdorim komercial), krijoni një kyç në faqen e llogarisë suaj dhe dërgoni atë në një nga tre mënyra:

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"

• I lirë — anonim (IP me limitin e shpejtësisë) ose një kyç i lirë me një kuota të vogël mujore. Jo komercial.
• Zhvilluesi — 10,000 thirrje në muaj, përdorim komercial.
• Biznesi — $49/muaj — 100,000 thirrje në muaj, përparësi.

Çfarë llogaritet në kuota tuaja

Vetëm një përgjigje e suksesshme e bën këtë. Një 2xx = një thirrje. Çdo gabim është i lirë: një 400 për një parametrë të gabuar, një vlerë të gabuar ose një fushë të kërkuar që mungon, një 404 për një slug të panjohur, një 401 për një kyç të gabuar, një 429, dhe çdo gjë që shkon keq nga ana jonë. Heto kontratën dhe rregullo kërkesën tënde sa herë që të duash — do të paguhesh për përgjigjet, jo për korrigjimet.

Për shkak se gabimet janë të lira, ato janë të kufizuara në vend të kësaj: nëse një kyç shkakton më shumë se 200 nuk ka marrë përgjigjet e refuzuara brenda një ore, merr HTTP 429 "too_many_invalid_requests" deri sa të kalojë ora. Thirrjet e suksesshme nuk llogariten kurrë për këtë, kështu që një integrim funksionues nuk do ta shohë kurrë këtë — vetëm kap një klient të bllokuar në një cikl përpjekje.

Kur kuota mujore e një kyçi është përdorur, API kthen HTTP 429 me gabimin "quota_exceeded"; një kyç i panjohur ose i paaktiv kthen HTTP 401. Shiko planet e plota dhe regjistrohu në Çmimi faqe.

Shembuj

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

Të gjitha pikat përfundimtare

Një pikë përfundimi për çdo kalkulator. Tastierat e fushës dhe rezultatit për secilin janë në /api/v1/ indeksi.