🔌 Vapaan laskurin API

Yleiskatsaus

API-rajapinta käyttää täsmälleen samaa matikkaa kuin sivusto. Lähetä laskurin kenttä-arvot kyselyparametrina tai JSONina ja hanki lasketut tulokset JSONina – mukaan lukien kaikki laskurin tuottamat poistot tai kaaviotiedot.

• 198+ laskimet, joilla kaikilla on oma päätetapahtumansa
• Ei API-näppäintä — Nimetön pääsy, IP-maksurajoitettu
• CORS — Access-Control-Allow-Origin: * (käyttökelpoinen asiakaspuoli)
• Veron raja-arvo: 60 pyynnöt/tunti/inventaari (HTTP 429, jos ylitetty)
• Virheet ovat ilmaisia — Vain onnistunut (2xx) vastaus käyttää kuukausittaisesta kiintiöstä soitettua puhelua. 400, 401, 404, 429 ja 500 eivät maksa sinulle mitään.

Perusverkko- osoite

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

Hakemisto – luetteloi jokainen laskin

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

Palauttaa koneella luettavan luettelon kaikista laskimista kunkin kentillä (avain, nimimerkki, tyyppi, oletus, yksikkö) ja tulosavaimilla – riittää rakentamaan asiakasta dynaamisesti. Jokaisessa kentässä on myös vaadittu lippu – se pätee harvoihin kenttiin, joissa ei ole oletustietoja (pääasiassa päivämääriä). Lähetä nämä: pari laskinta voi päätellä yhden, loput vastaavat 400 ilman sitä.

Laske – suorita yksi laskin

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

Vastemuoto:

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

Maatietoiset laskimet (laina, tulovero, myyntivero...) hyväksytään ?country=us|uk|ca|au|in|ie|nz|za. Tuntematon luoti palauttaa 404; tukikelvoton maa tai huono syöttö palauttaa 400, jossa on hyödyllinen viesti ja kenttäspekti.

Parametrit, oletukset ja virheet

Lähetä vain ne kentät, joista välität. Kaikki mitä jätät pois, täytetään kentän julkaistulla oletuksella – sama arvo kuin laskinsivun esitäytöillä, joten API ja verkkosivusto palauttavat aina samat numerot samoille tuloille. Jokainen vastaus listaa, mitä se täytti alla. defaults_applied.

Kaikki, mitä API ei voi rehellisesti ratkaista, on virhe, ei koskaan nolla: väärin kirjoitettu parametri, väärän tyypin arvo, tuntematon pudotusvaihtoehto tai puuttuva kenttä, jossa ei ole oletusta (päivämääräkenttiä – syntymäaikaa ei voi arvata). Jokainen 400 nimeää rikkovan parametrin ja toistaa koko kentän yksityiskohdat, jotta asiakas voi korjata itsensä.

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

• /api/v1/ Indeksi julkaisee jokaisen kentän avaimen, tyypin, yksikön, oletuksen ja sen, onko se tarpeen – riittääkö se rakentamaan asiakkaan, joka ei koskaan arvaa.

Todentaminen ja suunnitelmat

Voit soittaa API:hen ilman avainta – nimettömät pyynnöt ovat IP:n määräämiä. Suuremman, ennustettavan kuukausikiintiön (ja kaupallisen käytön) vuoksi luo avain tilisivullesi ja lähetä se yhdellä kolmesta tavasta:

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"

• Vapaa — Nimetön (IP-korko rajoitettu) tai vapaa avain pienellä kuukausittaisella kiintiöllä. Ei-kaupallinen.
• Kehittäjä — $9/mo — 10 000 puhelua kuukaudessa, kaupallinen käyttö.
• Liiketoiminnan arvo on 49 dollaria/m. — 100 000 puhelua kuukaudessa, tärkein syöttö.

Mikä on kiintiön vastaista

Vain yksi vastaus onnistuu. Yksi 2xx = yksi puhelu. Jokainen virhe on ilmainen: 400 väärin kirjoitettua parametria, huono arvo tai puuttuva vaadittu kenttä, 404 tuntematonta luotia, 401 huonoa avainta, 429, ja kaikki, mikä menee pieleen meidän puolellamme. Tutki sopimusta ja korjaa pyyntösi niin monta kertaa kuin tarvitset – sinulta laskutetaan vastauksia, ei korjauksia.

Virheiden vuoksi ne ovat ilmaisia, mutta niiden sijaan ne ovat korkorajallisia: jos yksi avain herättää enemmän kuin 200 Torjutut vastaukset tunnin sisällä, se saa HTTP 429 "too_too_invalid_requests" kunnes tunti menee ohi. Onnistuneilla puheluilla ei ole koskaan merkitystä, joten toimiva integraatio ei koskaan näe sitä – se vain nappaa asiakkaan, joka on juuttunut uudelleenrynnistykseen.

Kun avaimen kuukausittainen kiintiö on käytetty loppuun, API palauttaa HTTP 429:n virheellä "kiintiön ylitetty", tuntematon tai toimeton avain palauttaa HTTP 401:n. Katso kaikki suunnitelmat ja ilmoittaudu Hinnoittelu sivu.

Esimerkkejä

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

Kaikki päätetapahtumat

Yksi päätetapahtuma laskinta kohden. Kenttä- ja tulosavaimet jokaiselle ovat /api/v1/ indeksi.