🔌 Free Calculator API

Тұжырымдамасы

API веб- сайт қолданатын математикалық амалдарды орындайды. Калкулятор өрісінің мәндерін сұраныс параметрлері немесе JSON ретінде жіберіп, есептеу нәтижелерін JSON ретінде алады - калькулятор шығарған кез келген амортизация жоспары немесе диаграмма деректері қоса.

• 198+ калькуляторлар, әрқайсысының өзінің аяқтау нүктесі бар
• API кілті жоқ — анонимді қатынау, жылдамдығы IP бойынша шектеледі
• CORS — Access-Control-Allow-Origin: * (клиент жағынан қолданылатын)
• Жиілігінің шегі: 60 IP- адрес бойынша сұраныс/ сағат (жоғары болғанда HTTP 429)
• Қателер бос — тек сәтті (2xx) жауап айлық квотаңыздан бір шақыруды ғана пайдаланады. Әрбір 400, 401, 404, 429 және 500 шақыру ештеңе етпейді.

Негізгі URL

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

Индекс - барлық калькуляторлар тізімі

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

Барлық калькуляторлардың машина оқыйтын тізімін қайтарады, әрбірінің өрісі (кілт, жарлығы, түрі, әдетті, бірлігі) және нәтиже кілттері - клиентті динамикалық құру үшін жеткілікті. Әрбір өріс қажет жалаушамен жабылған - әдетті өрістері жоқ (әдетте күндер) өрістер үшін бұл дұрыс. Бұл жалаушаларды жіберіңіз: біраз калькуляторлар біреуін анықтайды, қалғандары бұл жалаушасыз 400 деп жауап береді.

Есептеу — бір калькуляторды орындау

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

Жауап пішіні:

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

Елді ескеретін калькуляторлар (ипотека, несие, табыс салығы, сату салығы...) қабылданады ?country=us|uk|ca|au|in|ie|nz|za. Беймәлім slug қайтаратыны 404; қолдауы жоқ ел немесе қате енгізілгені үшін қайтаратыны 400, пайдалы хабарламамен және өріс сипаттамасымен.

Параметрлер, әдеттілер және қателер

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.

API шеше алмайтын кез келген нәрсе - қате, нөл емес: қате жазылған параметр, қате түрдегі мән, белгісіз ашылмалы тізім параметрі, немесе әдетті өрісі жоқ өріс (күні өрісі - туған күнін болжай алмайды). Әрбір 400- інде қате параметрдің атауы келтіріліп, клиенттің өздігінен түзелуіне мүмкіндік беретін өріс параметрі келтіріледі.

$ 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/ index әрбір өрістің кілт, түрі, бірлігі, әдетті және қажет пе дегенін жариялайды - ештеңе болжамайтын клиентті құру үшін жеткілікті.

Аутентификация мен жоспарлар

API- ны кілтсіз шақыруға болады - анонимді сұраныс IP- адресі бойынша шектеледі. Жоғары, болжамды айлық квота (не коммерциялық пайдалану) үшін, тіркелгі бетінде кілт құрып, оны үш жолмен жіберіңіз:

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"

• Бос — анонимді (IP жылдамдығы шектелген) немесе ай сайын аз мөлшерде берілетін тегін кілт. Коммерциялық емес.
• Жасаушы $9/ ай — 10,000 calls/month, commercial use.
• Бизнес — $49/ай — 100,000 calls/month, priority throughput.

Квотаңызға не кіреді

Тек сәтті жауап қана жауап береді. Бір 2xx = бір шақыру. Әрбір қателік ақысыз: 400 қате параметр үшін, қате мән үшін немесе керек өріс жоқ болса, 404 белгісіз slug үшін, 401 қате кілт үшін, 429 және біздің тарапымыздан қате болған кез келген нәрсе үшін. Келісім шартын қарап, қажет болғанша қайталап сұрауыңыздың дұрыстығын тексеріңіз - жауап үшін төленеді, түзету үшін емес.

Қателер еркін болғандықтан, олардың орнына жылдамдық шектеуі қолданылады: егер бір перне бірнеше қателерді тудырса 200 сағат ішінде жауаптарды қабылдамады, сағат өткенше HTTP 429 "too_many_invalid_requests" дегенді алады. Сәтті шақырулар бұл санға кірмейді, сондықтан жұмыс істейтін интеграция оны көрмейді - тек қайталау цикліне тығылған клиентті ғана байқайды.

Кілттің айлық квотасының шегі өткенде API HTTP 429 "quota_exceeded" қатесін қайтарады; беймәлім немесе белсенді емес кілт HTTP 401 қатесін қайтарады. See full plans and sign up on the Бағалау бет.

Мысалдар

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

Барлық аяқтау нүктелері

Калькулятордың бір аяқтау нүктесі. Әрбірінің өріс пен нәтиже пернелері келесіде /api/v1/ индекс.