🔌 КалкуляторName

& Тақвим

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-и маҳдудшуда) ё калиди ройгон бо квотаи моҳонаи хурд. На тиҷоратӣ.
• Тайёркунанда — 100
• Корӣ — 1000♠1000

Чӣ ба квота дохил мешавад

Танҳо ҷавоби муваффақ кор мекунад. Як 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/ индекс.