المطورون

واجهة API العامة

اقرأ مواقعك وتقاريرك ومراتبك وكلماتك المفتاحية عبر واجهة API بسيطة تعتمد على مفتاح. ميزة Agency.

واجهة API العامة

لخطوات الإعداد، راجع دليل ميزة API العامة.

توفر واجهة API العامة وصول قراءة فقط إلى البيانات التي يحتفظ بها RankMeFast بالفعل لحسابك, المواقع، وأحدث تقرير تدقيق، وسجل المراتب، والكلمات المفتاحية المتتبعة. إنها ميزة خطة Agency (انظر الخطط والحدود والأرصدة). لا تُطلق واجهة API أبدًا عملًا جديدًا لدى المزوّدين, بل تقرأ فقط ما أنتجته تدقيقاتك وفحوصات المراتب مسبقًا.

بدء تحليلات Content Intelligence وتغيير حالة التوصيات ليسا جزءًا من /api/v1. تظل هذه عمليات داخل المنتج تتطلب تسجيل الدخول وتحميها Better Auth. يستطيع MCP قراءة التحليلات المحفوظة، لكنه لا يوفر أداة لبدء تحليل محتوى أو تغيير توصية.

المصادقة

أنشئ مفتاحًا من الحساب ← مفاتيح API (/profile?tab=api-keys). يُعرض المفتاح الكامل مرة واحدة فقط: انسخه فورًا؛ وبعدها لن يظهر سوى بادئته. يمكنك الاحتفاظ بما يصل إلى عشرة مفاتيح نشطة وإبطال أي منها في أي وقت. المفتاح المُبطل يتوقف عن العمل فورًا.

أرسل المفتاح كرمز bearer مع كل طلب:

Authorization: Bearer rmf_XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

استبدل https://your-rankme-host في الأمثلة أدناه بأصل واجهة api لديك (قيمة SERVER_URL في تنصيبك).

لغة الاستجابة وعقد البيانات

اختر لغة النص عبر x-lang ثم Accept-Language، وإلا تستخدم الواجهة en. تُطبّع قيم الرؤوس الإقليمية مثل fr-CA بأمان إلى fr. يتجاهل /api/v1 ملفات تعريف الارتباط للمتصفح ولغة الحساب وتفضيلات مساحة العمل. تتضمن كل استجابة Content-Language الفعالة وتضيف x-lang, Accept-Language إلى Vary من دون إزالة القيم الموجودة.

تُترجم فقط نصوص التقارير والنتائج والإجراءات والأخطاء الآمنة التي تؤلفها RankMeFast. لا تتغير أسماء خصائص JSON أو حالات HTTP أو رموز الأخطاء الثابتة أو قيم التعداد والحالة أو المعرّفات أو النطاقات أو عناوين URL أو الكلمات المفتاحية أو الطوابع الزمنية أو القياسات أو الملاحظات أو المؤشرات أو نص المستخدم والمزود المخزن. ولا تغير اللغة الفرز أو تنسيق الأرقام والتواريخ.

يمثل CSV عقدًا آليًا متطابق البايتات في كل لغات الاستجابة. تبقى BOM بترميز UTF-8 وأسماء الرؤوس وترتيبها وترتيب الصفوف واقتباس RFC-4180 والقيم ونهايات الأسطر واسم الملف ورؤوس التقسيم وسلوك المؤشر كما هي. يصف Content-Language اختيار الاستجابة، ولا يترجم بايتات CSV أو يعيد تسميتها.

نقاط النهاية

قائمة مواقعك

curl -H "Authorization: Bearer rmf_..." \
  https://your-rankme-host/api/v1/sites

تعيد { "sites": [{ "id", "domain", "url", "createdAt" }] }.

أحدث تقرير تدقيق لموقع

curl -H "Authorization: Bearer rmf_..." \
  https://your-rankme-host/api/v1/sites/<siteId>/report/latest

تعيد أحدث تدقيق ناجح بالشكل { "runId", "report" }, نفس النتائج والفئات والنصوص المترجمة التي تعرضها لوحة التحكم. تجيب بـ 404 إذا لم يكن للموقع تدقيق مكتمل بعد.

سجل المراتب لموقع

