🔌 Kalkulagailu librearen APIa

Orokorra

APIak webguneak erabiltzen duen matematika bera exekutatzen du. Bidali kalkulagailu baten eremu-balioak kontsulta-parametro gisa edo JSON gisa, eta lortu kalkuluaren emaitzak JSON gisa — kalkulagailuak sortzen dituen amortizazio-egutegi edo grafikoen datuak barne.

• 198+ kalkulagailuak, bakoitzak bere amaiera-puntua duela
• API gakorik ez — anonimoa, IP-k mugatutako abiadura
• CORS — Access-Control-Allow-Origin: * (bezero-alde erabilgarria)
• Emaria muga: 60 eskaerak/ordua IP bakoitzeko (HTTP 429 gainditzen denean)
• 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.

Oinarrizko URLa

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

Indizea — kalkulagailu guztiak zerrendatzen ditu

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

Kalkulagailu guztien zerrenda makina-irakurgarria itzultzen du, bakoitzaren eremuekin (gakoa, etiketa, mota, lehenetsia, unitatea) eta emaitza-gakoekin - bezero bat dinamikoki eraikitzeko nahikoa. 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.

Kalkulatu — exekutatu kalkulagailu bat

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

Erantzunaren forma:

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

Herrialdea kontuan hartzen duten kalkulagailuak (hipoteka, mailegu, diru-sarrerak, salmenta-sarrerak...) onartzen dira ?country=us|uk|ca|au|in|ie|nz|za. Slug ezezagunak 404 itzultzen du; herrialdea onartzen ez bada edo sarrera okerra bada, 400 itzultzen da mezu lagungarri batekin eta eremuaren zehaztasunarekin.

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.

Autentifikazioa eta planak

APIari gakorik gabe deitu diezaiokezu — eskaera anonimoek IParen araberako tasa mugatua dute. Hileko kuotarik handiena eta aurreikusgarria (eta erabilera komertziala) lortzeko, sortu gako bat zure kontu-orrian eta bidali hiru modutan:

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"

• Libre — anonimoa (IP-ren abiadura mugatua) edo hileko kuota txikia duen gako librea. Ez-merkataritzakoa.
• Garatzailea — $9/mo — 10.000 deia/hilabete, erabilera komertziala.
• Negozioak — $49/mo — 100.000 biztanle inguru ditu, eta udalerririk populatuena da.

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.

Gako baten hileko kuota agortu denean, APIak HTTP 429 itzultzen du "quota_exceeded" errorearekin; gako ezezagun edo inaktibo batek HTTP 401 itzultzen du. Ikusi plan osoak eta eman izena Prezioa orrialdea.

Adibideak

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

Amaierako puntu guztiak

Amaierako puntu bat kalkulagailu bakoitzeko. Eremu-gakoak eta emaitza-gakoak bakoitzaren barruan daude /api/v1/ indizea.