🔌 Özgür hesap makinesi API

Genel Bakış

API, web sitesinin kullandığı matematikle aynı matematiki kullanır. Bir hesaplayıcının alan değerlerini sorgu parametreleri veya JSON olarak gönderin ve hesaplamanın ürettiği herhangi bir amortisman planı veya grafik verileri dahil olmak üzere hesaplanan sonuçları JSON olarak geri alın.

• 198+ hesap makineleri, her biri kendi son noktasına sahip
• API anahtarı yok — anonim erişim, IP ile hız sınırlı
• CORS — Access-Control-Allow-Origin: * (kullanılabilir istemci tarafı)
• Hız sınırı: 60 IP başına saat başına talepler (aşıldığında HTTP 429)
• Hatalar ücretsizdir. — sadece başarılı bir (2xx) cevap aylık kotanızdan bir çağrı kullanır. Her 400, 401, 404, 429 ve 500 size hiçbir şeye mal olmaz.

Temel URL

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

İndeks — her hesaplayıcıyı listele

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

Her birinin alanları (anahtar, etiket, tür, varsayılan, birim) ve sonuç anahtarları ile tüm hesaplayıcıların makine okunabilir bir listesini geri verir - dinamik olarak bir istemci inşa etmek için yeterli. Her alan ayrıca bir gerekli bayrağı taşıyor - varsayılan olmayan birkaç alan için doğru (çoğu zaman tarihler). Gönder: bir kaç hesaplayıcı bir tane çıkarabilir, geri kalanlar 400 cevap verir.

Hesaplama — bir hesap makinesi çalıştır

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

Cevap şekli:

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

Ülke bilincinde hesaplayıcılar (mortgage, loan, income-tax, sales-tax…) kabul edilir ?country=us|uk|ca|au|in|ie|nz|za. Bilinmeyen slug 404 geri döner; desteklenmeyen ülke veya kötü giriş, yardımcı bir mesaj ve alan spesifikasyonuyla 400 geri döner.

Parametreler, varsayımlar ve hatalar

Sadece önem verdiğiniz alanları gönderin. Kaçırdığınız her şey o alan için yayınlanan varsayılan değerle doldurulur - hesaplama sayfasının önceden doldurduğu aynı değer, böylece API ve web sitesi aynı girdiler için her zaman aynı sayıları geri verir. Her cevap altında doldurduğunu listeler defaults_applied.

API'nin dürüstçe çözemeyeceği her şey bir hatadır, hiçbir zaman sıfır değildir: yanlış yazılmış bir parametre, yanlış tipteki bir değer, bilinmeyen bir düşme seçeneği, veya varsayılan olmayan eksik bir alan (tarih alanları - doğum tarihi tahmin edilemez). Her 400, yasadışı parametreyi adlandırır ve istemcinin kendisini düzeltmesi için tam alan spesifikasyonunu yansıtır.

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

The /api/v1/ index her alan için anahtar, tür, birim, varsayılan ve gerekli olup olmadığını yayınlar — hiç tahmin etmeyen bir istemci inşa etmek için yeterli.

Kimlik doğrulama ve planlar

API'yi hiçbir anahtar olmadan çağırabilirsiniz — anonim istekler IP tarafından hız sınırlıdır. Daha yüksek, tahmin edilebilir aylık kota (ve ticari kullanım) için, hesabınız sayfasında bir anahtar oluşturun ve üç yoldan birini gönderin:

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"

• Özgür — anonim (IP hızı sınırlı) veya küçük aylık bir kotasyonla ücretsiz bir anahtar. Ticari olmayan.
• Geliştirici — $9/ay — Ayda 10.000 çağrı, ticari kullanım.
• İş — $49/ay — Ayda 100.000 çağrı, öncelikli işlem hacmi.

Neler kotanıza dahil?

Sadece başarılı bir cevap işe yarar. Bir 2xx = bir çağrı. Her hata ücretsizdir: yanlış yazılmış bir parametre için 400, yanlış bir değer veya eksik bir gerekli alan için 400, bilinmeyen bir slug için 404, kötü bir anahtar için 401, 429 ve bizim tarafımızdan yanlış giden her şey için 404. Sözleşmeyi inceleyin ve isteğinizi ihtiyacınız olduğu kadar düzeltin - cevaplar için faturalandırılıyorsunuz, düzeltmeler için değil.

Hatalar ücretsiz olduğu için, bunun yerine oran sınırlıdır: eğer bir anahtar daha fazlasını tetiklerse 200 bir saat içinde cevapları reddettiği takdirde, saatin sonuna kadar HTTP 429 "too_many_invalid_requests" (çok_çok_yanlış_talep) alacaktır. Başarılı çağrılar bu sayıya dahil edilmez, bu yüzden çalışan bir entegrasyon bunu asla görmez — sadece tekrar denemede sıkışmış bir istemciyi yakalar.

Bir anahtar aylık kotası kullanıldığında API HTTP 429 ile "quota_exceeded" hatasını geri döndürür; bilinmeyen veya etkin olmayan bir anahtar HTTP 401'i geri döndürür. Tüm planları görün ve kayıt olun Fiyatları sayfa.

Örnekler

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

Tüm son noktalar

Her hesap makinesi için bir son nokta. Her biri için alan anahtarları ve sonuç anahtarları aşağıdaki tablodadır. /api/v1/ indeks.