🔌 Free Calculator API

Prehľad

Rozhranie API vykonáva presne rovnakú matematiku, akú používa webová stránka. Odošlite hodnoty polí kalkulačky ako parametre dotazu alebo JSON a získajte vypočítané výsledky späť ako JSON. Zahŕňajú všetky amortizačné plány alebo grafy, ktoré kalkulačka vygeneruje.

• 198+ Kalkulačky, každá s vlastným koncovým bodom
• Žiadny API kľúč — Anonymný prístup, rýchlosť obmedzená podľa IP
• CORS — Access-Control-Allow-Origin: * (použiteľné na strane klienta)
• Limit sadzby: 60 požiadaviek/hodina na IP (HTTP 429 pri prekročení)
• Chyby sú zadarmo — Iba úspešná (2xx) odpoveď využije jeden hovor z mesačnej kvóty, každý 400, 401, 404, 429 a 500 hovor je bezplatný.

Základná URL

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

Index — zobrazí zoznam všetkých kalkulačiek

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

Vráti strojovo čitateľný zoznam všetkých kalkulačiek s každým z polí (kľúč, označenie, typ, predvolené, jednotka) a kľúče výsledkov - dosť na dynamické vytvorenie klienta. Každé pole má tiež povinný príznak — platí pre niekoľko polí, ktoré nemajú predvolené hodnoty (väčšinou dátumy).Pošlite ich: pár kalkulačiek dokáže odvodiť jednu, ostatné odpovedajú 400 bez nej.

Výpočet — spustenie jednej kalkulačky

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

Tvar odozvy:

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

Kalkulačky pre jednotlivé krajiny (hypotéka, pôžička, daň z príjmu, daň z predaja...) akceptovať ?country=us|uk|ca|au|in|ie|nz|za. Neznámy slug vracia 404; nepodporovaná krajina alebo zlé zadanie vracia 400 s užitočnou správou a špecifikáciou poľa.

Parametre, predvolené nastavenia a chyby

Odoslať len polia, ktoré sú pre vás dôležité. Všetko, čo vynecháte, sa vyplní publikovanou predvolenou hodnotou pre dané pole – rovnakou hodnotou, ktorú predvyplní stránka kalkulačky, takže rozhranie API a webová stránka vždy vrátia rovnaké čísla pre rovnaké vstupy. defaults_applied.

Všetko, čo API nedokáže vyriešiť, je chyba, nikdy nula: chybne napísaný parameter, hodnota nesprávneho typu, neznáma možnosť v dropdowne, alebo chýbajúce pole, ktoré nemá predvolené nastavenie (dátumové polia – dátum narodenia sa nedá uhádnuť).Každých 400 pomenúva porušený parameter a opakuje celú špecifikáciu poľa, aby sa klient mohol sám opraviť.

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

100 mg /api/v1/ index zverejňuje kľúč každého poľa, typ, jednotku, predvolené nastavenie a či je povinné - dosť na vytvorenie klienta, ktorý nikdy neháda.

Overenie & plány

Rozhranie API môžete volať bez kľúča. Anonymné požiadavky sú obmedzené rýchlosťou podľa IP adresy. Ak chcete získať vyššiu, predvídateľnú mesačnú kvótu (a komerčné využitie), vytvorte kľúč na stránke svojho účtu a odošlite ho jedným z troch spôsobov:

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"

• Voľný — Môžete si vybrať anonymný (IP rate-limited) alebo bezplatný kľúč s malou mesačnou kvótou.
• Vývojár — $9/mesiac — 10 000 hovorov/mesiac, komerčné použitie.
• Podnikanie — $49/mesiac — 100 000 hovorov/mesiac, prioritná priepustnosť.

Čo sa započíta do vašej kvóty

Každá chyba je zadarmo: 400 pre nesprávne napísaný parameter, nesprávnu hodnotu alebo chýbajúce povinné pole, 404 pre neznámy slug, 401 pre nesprávny kľúč, 429 a čokoľvek, čo sa pokazí na našej strane. Preskúmajte zmluvu a opravte svoju požiadavku toľkokrát, koľko potrebujete – fakturujeme vám odpovede, nie opravy.

Pretože chyby sú bezplatné, sú namiesto toho obmedzené rýchlosťou: ak jeden kláves vyvoláva viac ako 200 Ak sa v priebehu hodiny vyskytne viac ako 100 odmietnutých odpovedí, dostane HTTP 429 "too_many_invalid_requests" až do skončenia hodiny. Úspešné volania sa nikdy nezapočítavajú do tohto čísla, takže pracovná integrácia to nikdy neuvidí. Zachytí iba klienta, ktorý sa zasekol v slučke opakovaných pokusov.

Keď sa vyčerpá mesačná kvóta kľúča, API vráti HTTP 429 s chybou "quota_exceeded"; neznámy alebo neaktívny kľúč vráti HTTP 401. Pozrite si kompletné plány a zaregistrujte sa na Ceny strana.

Príklady

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

Všetky koncové body

Klávesy pre polia a kľúče výsledkov pre každý z nich sú uvedené v časti /api/v1/ index.