🔌 API Kalkulator Bebas

Lihat

API menjalankan matematik yang sama dengan laman web. Hantar nilai medan kalkulator sebagai parameter pertanyaan atau JSON dan dapatkan hasil yang dikira sebagai JSON — termasuk sebarang jadual amortisasi atau data carta yang kalkulator keluarkan.

• 198+ kalkulator, masing-masing dengan titik akhirnya sendiri
• Tiada kekunci API — akses anonim, kadar terhad oleh IP
• CORS — Access-Control-Allow-Origin: * (boleh digunakan klien-sisi)
• Had kadar: 60 permintaan/jam bagi IP (HTTP 429 bila melebihi)
• Ralat adalah percuma — hanya respon (2xx) yang berjaya menggunakan satu panggilan dari kuota bulanan anda. Setiap 400, 401, 404, 429 dan 500 tidak kos apa-apa.

URL Asas

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

Indeks — senaraikan setiap kalkulator

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

Kembalikan senarai boleh baca mesin bagi semua kalkulator dengan medan (kunci, label, jenis, default, unit) dan kunci hasil bagi setiap satu — cukup untuk bina klien secara dinamik. Setiap medan juga membawa bendera yang diperlukan - benar untuk beberapa medan yang tidak mempunyai piawai (tarikh, kebanyakannya). Hantar mereka: beberapa kalkulator boleh mengira satu, yang lain menjawab 400 tanpanya.

Kira — jalankan satu kalkulator

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

Bentuk tindak balas:

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

Kalkulator negara-sedar (hipotek, pinjaman, cukai pendapatan, cukai jualan...) terima ?country=us|uk|ca|au|in|ie|nz|za. Slug tidak diketahui mengembalikan 404; negara tidak disokong atau input buruk mengembalikan 400 dengan mesej berguna dan spesifikasi medan.

Parameter, default dan ralat

Hantar hanya medan yang anda pedulikan. Apa-apa yang anda tinggalkan akan diisi dengan piawaian diterbitkan medan itu - nilai yang sama yang dipra-isi halaman kalkulator, jadi API dan laman web selalu kembalikan nombor yang sama untuk input yang sama. Setiap maklum balas daftar apa yang diisi di bawah defaults_applied.

Apa-apa yang API tidak dapat selesaikan dengan jujur adalah ralat, tidak pernah sifar: parameter salah ejaan, nilai jenis salah, pilihan dropdown tidak diketahui, atau medan hilang yang tidak mempunyai piawaian (medan tarikh - tarikh lahir tidak boleh diteka). Setiap 400 nama parameter yang melanggar dan mengecam spesifikasi medan penuh supaya klien boleh betulkan dirinya.

$ 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/ indeks menerbitkan kunci setiap medan, jenis, unit, default dan sama ada ia diperlukan — cukup untuk bina klien yang tidak pernah meneka.

Pengesahan

Anda boleh memanggil API tanpa kekunci sama sekali - permintaan anonim adalah terhad kadar oleh IP. Untuk kuota bulanan yang lebih tinggi, boleh diduga (dan penggunaan komersial), cipta kekunci pada halaman akaun anda dan hantar ia salah satu daripada tiga cara:

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"

• Bebas — anonim (IP had kadar) atau kunci percuma dengan kuota bulanan kecil. Tidak komersial.
• Pemaju — $9/mo — 10,000 panggilan/bulan, penggunaan komersial.
• Perniagaan — $49/mo — 100,000 panggilan/bulan, laluan utama.

Apa yang dikira terhadap kuota anda

Hanya maklum balas yang berjaya yang boleh. Satu 2xx = satu panggilan. Setiap ralat adalah percuma: 400 untuk parameter salah ejaan, nilai buruk atau medan yang diperlukan hilang, 404 untuk slug tidak diketahui, 401 untuk kekunci buruk, 429, dan apa-apa yang salah di pihak kami. Jelajah kontrak dan betulkan permintaan anda sebanyak kali yang anda perlukan — anda dicaj untuk jawapan, bukan untuk pembaikan.

Kerana ralat adalah percuma mereka adalah kadar-terhad sebaliknya: jika satu kekunci menimbulkan lebih daripada 200 jika tidak menerima maklum balas dalam satu jam, ia akan mendapat HTTP 429 "too_many_invalid_requests" sehingga jam berakhir. Panggilan yang berjaya tidak pernah dikira ke dalam itu, jadi integrasi yang berfungsi tidak pernah melihatnya — ia hanya menangkap klien terperangkap dalam lilitan cubaan semula.

Apabila kuota bulanan kekunci digunakan, API mengembalikan HTTP 429 dengan ralat "quota_exceeded"; kekunci tidak diketahui atau tidak aktif mengembalikan HTTP 401. Lihat rancangan penuh dan daftar di Harga halaman.

Contoh

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

Semua titik akhir

Satu titik akhir bagi setiap kalkulator. Kekunci medan dan kekunci hasil bagi setiap satu adalah dalam /api/v1/ indeks.