🔌 အခမဲ့ဂဏန်းတွက်စက် API ကို

အကျဉ်းချုပ်

ဤ API ကို website ကိုအသုံးပြုသည်အတိအကျတူညီသောသင်္ချာ runs. query parameters များသို့မဟုတ် JSON အဖြစ်တွက်ချက်စက်၏ Field Values ကိုပို့ပြီး JSON အဖြစ်ပြန်ရဖို့တွက်ချက်ရလဒ်များကို - calculator ထုတ်လုပ်မည်သည့် amortization စီစဉ်ထားသို့မဟုတ် chart data ကိုအပါအဝင်.

• 198+ ဂဏန်းတွက်စက်, ၎င်း၏ကိုယ်ပိုင် endpoint တစ်ခုချင်းစီနှင့်အတူ
• API ကီးမရှိပါ — အမည်မဲ့ access, IP ကိုအားဖြင့်နှုန်း-ကန့်သတ်
• CORS — Access-Control-Allow-Origin: * (သုံးနိုင်သော client-side)
• နှုန်းထား ကနိမ့်ဆုံး: 60 IP ကိုတစ်ဦးလျှင်တောင်းဆိုချက်များ / နာရီ (HTTP ကို 429 ကျော်လွန်သောအခါ)
• အမှားများအခမဲ့ဖြစ်ကြသည် — တစ်ခုတည်းသောအောင်မြင်သော (2xx) တုံ့ပြန်မှုသင်၏လစဉ် quota မှတစ်ဦးခေါ်ဆိုမှုအသုံးပြု. အားလုံး 400, 401, 404, 429 နှင့် 500 သင်ဘာမှကုန်ကျ.

အခြေခံ URL

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

Index — စာရင်းတိုင်းဂဏန်းတွက်စက်

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

တစ်ခုချင်းစီကိုတစ်ဦး၏နယ်ပယ် (key ကို, label ကို, အမျိုးအစား, default, တပ်မတော်) နှင့်ရလဒ် key ကိုနှင့်အတူအားလုံးဂဏန်းတွက်စက်များ၏စက်-ဖတ်နိုင်စာရင်းပြန်လာ - dynamic အားဖြင့် client ကိုတည်ဆောက်ရန်လုံလောက်သော။ တစ်ခုချင်းစီကိုနယ်ပယ်လည်းလိုအပ်သောကဒ်ပြားကိုဆောင်ကြဉ်း - မည်သည့် default ကိုမရှိသောအနည်းငယ်နယ်ပယ်များအတွက်မှန်ကန် (ရက်စွဲများ, အများစု). သူတို့ကိုပို့: ဂဏန်းတွက်စက်တစ်ဦးအစုံတစ်ဦးက infer နိုင်ပါတယ်, ကျန်အဖြေ 400 ဒါကိုမရှိဘဲ.

တွက်ချက်ခြင်း — တစ်ဂဏန်းတွက်စက်ကို run

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

တိုင်းပြည်-အသိအမှတ်ပြုဂဏန်းတွက်စက် ( mortgage, ချေးငွေ, ဝင်ငွေ-အခွန်, ရောင်းချ-အခွန်...) လက်ခံ ?country=us|uk|ca|au|in|ie|nz|za. အမည်မသိ slug 404 ပြန်လာ; မထောက်ခံတဲ့နိုင်ငံသို့မဟုတ်ဆိုး input ကိုပြန်လာ 400 ကူညီပေးနိုင်တဲ့သတင်းစကားနှင့် Field ကို Spec အတူ။

သတ်မှတ်ချက်၊ စံသတ်မှတ်ချက်နှင့်အမှား

သင်ကအရေးကြီးတဲ့အကြောင်းကိုသာနယ်ပယ်များကိုပို့. သင်ထွက်ခွာသွားဘာမှထိုနယ်ပယ်၏ထုတ်ဝေ default နဲ့ဖြည့်သည် - အလားတူတန်ဖိုးကိုဂဏန်းတွက်စက်စာမျက်နှာ pre-fills, ဒါကြောင့် API ကိုနှင့်ဝက်ဘ်ဆိုက်ကိုအမြဲတူ inputs များအတွက်တူညီတဲ့နံပါတ်များကိုပြန်လာ. တစ်ခုချင်းစီကိုတုံ့ပြန်မှုအောက်တွင်ဖြည့်ထားတဲ့အရာကိုစာရင်း defaults_applied.