curl -H "Authorization: Bearer rmf_..." \
  "https://your-rankme-host/api/v1/sites/<siteId>/rank-history?from=2026-06-01&to=2026-07-01"

تعيد { "keywords": [{ "id", "phrase", "series": [...] }] }. تحمل كل نقطة في السلسلة المرتبة وعنوان URL الذي تصدّر وإشارات Google AI Overview (aiOverviewPresent، aiCited، aiCitedUrl). from وto تاريخان بصيغة ISO اختياريان.

كل الكلمات المفتاحية المتتبعة

curl -H "Authorization: Bearer rmf_..." \
  https://your-rankme-host/api/v1/keywords

تعيد كل كلمة مفتاحية متتبعة عبر جميع مواقعك مع أحدث مرتبة والفرق وحقول AI Overview.

تصدير CSV والصفوف المخزنة

عند تفعيل PUBLIC_EXPORTS_ENABLED اطلب CSV من أي مسار قائمة عبر ?format=csv أو Accept: text/csv. تستخدم الملفات أعمدة ثابتة وBOM بترميز UTF-8 واقتباس RFC-4180 ونصًا آمنًا من الصيغ، بينما تبقى استجابات JSON الأصلية كما هي. يقبل سجل الترتيب engine=google|bing|youtube|amazon، ويعرض كل المحركات افتراضيًا في عمود engine.

يحتفظ CSV لسجل الترتيب والكلمات المفتاحية بالمخرجات القديمة غير المقسّمة ما لم تضف limit أو cursor معتمًا. تقبل صفحة سجل الترتيب من 1 إلى 25 مجموعة كلمات مفتاحية (بحد 730 نقطة لكل مجموعة)، وتقبل صفحة الكلمات المفتاحية من 1 إلى 1,000 صف. أرسل قيمة X-Next-Cursor في الطلب التالي وتوقّف عند غياب هذا الرأس. تتجاهل JSON معاملات تقسيم CSV هذه وتحافظ على عقد الاستجابة الأصلي.

توجد قراءتان إضافيتان للبيانات المخزنة: GET /api/v1/serp-features?siteId=<siteId> وGET /api/v1/backlink-rows?siteId=<siteId>. تقبلان limit من 1 إلى 1,000 ومؤشر cursor معتمًا، وتعيدان صفوف الحساب فقط مع الوسم sourceKind=provider_observation (source_kind في CSV). عند إيقاف العلم تجيب المسارات الجديدة وCSV بـ503 وتظل مسارات JSON الأصلية متاحة. راجع دليل Looker Studio لإعداد الموصل والحقول.

حدود المعدل

افتراضيًا يمكن لكل مفتاح إجراء 120 طلبًا في الدقيقة. بعد ذلك تجيب واجهة API بـ 429 حتى تتم إعادة ضبط النافذة.

الأخطاء

تستخدم الأخطاء الشكل { "error": { "message": "...", "details": ... } }. تتبع رسالتها البشرية الآمنة x-lang ثم Accept-Language ثم en، بينما تبقى الحالة والحقول والرموز الثابتة والتفاصيل الآمنة متوافقة آليًا:

401, المفتاح مفقود أو تالف أو مُبطل أو غير معروف.
402, خطتك لا تتضمن واجهة API.
404, الموقع أو التقرير غير موجود في حسابك.
429, تم تجاوز حد المعدل (المحتوى: { "error": "..." }).

التوافق

يوفّر هذا الإصدار ستة مسارات للقراءة فقط:

GET /api/v1/sites
GET /api/v1/sites/:siteId/report/latest
GET /api/v1/sites/:siteId/rank-history
GET /api/v1/keywords
GET /api/v1/serp-features
GET /api/v1/backlink-rows

لا تضيف ميزات رادار العلامة التجارية أو ذكاء المراجعات أو ذكاء الروابط أو تحليلات الزيارات أو اتجاهات الكلمات المفتاحية أو مستشعر SERP أي مسار تحت /api/v1. تظل الميزات الخمس المدفوعة ضمن لوحة التحكم المصادَق عليها، ويظل المستشعر العام تحت /api/volatility. تحتفظ حقول الاستجابة الحالية بمعناها، وعلى العملاء تجاهل أي حقول إضافية لا يعرفونها.

العودة إلى فهرس الوثائق