كيف أستخدم Google Search Console API؟

أنشئ مشروعًا في Google Cloud console، وفعّل Google Search Console API، وأنشئ بيانات اعتماد OAuth 2.0، ثم سجّل الدخول بحساب Google يملك صلاحية الوصول إلى الموقع. بعدها يمكنك إرسال الطلبات إلى أربعة موارد: Search Analytics للنقرات والظهور وCTR والمتوسط الترتيبي؛ وURL Inspection لحالة الفهرسة؛ وSitemaps؛ وSites. لا تكفي مفاتيح API وحدها: يحتاج كل طلب إلى رمز OAuth، وتضع الحصص حدًا لحجم ما يمكنك طلبه.

ما الذي يغطيه الـ API وما الذي لا يغطيه

هذا هو الـ API بكامله. أما تقارير الروابط وإحصاءات الزحف (Crawl stats) وتقرير فهرسة الصفحات وتقرير Core Web Vitals فليس لها أي نقطة وصول، لذا تبقى داخل واجهة Search Console. ويعرض URL Inspection ما هو موجود في فهرس Google، وليس اختبارًا مباشرًا للصفحة.

إعداد الوصول

1. أنشئ مشروعًا في Google Cloud console أو اختر مشروعًا موجودًا.
2. فعّل Google Search Console API لهذا المشروع.
3. اضبط شاشة موافقة OAuth وأنشئ معرّف عميل OAuth.
4. اطلب نطاق صلاحية (scope): https://www.googleapis.com/auth/webmasters.readonly للقراءة فقط، أو https://www.googleapis.com/auth/webmasters إذا أردت أيضًا إرسال ملفات Sitemap أو حذفها.
5. سجّل الدخول بحساب يملك صلاحية على الموقع. تتطلب قراءة بيانات الأداء صلاحية قراءة على الأقل؛ ويرى الـ API ما يراه هذا الحساب تمامًا.

أول استعلام في Search Analytics

POST https://www.googleapis.com/webmasters/v3/sites/sc-domain%3Aexample.com/searchAnalytics/query
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "startDate": "2026-09-01",
  "endDate": "2026-09-30",
  "dimensions": ["query", "page"],
  "type": "web",
  "rowLimit": 25000,
  "startRow": 0
}

يوضع الموقع في المسار بعد ترميزه بصيغة URL: sc-domain:example.com لموقع من نوع Domain، أو البادئة الدقيقة مع الشرطة المائلة الختامية، مثل https://www.example.com/، لموقع من نوع URL-prefix. وهذه أهم الحقول:

• التواريخ شاملة للطرفين وبتوقيت المحيط الهادئ.
• type قيمته الافتراضية web؛ والقيم الأخرى هي image وvideo وnews وgoogleNews وdiscover. ويحتاج كل نوع إلى طلب مستقل.
• عوامل التصفية توضع في dimensionFilterGroups، ومعها عوامل تشغيل تبدأ من equals وcontains وتصل إلى includingRegex وexcludingRegex (بصيغة RE2).
• rowLimit يتراوح من 1 إلى 25,000 (الافتراضي 1,000)؛ ويتيح startRow التنقل بين بقية الصفوف.
• dataState قيمته الافتراضية final؛ وتضيف القيمة all الأيام الحديثة غير المكتملة، وتعمل hourly_all مع البُعد hour.

يعيد كل صف الحقول keys وclicks وimpressions وctr (من 0 إلى 1) وposition، مرتبة بحسب النقرات ما لم تجمع النتائج بحسب التاريخ.

الحدود التي تشكّل طريقة كتابة الشيفرة

• 50,000 صف في اليوم لكل نوع بحث. تنقّل بين الصفحات باستخدام startRow بخطوات من 25,000 وتوقف عند أول استجابة فارغة. وللحصول على أكبر قدر من البيانات، استعلم عن يوم واحد في كل طلب.
• حصة الحمل. أكثر الطلبات كلفة هي التي تجمع أو تصفّي بحسب الصفحة والاستعلام معًا، كما أن النطاقات الزمنية الطويلة أكلف من القصيرة. وإذا تجاوزت الحصة قصيرة المدى فإن Google تطلب منك الانتظار 15 دقيقة.
• معدلات الطلبات. 1,200 استعلام في الدقيقة لكل موقع ولكل مستخدم؛ و40,000 في الدقيقة و30,000,000 في اليوم لكل مشروع.
• حصة URL Inspection. 2,000 عملية فحص في اليوم و600 في الدقيقة لكل موقع.
• سجل يمتد 16 شهرًا، وتتوفر البيانات عادةً بعد يومين إلى ثلاثة أيام من انتهاء اليوم.
• مجموع الصفوف لا يساوي الإجماليات. تُستبعد الاستعلامات النادرة من صفوف مستوى الاستعلام، ويحتسب التجميع بحسب الصفحة الظهور بطريقة تختلف عن التجميع بحسب الموقع، لذا اقرأ الإجماليات من طلب لا يتضمن البُعد query.

أخطاء شائعة

• استخدام http:// بينما الموقع مسجّل بـ https://، أو إهمال الشرطة المائلة الختامية، يؤدي إلى خطأ في الصلاحيات حتى لو كان الحساب يملك حق الوصول.
• يُرفض في URL Inspection أي عنوان URL خارج نطاق الموقع: يجب أن يكون العنوان تابعًا لقيمة siteUrl التي تمررها.
• طلب شهر كامل مجمّعًا بحسب الاستعلام والصفحة في استدعاء واحد لا يعيد إلا أعلى الصفوف. أما الطلبات اليومية فتعيد عددًا أكبر.

كيف يساعدك AutoPSEO

إذا كنت تفضّل ألا تتولى صيانة OAuth والتنقل بين الصفحات، فإن AutoPSEO يتصل عبر تسجيل الدخول بحساب Google ويتيح البيانات نفسها من خلال REST API الخاص به على المسار /v1 (مع مستند OpenAPI 3.1) وخادم MCP، وتتم المصادقة بمفتاح API من Account → API keys. تتوفر مفاتيح للقراءة فقط، وتعيد نقطة وصول تحليلات البحث حتى 5,000 صف في الاستدعاء الواحد، وتتولى أدوات URL Inspection في التطبيق احتساب حصة Google البالغة 2,000 عملية فحص يوميًا عنك. راجع MCP ومفاتيح API. وللاحتفاظ بالبيانات لأكثر من 16 شهرًا دون كتابة خط معالجة خاص بك، اطّلع على المدة التي تحتفظ فيها Search Console بالبيانات.

المصادر من Google: مرجع API، وأسلوب استعلام Search Analytics، وحدود الاستخدام، والحصول على كل بياناتك، ودليل التفويض.