API ကိုရိုးသားစွာဖြေရှင်းနိုင်မဆိုအရာတစ်ခုခုအမှားဖြစ်ပါသည်, တစ်ဆယ်မ: တစ်ဦးအသံထွက် parameter ကို, မှားယွင်းသောအမျိုးအစား၏တန်ဖိုးကို, အမည်မသိ dropdown option ကို, သို့မဟုတ်မ default ကိုရှိပါတယ်သော missing field ကို (ရက်စွဲ Fields - တစ်ဦးမွေးဖွားရက်စွဲခန့်မှန်းမရနိုင်). အားလုံး 400 နာမကိုအမှီအမှုပြု parameter ကိုနှင့်တစ်ဦး client ကိုကိုယ်ပိုင်ပြင်ဆင်နိုင်အောင်အပြည့်အဝ Field ကို Spec ကို echoes.

$ 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 အားလုံး Field ရဲ့ key ကို, အမျိုးအစား, တပ်မတော်, default နှင့်လိုအပ်သည်မဟုတ်လျှင်ထုတ်ပြန်ကြေညာ - မကြာခဏခန့်မှန်းသော client ကိုဆောက်လုပ်ရန်လုံလောက်.

ခွင့်ပြုချက်နှင့် အစီအစဉ်များ

သင်သည်အဘယ်သူမျှမ key ကိုနှင့်အတူ API ကိုခေါ်ဆိုနိုင်ပါတယ် - အမည်မဲ့တောင်းဆိုမှုများ IP ကိုအားဖြင့်နှုန်းထား-ကန့်သတ်ထားသည်။ မြင့်မားသောအတွက်, ခန့်မှန်းနိုင်သောလစဉ် quota (နှင့်စီးပွားရေးလုပ်ငန်းအသုံးပြုမှု), သင့်ရဲ့အကောင့်စာမျက်နှာပေါ်တွင် key ကိုဖန်တီးပြီးသုံးနည်းလမ်းများထဲကတစ်ခုပို့:

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 ကိုနှုန်း-limited) သို့မဟုတ်အသေးစားလစဉ် quota နှင့်အတူအခမဲ့ key ကို. Non-ကုန်သွယ်.
• Developer — $9/လ — 10,000 calls/month, စီးပွားရေးလုပ်ငန်းသုံး။
• စီးပွားရေးလုပ်ငန်း — $49/month — 100,000 calls/month, အလိုအလျောက် ဖုန်းခေါ်ဆိုမှု

သင်၏ quota ကိုဆန့်ကျင်ဘာကိုတွက်ချက်

တစ်ခုတည်းသောအောင်မြင်သောတုံ့ပြန်မှုလုပ်. တစ်ဦး 2xx = တစ်ဦးခေါ်ဆိုမှု. အားလုံးအမှားအခမဲ့ဖြစ်ပါသည်: တစ် 400 ရေးမှား parameter ကိုများအတွက်, တစ်ဆိုးတဲ့တန်ဖိုးသို့မဟုတ်တစ်ဦးပျောက်ဆုံးနေလိုအပ်သောနယ်ပယ်, တစ် 404 အမည်မသိ slug အတွက်, တစ် 401 ဆိုး key ကိုများအတွက်, တစ် 429, နှင့်ကျွန်တော်တို့ရဲ့ဘက်မှာမှားသွားတဲ့အရာအားလုံး. သင်လိုအပ်သလိုအကြိမ်များစွာအဖြစ်စာချုပ်ကိုစူးစမ်းလေ့လာနှင့်သင်၏တောင်းဆိုချက်ကို fix - သင်အဖြေများအတွက် bill နေကြတယ်, မပြုပြင်ရန်အတွက်.

အမှားများအခမဲ့ဖြစ်ကြသည်ကြောင့်သူတို့အစားနှုန်းထား-ကန့်သတ်နေကြသည်: တစ်ဦးကခလုတ်ကိုထက်ပိုမိုလှုံ့ဆော်လျှင် 200 အောင်မြင်သောခေါ်ဆိုမှုဘယ်တော့မှအဲဒီကိုသို့စာရင်းမပါဘဲ, ဒါကြောင့်အလုပ်လုပ်ကိုင်ပေါင်းစည်းမှုဘယ်တော့မှမြင်လိမ့်မည် - ဒါဟာတစ်ဦး retry loop မှာပိတ်မိ client ကိုဖမ်းမိ။

တစ်ဦးက key ကို၏လစဉ် quota ကိုအသုံးပြုတဲ့အခါ API ကိုပြန်လာ HTTP 429 မှားယွင်းမှုနှင့်အတူ "quota_exceeded"; အမည်မသိသို့မဟုတ်မလှုပ်ရှားသော key ကိုပြန်လာ 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}'

အဆုံးသတ်မှတ်တိုင်များ

တစ်ဦး endpoint တစ်ဂဏန်းတွက်စက်တစ်ဦး. Field က Keys တွေကိုနှင့်တစ်ဦးချင်းစီအတွက်ရလဒ်ကို Keys တွေကို /api/v1/ စာရင်းဇယား.