🔌 Free Calculator APIName

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

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, пайдалы хабарламамен және өріс сипаттамасымен.

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

Тек қана қажет өрістерді жіберу. Ескертпеген өрістер әдетті өрістермен толтырылады - калькулятор бетінде алдын- ала толтырылған мәндер, сондықтан API мен веб- сайт әрқашан бірдей кірістер үшін бірдей сандарды қайтарады. Әрбір жауапта толтырылған өрістер тізімі көрсетіледі 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-нан астам түрі бар, оның ішінде 10-нан астам түрі ендеш.
• Бизнес — $49/ай — 100♠100♠100

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

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

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

Кілттің айлық квотасының шегі өткенде API HTTP 429 "quota_exceeded" қатесімен қайтарады; беймәлім немесе белсенді емес кілт HTTP 401 қатесін қайтарады. Тіркелгі Бағалау бет.

Мысалдар

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/ индекс.