🔌 الحساب الحر

ألف - استعراض عام

يقوم برنامج التطبيقات بتشغيل نفس الحسابات التي يستخدمها الموقع. يمكنك إرسال قيم حقل الحاسبة كبارامترات استفسار أو JSON والحصول على النتائج المحسوبة مرة أخرى كJSON - بما في ذلك أي جدول إهلاك أو بيانات الرسم البياني التي تنتجها الحاسبة.

• 198+ أجهزة حسابية، كل منها له نقطة نهائية خاصة به
• لا يوجد مفتاح API — الوصول المجهول الهوية، محدود المعدل بموجب بروتوكول الإنترنت
• CORS — Access-Control-Allow-Origin: * (قابلة للاستخدام في جانب الزبون)
• الحد الأقصى للمعدل: 60 طلبات/ساعة لكل بروتوكول شبكة (HTTP 429 عند تجاوزها)
• الأخطاء مجانية — فقط رد ناجح (2xx) يستخدم مكالمة واحدة من حصتك الشهرية. كل 400، 401، 404، 429 و 500 تكلفك شيئا.

العنوان الأساسي

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

الفهرس - قائمة بكل آلة حسابية

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

يعيد قائمة مقروءة آليا من جميع الحسابات مع كل حقل (الكلمة، العلامة، النوع، الافتراض، الوحدة) ومفاتيح النتيجة - بما يكفي لبناء عميل ديناميكي. كل حقل يحمل أيضاً راية مطلوبة - صحيحة بالنسبة للمجالات القليلة التي لا تحتوي على بيانات افتراضية (التواريخ، في الغالب). أرسل تلك: يمكن لبعض الحاسبات الاستدلال على واحدة، والباقي يجيب 400 بدونها.

حساب - تشغيل آلة حساب واحدة

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

حسابات قائمة على البلدان (الرهن العقاري، القروض، ضريبة الدخل، ضريبة المبيعات...) ?country=us|uk|ca|au|in|ie|nz|za. يرجع سلوك غير معروف 404؛ البلد غير المدعوم أو المدخلات السيئة يرجع 400 مع رسالة مفيدة ومواصفات الحقل.

البارامترات والافتراضات والأخطاء

إرسال الحقول التي تهتم بها فقط. أي شيء تتركه خارج يتم ملؤه بالقيمة الافتراضية المنشورة لذلك الحقل - نفس القيمة التي تملأها صفحة الحاسبة مسبقًا، لذا فإن API والموقع دائمًا يرجعان نفس الأرقام لنفس المدخلات. كل رد يورد ما تم ملؤه تحت defaults_applied.

أي شيء لا يستطيع برنامج الوصلة البينية حله بصدق هو خطأ، وليس صفرا أبدا: مقياس مخطئ في الهجاء، أو قيمة من النوع الخاطئ، أو خيار غير معروف في القائمة المنسدلة، أو حقل مفقود لا يحتوي على قيمة افتراضية (حقول التاريخ - تاريخ الميلاد لا يمكن تخمينه). كل 400 اسم للمقياس المخالف ويصدق على مواصفات الحقل الكاملة حتى يتمكن العميل من تصحيح نفسه.

$ 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 ينشر كل حقل مفتاح، نوع، وحدة، افتراضي وما إذا كان مطلوبا - بما فيه الكفاية لبناء عميل لا تخمين أبدا.

التوثيق والخطط

يمكنك استدعاء واجهة البرمجة التطبيقية بدون مفتاح على الإطلاق - الطلبات المجهولة هي محدودة بالمعدل حسب عنوان IP. لحصة شهرية أعلى ويمكن التنبؤ بها (والاستخدام التجاري)، إنشاء مفتاح على صفحة حسابك وإرساله واحدة من ثلاث طرق:

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"

• مجاني — غير معروفة الهوية (محدودة بمعدلات بروتوكول الإنترنت) أو مفتاح مجاني بحصة شهرية صغيرة.
• مطور 9 دولارات شهريا — 000 10 مكالمة شهريا، الاستخدام التجاري.
• الأعمال التجارية 49 دولارا/شهريا — 000 100 مكالمة/شهرا، معدل مرور على سبيل الأولوية.

ماذا يحسب في حصتك

كل خطأ مجاني: 400 لبارامترات مخطئة، أو قيمة سيئة أو حقل مطلوب مفقود، 404 لـسلوك غير معروف، 401 لمفتاح سيء، 429، وأي شيء يحدث خطأ من جانبنا. استكشف العقد وأصلح طلبك كلما احتجت إليه - يتم تحصيل رسوم منك عن الإجابات، وليس عن التصحيحات.

لأن الأخطاء خالية فهي محدودة بالمعدل بدلاً من ذلك: إذا كان مفتاح واحد يسبب أكثر من 200 إذا رفضت الاستجابات في ساعة، فهي تحصل على HTTP 429 "too_many_invalid_requests" حتى تمر الساعة. المكالمات الناجحة لا تحسب أبدا في ذلك، لذا فإن التكامل العامل لن يرى أبدا - إنه فقط يأخذ العميل عالقًا في حلقة إعادة المحاولة.

عندما تستخدم حصة المفتاح الشهرية، يعيد API HTTP 429 مع خطأ "quota_exceeded"؛ مفتاح غير معروف أو غير نشط يعيد 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}'

جميع النقاط النهائية

وترد مفاتيح الحقل ومفاتيح النتائج لكل منها في القائمة التالية: /api/v1/ الفهرس.