🔌 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 ёрдамчи хабар ва майдон спецификацияси билан қайтарилади.

Параметрлар, олдинги қийматлар ва хатолар

Фақат сизга қизиқ бўлган майдонларни юборинг. Сиз қолдирган барча нарсалар ўша майдоннинг чоп этилган стандарти билан тўлдирилади - ҳисоблаш саҳифаси олдиндан тўлдирган қиймат, шунинг учун API ва веб-сайт доимо бир хил киритиш учун бир хил рақамларни қайтаради. Ҳар бир жавоб остида тўлдирилган нарсалар рўйхатини кўрсатади defaults_applied.

API ҳал қила олмайдиган барча нарса хато, ҳеч қачон 0 бўлмайди: хато ёзилган параметр, хато турдаги қиймат, номаълум тушириладиган танлов ёки стандарт бўлмаган йўқотилган майдон (дата майдонлари — туғилган санани тахмин қилиш мумкин эмас). Ҳар 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 қўнғироқ/ой, савдо учун.
• Бизнес $49/ой — 100,000 қўнғироқ/ой, асосий ўтказувчанлик.

Сизнинг квотангизга нима ҳисобланади

Фақат муваффақиятли жавобгина ишлайди. Бир 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/ индекс.