🔌 Pulsuz Hesablama API

_Nəzarət

API veb saytda istifadə edilən eyni riyazi əməliyyatı yerinə yetirir. Hesablayıcının sahəsi dəyərlərini sorğu parametrləri və ya JSON olaraq göndər və hesablanmış nəticələri JSON olaraq geri al - hesablayıcının istehsal etdiyi hər hansı amortizasiya planı və ya cədvəl məlumatı da daxil olmaqla.

• 198+ hesablayıcılar, hər biri öz son nöqtəsi ilə
• API açarı yoxdur — anonim giriş, IP-yə görə sürət məhdudlaşdırılır
• CORS — Access-Control-Allow-Origin: * (istifadə edilə bilən müştəri tərəfi)
• Sür'ət həddi: 60 IP başına tələblər/saat (HTTP 429-a çatdıqda)
• Xətalar azaddır — yalnız müvəffəqiyyətli (2xx) cavab aylıq kvotanızdan bir zəng istifadə edir. Hər 400, 401, 404, 429 və 500 zəng sizə heç bir şey xərcləmir.

Əsas Ünvan

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

İndeks — hər hesablamanı siyahıya al

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

Bütün hesablayıcıların maşın oxuna bilən siyahısını hər birinin sahəsi (açar, etiket, növ, ön qurğulu, vahid) və nəticə açarları ilə geri qaytarır - müştərini dinamik olaraq qurmaq üçün kifayət qədər. Hər bir sahədə lazımi bayraq da var - ön qurğulu olmayan bir neçə sahədə (adətən tarixlər) doğrudur. Onları göndər: bir neçə hesablayıcı birindən nəticə çıxara bilər, qalanları isə 400 cavabını verəcək.

Hesabla — bir hesablamanı işlət

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

Cavab şəkli:

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

Ölkə-aydın hesablayıcılar (hipoteka, kredit, gəlir vergisi, satış vergisi...) qəbul edilir ?country=us|uk|ca|au|in|ie|nz|za. Namə'lum sluq 404 geri qaytarır; dəstəklənməyən ölkə və ya səhv daxili 400'ü köməkçi ismarış və sahənin spesifikasiyaları ilə geri qaytarır.

Parametrlər, ön qurğular və xətalar

Yalnız diqqət yetirdiyiniz sahələri göndərin. Əks təqdirdə, bu sahənin əvvəlcədən yazılmış dəyəri ilə doldurulur - hesablama səhifəsinin əvvəlcədən doldurduğu eyni dəyər, buna görə API və veb sayt həmişə eyni girişlər üçün eyni rəqəmləri geri qaytarır. Hər cavab altında doldurulduğunu göstərir defaults_applied.

API-nin düzgün həll edə bilmədiyi hər şey xətadır, heç vaxt sıfır deyil: səhv imla parametri, səhv növ dəyər, namə'lum aşağı düşən seçim, ya da ön qurğulu olmayan eksik sahələr (tarix sahələri - doğum tarixi təxmin edilə bilməz). Hər 400-də səhv parametrin adı və müştərinin özünü düzəldə biləcəyi bütün sahələrin spesifikasiyasını əks etdirir.

$ 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": [ ... ]
}

Bu /api/v1/ index hər sahənin açarını, növünü, vahidini, ön qurğusunu və tələb olunduğunu yayımlayır - heç vaxt təxmin etməyən bir müştəri yaratmaq üçün kifayətdir.

Tanıtma

API-ni açarsız çağıra bilərsiniz - anonim tələblər IP-yə görə sürətlə məhdudlaşır. Daha yüksək, proqnozlaşdırıla bilən aylıq kvota (və kommersiya istifadəsi) üçün hesab səhifəsində bir açar yaradın və onu üç yoldan birinə göndərin:

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"

• Pulsuz — anonim (IP sürəti məhdudlaşdırılmış) ya da aylıq kiçik kvota ilə pulsuz açar. Ticarətə aid olmayan.
• Developer — $9/mo — 10,000 calls/month, commercial use.
• İş — $49/ay — 100,000 calls/month, priority throughput.

Sənin kvotana nə daxildir

Yalnız müvəffəq cavablar bunu edir. Bir 2xx = bir çağırış. Hər xəta pulsuzdur: 400 səhv imla parametri, səhv dəyər və ya lazımi sahənin olmaması üçün, 404 naməlum slug üçün, 401 səhv açar üçün, 429 və bizim tərəfimizdən səhv olan hər şey üçün. Müqaviləni araşdır və istəyinizi lazım olduğu qədər dəfə düzəlt - cavablar üçün hesablanırsınız, düzəltmələr üçün yox.

Xətalar azad olduğundan onlar əvəzinə dərəcə-mərkəzləşdirilmişdir: əgər bir açar daha çoxu işə salsa 200 Bir saat ərzində cavablar rədd edildikdə, saat keçənə qədər HTTP 429 "too_many_invalid_requests" alır. Müvəffəqiyyətli zənglər heç vaxt bu hesaba daxil edilmir, buna görə də işləyən inteqrasiya heç vaxt bunu görməz - yalnız təkrar-təcrid döngəci ilə bağlı olan bir müştərini tutub.

Açarın aylıq kvotası istifadə edildikdə API HTTP 429 ilə "quota_exceeded" səhvi ilə geri dönür; naməlum ya da aktiv olmayan açar HTTP 401 ilə geri dönür. Bütün planları gör və qeydiyyatdan keç Qiymətləndirmə səhifə.

Məsələr

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

Bütün son nöqtələr

Hər hesablama üçün bir son nöqtəsi. Hər birinin sahəsi və nəticəsi açarları budur /api/v1/ indeks.