🔌 API tính toán miễn phí

Kiểm tra

API chạy chính xác cùng toán học mà trang web sử dụng. Gửi giá trị trường của máy tính như tham số truy vấn hoặc JSON và lấy kết quả tính toán trở lại như JSON — bao gồm bất kỳ lịch trình hủy bỏ hay dữ liệu biểu đồ mà máy tính tạo ra.

• 198+ máy tính, mỗi cái có điểm cuối riêng
• Không có chìa khóa API — truy cập ẩn danh, tốc độ giới hạn bởi IP
• CORS — Access-Control-Allow-Origin: * (có thể dùng bên máy khách)
• Giới hạn tốc độ: 60 yêu cầu/ giờ mỗi IP (HTTP 429 khi vượt quá)
• Lỗi là miễn phí — chỉ một cuộc gọi thành công (2xx) sẽ dùng một cuộc gọi từ số lượng gọi hàng tháng của bạn. Mỗi cuộc gọi 400, 401, 404, 429 và 500 không tốn tiền của bạn.

URL cơ sở

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

Tiêu đề — liệt kê mọi máy tính

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

Trả lại một danh sách có thể đọc được bởi máy của tất cả các máy tính với các trường của mỗi người (key, label, type, default, unit) và các khóa kết quả - đủ để xây dựng một khách hàng động. Mỗi trường cũng có một cờ cần thiết — đúng cho một vài trường không có mặc định (hầu hết là ngày). Gửi chúng: một vài máy tính có thể suy ra một, phần còn lại trả lời 400 mà không có nó.

Tính toán — chạy một máy tính

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

Hình phản hồi:

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

Các máy tính toán nhận thức về quốc gia (mượn, vay, thuế thu nhập, thuế bán hàng...) chấp nhận ?country=us|uk|ca|au|in|ie|nz|za. Unknown slug trả về 404; không hỗ trợ quốc gia hoặc nhập sai trả lại 400 với một thông điệp hữu ích và đặc tả trường.

Tham số, mặc định và lỗi

Chỉ gửi các trường bạn quan tâm. Bất kỳ gì bạn bỏ qua sẽ được điền với mặc định công bố của trường đó — cùng giá trị mà trang tính toán điền trước, vì thế API và trang web luôn luôn trả lại cùng số cho cùng đầu vào. Mỗi câu trả lời liệt kê những gì nó điền dưới defaults_applied.

Mọi thứ API không thể giải quyết thành thật là một lỗi, không bao giờ là một số 0: một tham số đánh vần sai, một giá trị của kiểu sai, một tùy chọn thả xuống không biết, hoặc một trường thiếu không có mặc định (các trường ngày - một ngày sinh không thể đoán được). Mỗi 400 tên tham số vi phạm và lặp lại đầy đủ các đặc tả trường để khách hàng có thể tự sửa.

$ 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 công bố khóa, loại, đơn vị, mặc định và có cần thiết không của mỗi trường — đủ để xây dựng một khách hàng không bao giờ đoán.

Kế hoạch xác thực

Bạn có thể gọi API mà không cần khóa — yêu cầu ẩn danh bị giới hạn tốc độ theo IP. Để có một hạn mức hàng tháng cao hơn, có thể dự đoán (và sử dụng thương mại), hãy tạo một khóa trên trang tài khoản của bạn và gửi nó theo một trong ba cách sau:

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"

• Tự do — ẩn danh (giảm tốc độ IP) hoặc một chìa khóa miễn phí với một số lượng nhỏ hàng tháng. Không thương mại.
• Nhà phát triển — $9/mo — 10.000 cuộc gọi/tháng, sử dụng thương mại.
• Công việc — $49/tháng — 100,000 cuộc gọi/tháng, ưu tiên.

Điều gì được tính vào số lượng của anh

Chỉ có một câu trả lời thành công mới có thể. Một 2xx = một cuộc gọi. Mỗi lỗi đều miễn phí: 400 cho một tham số đánh vần sai, một giá trị sai hoặc thiếu một trường cần thiết, 404 cho một slug không biết, 401 cho một chìa khóa sai, 429, và bất kỳ điều gì sai ở phía chúng tôi. Khám phá hợp đồng và sửa yêu cầu của bạn bao nhiêu lần bạn cần — bạn sẽ được tính tiền cho câu trả lời, không phải cho sự sửa chữa.

Bởi vì lỗi là miễn phí chúng được giới hạn tốc độ thay vì: nếu một phím gây ra nhiều hơn 200 nếu không nhận được phản hồi trong một giờ, nó sẽ nhận được HTTP 429 "too_many_invalid_requests" cho đến khi giờ trôi qua. Các cuộc gọi thành công không bao giờ được tính vào đó, vì vậy một tích hợp hoạt động sẽ không bao giờ thấy nó — nó chỉ bắt được một khách hàng bị kẹt trong vòng lặp thử lại.

Khi hạn ngạch hàng tháng của một chìa khóa được sử dụng API trả lại HTTP 429 với lỗi "quota_exceeded"; một chìa khóa không rõ hoặc không hoạt động trả lại HTTP 401. Xem kế hoạch đầy đủ và đăng ký trên Giá trang.

Ví dụ

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ất cả các điểm cuối

Một điểm cuối cho mỗi máy tính. Phím trường và phím kết quả cho mỗi cái là trong /api/v1/ chỉ mục.