واجهة برمجة الكلمات

مفتاحك

أرسل المفتاح في الترويسة Authorization على شكل bearer، أو في الترويسة X-API-Key.

المستوى المجاني

يمكن للمفتاح المجاني إجراء 10 طلبات في اليوم. يبدأ العدّ من جديد عند 00:00 بتوقيت UTC. كل طلب إلى نقطة تعيد بيانات يُحسب طلبًا واحدًا. تعرض الترويسات X-RateLimit-Limit وX-RateLimit-Remaining وX-RateLimit-Reset ما تبقّى لك.

نقاط الوصول

تبدأ كل المسارات بـ /api/v1. الوصف الكامل في ملف OpenAPI.

• GET /api/v1/words الكلمات المطابقة للمرشِّحات
• GET /api/v1/words/{word} كل المداخل بهذا الإملاء
• GET /api/v1/themes المواضيع التي فيها كلمات، مع الأعداد والأسماء
• GET /api/v1/themes/{theme}/words كلمات موضوع
• GET /api/v1/levels مستويات CEFR التي فيها كلمات، مع الأعداد
• GET /api/v1/levels/{level}/words كلمات مستوى
• GET /api/v1/word-of-the-day كلمة اليوم (UTC)
• GET /api/v1/word-of-the-day/{date} كلمة يوم معيّن، بالصيغة YYYY-MM-DD
• GET /api/v1/random كلمات عشوائية، لا تُخزَّن مؤقتًا أبدًا
• GET /api/v1/export/words.json كل الكلمات الظاهرة بصيغة JSON
• GET /api/v1/export/words.csv كل الكلمات الظاهرة بصيغة CSV
• GET /api/v1/meta إصدار البيانات والأعداد وحالات المراجعة الظاهرة والتراخيص. مفتوح ولا يحتاج إلى مفتاح. (لا يحتاج إلى مفتاح)

وصف OpenAPI (JSON)

الحقل review_status

لكل قيمة review_status يبيّن إلى أي حد روجعت: owner (أدخلها المالك أو أكّدها)، reviewed، imported (مأخوذة من مصدر مفتوح)، machine (مسودة آلية لم يراجعها شخص بعد) وdraft. تعرض نقطة /meta الحالات التي ترسلها الواجهة الآن. افحص هذا الحقل إن كنت تريد بيانات روجعت فقط.

الأخطاء

لكل خطأ الشكل نفسه: كائن error فيه status وcode وmessage.

• bad_request: 400: أحد المعاملات غير صحيح. تذكر الرسالة اسمه.
• unauthorized: 401: المفتاح مفقود أو غير معروف أو أُلغي.
• forbidden: 403: هذا المفتاح لا يشمل نقطة الوصول هذه.
• not_found: 404: لا شيء مطابق.
• rate_limited: 429: استهلك المفتاح طلبات اليوم. تعطي الترويسة Retry-After عدد الثواني حتى 00:00 بتوقيت UTC.
• server_error: 500: حدث خطأ من جانبنا. حاول مرة أخرى لاحقًا.

مثال

الطلب نفسه بـ curl وJavaScript وPython. استبدل YOUR_KEY بمفتاحك الخاص ولا تضعه أبداً في شيفرة عامة.

curl -H "Authorization: Bearer ih_live_YOUR_KEY" \
  "https://inburgering.help/api/v1/words/fiets?lang=en,fa"

const response = await fetch("https://inburgering.help/api/v1/words/fiets?lang=en,fa", {
  headers: { Authorization: "Bearer ih_live_YOUR_KEY" },
});
if (response.status === 429) {
  // Over the limit: try again after this many seconds.
  console.log("Retry after", response.headers.get("Retry-After"));
} else if (!response.ok) {
  console.log((await response.json()).error.message);
} else {
  console.log(await response.json());
}

import requests

response = requests.get(
    "https://inburgering.help/api/v1/words/fiets?lang=en,fa",
    headers={"Authorization": "Bearer ih_live_YOUR_KEY"},
    timeout=10,
)
if response.status_code == 429:
    # Over the limit: try again after this many seconds.
    print("Retry after", response.headers["Retry-After"])
else:
    response.raise_for_status()
    print(response.json())

الإصدارات والتغييرات

واجهة البرمجة الآن في الإصدار 1 (/api/v1). داخل الإصدار الواحد نضيف حقولاً ونقاط وصول فقط، فتجاهل الحقول التي لا تعرفها. أي تغيير قد يعطّل عميلاً يحصل على إصدار جديد، ويبقى الإصدار القديم متاحاً خلال مدة إشعار معلنة قبل إيقافه. التغييرات مذكورة أدناه.

• v1
  • الإصدار الأول: الكلمات والمواضيع والمستويات وكلمة اليوم والكلمات العشوائية والتصدير وmeta.
  • مفاتيح بحدود يومية لكل مستوى، مع حد شهري اختياري وحالات مراجعة وصلاحيات (قراءة، تصدير) لكل مستوى.
  • أسماء المواضيع بالهولندية والإنجليزية؛ أسماء المواضيع بالفارسية والعربية والتركية مسودات (تذكرها استجابة themes في labels_draft).

طلب مفتاح API

لا تُصدَر المفاتيح لطالبين جدد حاليًا. عُد لاحقًا.