واجهة برمجة تطبيقات Search Console

الخلاصة — تتيح لك Search Console API جلب بيانات Google Search Console بالشفرة بدلاً من النقر في الواجهة. وهي تمنحك أكثر مما تمنحه الواجهة؛ فتصدير الواجهة يتوقف عند نحو 1 000 صف، بينما تمنحك API حتى 25 000 صف لكل طلب. تسجل الدخول عبر Google باستخدام OAuth، لا مفتاح API بسيطاً، ولا تحصل إلا على بيانات المواقع التي تحققت من ملكيتها.

ما هي Search Console API؟

تعرض Search Console أداء موقعك في Google: الاستعلامات التي ترتب لها، وعدد النقرات ومرات الظهور، وما إذا كانت صفحاتك مفهرسة. وتمنحك API وصولاً برمجياً إلى قدر كبير من البيانات وعناصر التحكم نفسها، بحيث ترسلها إلى جدول بيانات أو لوحة معلومات أو برنامج نصي مجدول. لكنها لا تتكافأ تماماً مع الواجهة؛ فبعض الوظائف، مثل الاختبار المباشر لعنوان URL، موجودة في الواجهة وحدها، كما أن الوصول إلى API أو الأتمتة لا يضمن في حد ذاته الفهرسة أو الترتيب أو تشخيص الزيارات أو الظهور في بحث الذكاء الاصطناعي.

تتكون من أربعة أجزاء:

1. Search Analytics API — أرقام تقرير الأداء، مثل النقرات ومرات الظهور ونسبة النقر إلى الظهور ومتوسط الموضع، موزعة حسب الاستعلام والصفحة والبلد والجهاز والتاريخ.
2. URL Inspection API — حالة فهرسة عنوان URL واحد. تعرض النسخة الموجودة حالياً في فهرس Google؛ ويمكن لأداة URL Inspection في الواجهة إجراء اختبار مباشر لا تستطيع API إجراءه.
3. Sitemaps API — سرد خرائط الموقع أو إرسالها أو حذفها.
4. Sites API — سرد الملكيات في حسابك أو إضافتها أو إزالتها.

حد ملكيات المنصات: لدى Search Console الآن ملكيات منفصلة لـInstagram وTikTok وX وYouTube، لكن وثائق Google الحالية للمنصات تصف تقارير الواجهة وتصديرها، لا معرف siteUrl أو عقد دعم نقاط النهاية القديمة. ولذلك يغطي سير عمل API في هذا المقال ملكيات مواقع الويب فقط. ولا تعد LinkedIn ملكية منصة مدعومة.

لماذا تستخدمها بدلاً من الواجهة؟

السبب الأكبر هو الصفوف. إذا صدرت تقرير الأداء من واجهة Search Console، تحصل على نحو 1 000 صف. أما API فتعيد حتى 25 000 صف لكل طلب، ويمكنك التنقل للحصول على المزيد. وإذا كان موقعك يحتوي آلاف الاستعلامات أو الصفحات، فلن تعرض لك الواجهة معظم بياناتك ببساطة.

والسبب الآخر هو الأتمتة. بعد تحويل المهمة إلى استدعاء API، تستطيع تشغيلها كل صباح وإرسال البيانات إلى لوحة معلومات أو إصدار تنبيه عند انخفاض النقرات.

القيد

لا يمكنك سحب البيانات إلا للملكيات التي تحققت منها في Search Console. إذا وجهت API إلى موقع لا تملكه فلن تحصل على شيء، وهذا أكثر ما يعثر فيه المبتدئون.

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

الخلاصة — Search Console API هي أربع واجهات REST تحت webmaster-tools/v1: Search Analytics وURL Inspection وSitemaps وSites. تستخدم كلها OAuth 2,0 وتقتصر على الملكيات التي تم التحقق منها. تعيد Search Analytics من 1 إلى 25 000 صف لكل طلب، والافتراضي 1 000، لكنها “does not guarantee to return all data rows but rather top ones” (الترجمة العربية): «لا تضمن إعادة جميع صفوف البيانات، بل الصفوف الأعلى فقط»، ولذلك تنتقل عند الحاجة إلى اكتمال واسع النطاق إلى التصدير المجمع في BigQuery. وتخضع URL Inspection لحد صارم قدره 2 000 طلب يومياً و600 طلب في الدقيقة لكل موقع؛ وهذا الحساب هو ما يقيد مراقبة الفهرسة على نطاق كبير.

يقتصر دليل API هذا على ملكيات مواقع الويب. لا تفترض أن نقاط نهاية Sites أو Search Analytics أو URL Inspection أو Sitemaps تدعم ملكيات منصات Instagram أو TikTok أو X أو YouTube حتى توثق Google المعرف وعقد نقطة النهاية.

نظرة سريعة إلى واجهات API الأربع

تصوغ Google وظيفة API بأنها تتيح لك “view, add, or remove properties and sitemaps, run advanced queries for Google Search results data for the properties that you manage in Search Console, and test individual pages.” (الترجمة العربية): «عرض الملكيات وخرائط الموقع أو إضافتها أو إزالتها، وتشغيل استعلامات متقدمة لبيانات نتائج بحث Google للملكيات التي تديرها في Search Console، واختبار صفحات فردية». وينطبق ذلك بوضوح على الموارد الأربعة، وكلها تحت webmaster-tools/v1:

• Search Analytics API — تقرير الأداء برمجياً: النقرات ومرات الظهور ونسبة النقر والموضع حسب البعد، مثل الاستعلام والصفحة والبلد والجهاز وشكل الظهور في البحث والتاريخ والساعة.
• URL Inspection API — حالة فهرسة عنوان URL واحد، وهي النظير البرمجي لأداة URL Inspection.
• Sitemaps API — سرد خرائط الموقع والحصول عليها وإرسالها وحذفها.
• Sites API — سرد الملكيات المتحقق منها وإضافتها وإزالتها.

تعرض API كثيراً مما تستخدمه في الواجهة، مثل تقرير الأداء وأداة URL Inspection، كنقاط نهاية قابلة للبرمجة. لكنها ليست مرآة متطابقة؛ فلا تضمن تكافؤاً كاملاً مع الواجهة، إذ لا يوجد اختبار URL Inspection المباشر مثلاً إلا في الواجهة، كما أن الوصول إلى API أو الأتمتة لا يضمن وحده الفهرسة أو الترتيب أو تشخيص الزيارات أو الظهور في بحث الذكاء الاصطناعي.

المصادقة: OAuth 2,0 ونطاقان والملكيات المتحقق منها فقط

لا يوجد مفتاح API. كل استدعاء يستخدم OAuth 2,0، وتقول Google صراحة إن “all requests to the Google Search Console API must be authorized by an authenticated user.” (الترجمة العربية): «يجب أن يفوض مستخدم مصادق عليه جميع الطلبات إلى Google Search Console API». تسجل تطبيقاً في Google Cloud، وتطلب نطاقاً، وتحصل على رمز وصول قصير العمر. ويوجد نطاقان:

• https://www.googleapis.com/auth/webmasters — قراءة وكتابة.
• https://www.googleapis.com/auth/webmasters.readonly — قراءة فقط.

للأتمتة بين الخوادم، مثل تقرير ليلي أو مراقب للفهرس، تمنح حساب خدمة حق الوصول إلى الملكية وتتجاوز تدفق الموافقة التفاعلي.

بالنسبة إلى ملكيات مواقع الويب، تهم صيغتان لمعرف الملكية: تمرر ملكية بادئة URL كعنوان الملكية كاملاً، ومثال Google هو http://www.example.com/، بينما تستخدم ملكية النطاق الصيغة sc-domain:example.com. عليك تمرير الصيغة المطابقة لطريقة التحقق من الملكية في Search Console. وفي الحالتين يحتاج حساب الخدمة أو المستخدم إلى وصول ممنوح للملكية المحددة نفسها؛ فلا تتجاوز هذه الآلية الملكية ولا تمنح وصولاً شاملاً لكل ملكيات الحساب.

أما الشرط الذي يعرقل الجميع فهو: “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” (الترجمة العربية): «يجب أن تملك مستوى الوصول المناسب، مالكاً أو كاملاً أو قراءة، إلى أي حساب Google Search Console تريد الوصول إليه عبر API». إذا استدعيت API لملكية لم تتحقق منها فلن تعيد شيئاً؛ وقد يكون ذلك بيانات فارغة لا خطأً واضحاً.

Search Analytics API: تقرير الأداء على نطاق واسع

ابدأ بالسقف لا بالسهولة. تحذر Google بأن “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” (الترجمة العربية): «تخضع API لقيود Search Console الداخلية ولا تضمن إعادة جميع صفوف البيانات، بل الصفوف الأعلى فقط». يوسع ترقيم الصفحات المسافة التي تستطيع قطعها في قائمة الصفوف الأعلى، لكنه لا يزيل السقف. وعندما تحتاج كل صف، فهذا هو وقت استخدام التصدير المجمع إلى BigQuery أدناه، لا قيمة rowLimit أكبر.

ومع ذلك تظل هذه الواجهة سبب استخدام معظم الناس لـAPI. تتفوق على الواجهة بسبب معامل rowLimit: “[Optional; Valid range is 1–25,000; Default is 1,000].” (الترجمة العربية): «اختياري؛ النطاق الصالح من 1 إلى 25 000؛ والافتراضي 1 000». يتوقف تصدير الواجهة عند نحو 1 000 صف، بينما تمنحك API حتى 25 000 صف لكل طلب، وتنتقل بعدها باستخدام startRow. وفي موقع له ذيل طويل من الاستعلامات، يعني ذلك رؤية بيانات أكثر، وإن لم تكن كلها.

يشكل أمران آخران النتيجة. أولاً، تتحكم dataState في حداثة البيانات: تعيد final، وهي الافتراضية، البيانات النهائية فقط؛ وتضم all بيانات حديثة جُمعت للتو؛ وتوفر hourly_all تفصيلاً بالساعة يكون جزئياً صراحة، وتحدد بيانات الاستجابة first_incomplete_date أو first_incomplete_hour، كما تنبه Google إلى أن القيم بعد تلك النقطة قد تتغير. ثانياً، ليست حصص Search Analytics رقماً واحداً؛ إذ تفصل صفحة الحدود بين حدود التحميل القائمة على الموارد والمقاسة في فترات عشر دقائق ويوم واحد، وبين حدود معدل الطلبات QPS وQPM وQPD. تستهلك النطاقات الزمنية الأوسع والأبعاد الأكثر والتصفية الأثقل حصة أكبر، وقد تبلغ حد التحميل قبل حد معدل الطلبات.

URL Inspection API: الحصة التي تقيدك فعلياً

تقول وثائق URL Inspection API إنها “view[s] the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” (الترجمة العربية): «تعرض حالة الفهرسة أو قابلية الفهرسة لعنوان URL المقدم. لا تتاح حالياً إلا حالة النسخة الموجودة في فهرس Google؛ ولا يمكنك اختبار قابلية فهرسة عنوان URL مباشر». وهذا قيد حقيقي: تستطيع أداة URL Inspection في الواجهة إجراء اختبار مباشر للصفحة كما هي الآن، بينما لا تستطيع API إلا الإبلاغ عن النسخة الموجودة في الفهرس. استخدمها لبناء مراقبة تغطية الفهرس لعدة عناوين، لا بديلاً من اختبار الواجهة المباشر.

وهنا يصبح الحساب مهماً. تحصل لكل موقع على 2 000 طلب يومياً و600 طلب في الدقيقة. أما الحد لكل مشروع فأعلى بكثير، 10 000 000 يومياً و15 000 في الدقيقة، لكن حد الموقع هو المؤثر. إذا أردت مراقبة حالة فهرسة موقع يضم 50 000 عنوان URL، فلن تستطيع فحصها كلها في يوم واحد؛ وعليك توزيعها على دفعات وأيام أو تحديد الأولويات. لا تحسب مقالات كثيرة هذه المسألة، مع أنها أكبر قيد تخطيطي للمراقبة واسعة النطاق.

وبالمقارنة، تعد Search Analytics سخية، بمقدار 1 200 طلب في الدقيقة لكل موقع ولكل مستخدم، بينما تبلغ موارد Sitemaps وSites مقدار 20 طلباً في الثانية و200 في الدقيقة لكل مستخدم. URL Inspection هي الأضيق.

واجهتا Sitemaps وSites

تدير Sitemaps API خرائط موقعك؛ فهي “submits a sitemap for a site,” (الترجمة العربية): «ترسل خريطة موقع لموقع»، و*“deletes a sitemap from this site,”* (الترجمة العربية): «تحذف خريطة موقع من هذا الموقع»، و*“retrieves information about a specific sitemap,”* (الترجمة العربية): «تسترجع معلومات عن خريطة موقع محددة»، و*“lists the sitemaps-entries submitted for this site, or included in the sitemap index file.”* (الترجمة العربية): «تسرد إدخالات خرائط الموقع المرسلة لهذا الموقع أو المضمنة في ملف فهرس خرائط الموقع». ويتضمن مورد خريطة الموقع حقولاً مثل path وlastSubmitted وisPending وisSitemapsIndex وlastDownloaded وwarnings وerrors ومصفوفة contents، وهي مفيدة لتدقيق صحة الخرائط على نطاق واسع.

أما Sites API فتسرد الملكيات المتحقق منها وتضيفها وتزيلها، وهي مفيدة عند إدارة ملكيات كثيرة تريد توفيرها أو تدقيقها برمجياً.

متى تستخدم التصدير المجمع إلى BigQuery؟

في المواقع الكبيرة، يصبح نموذج 25 000 صف لكل طلب والصفوف الأعلى فقط سقفاً. ولا تقدم Google مورداً خامساً يعيد الشكل نفسه من البيانات، بل مسار تصدير مجدولاً منفصلاً هو التصدير المجمع للبيانات إلى BigQuery. فكر في الاختيار على أنه سحب مقابل دفع مجدول، لا API أ مقابل API ب. تصفه Google هكذا: “Schedule a daily export of your Search Console performance data to BigQuery, where you can run complex queries over your data or export it to an external storage service. Using the bulk data export feature, you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” (الترجمة العربية): «جدول تصديراً يومياً لبيانات أداء Search Console إلى BigQuery، حيث يمكنك تشغيل استعلامات معقدة على بياناتك أو تصديرها إلى خدمة تخزين خارجية. وباستخدام التصدير المجمع سترى جميع بيانات الأداء المتاحة للملكية، باستثناء الاستعلامات مجهولة الهوية».

قاعدة القرار هي:

• تصدير الواجهة — نحو 1 000 صف لإلقاء نظرة سريعة مرة واحدة.
• Search Analytics API — حتى 25 000 صف لكل طلب، مع ترقيم وقابلية للبرمجة؛ مناسب للسحوبات المتوسطة عند الطلب ولوحات المعلومات.
• التصدير المجمع إلى BigQuery — جميع بيانات الأداء المتاحة يومياً بلا حد للصفوف؛ وهو الأنسب عندما تملك عشرات الآلاف من الصفحات أو الاستعلامات.

ولا يمنحك أي منها الاستعلامات مجهولة الهوية التي تخفيها Google للخصوصية. هذه فجوة حقيقية لا خطأ يمكن التحايل عليه. أعرف حجمها مباشرة؛ فبصفتي سفير علامة Ahrefs ساعدت في إبراز دراسة سحبنا فيها كل البيانات المتاحة من API عبر عينة كبيرة جداً من المواقع، ووجدنا أن Google تخفي عبارة الكلمة المفتاحية لنسبة كبيرة من النقرات. ثم بنينا ذلك في Ahrefs Rank Tracker: سجل كامل لبيانات GSC، ونسبة النقرات المنسوبة إلى الاستعلامات مجهولة الهوية، ومنحنى CTR مخصصاً من أرقامك. حين يقول أحدهم إن API تعيد «كل بياناتك»، فهذه الشريحة المخفية هي الاستثناء الصادق.

حالات الاستخدام الشائعة

• التقارير المؤتمتة — سحوبات مجدولة إلى Sheets أو مستودع بيانات.
• لوحات ذكاء الأعمال — Looker Studio أو BigQuery فوق بيانات الأداء.
• مراقبة الفهرسة والتغطية على نطاق واسع — URL Inspection موزعة ضمن حصة 2 000 طلب يومياً.
• بناء منحنى CTR — نمذجة نسبة النقر المتوقعة حسب الموضع من بياناتك.
• تنبيهات الشذوذ — رصد انخفاض النقرات أو مرات الظهور تلقائياً.

هكذا تعمل أيضاً أدوات الأطراف الثالثة؛ فعندما «تدمج» Ahrefs أووصلة Looker Studio مع Search Console، فإنها تستدعي واجهات API نفسها، وبصورة متزايدة تصدير BigQuery، نيابة عنك.

ملخص الذكاء الاصطناعي

خلاصة مكثفة للنسخة المتقدمة:

• Search Console API تساوي أربع واجهات REST تحت webmaster-tools/v1: Search Analytics لبيانات الأداء، وURL Inspection لحالة الفهرسة، وSitemaps، وSites. ولا تتكافأ تماماً مع الواجهة؛ فبعض الوظائف مثل الاختبار المباشر متاحة في الواجهة فقط، ولا يضمن الوصول إلى API وحده الفهرسة أو الترتيب أو تشخيص الزيارات.
• المصادقة عبر OAuth 2,0 بلا مفتاح API. يوجد نطاقا webmasters وwebmasters.readonly، وتستخدم حسابات الخدمة للاتصال بين الخوادم، لكنها تحتاج وصولاً صريحاً إلى الملكية نفسها. يقبل siteUrl ملكية بادئة URL أو ملكية نطاق بصيغة sc-domain:example.com. ولا تعيد API إلا بيانات الملكيات التي تحققت منها.
• تعيد Search Analytics الصفوف الأعلى أولاً، لا تفريغاً كاملاً، بغض النظر عن الترقيم. وفي هذا السقف تقبل من 1 إلى 25 000 صف لكل طلب، والافتراضي 1 000، مقابل نحو 1 000 في تصدير الواجهة، وتنقسم الحصص إلى حدود تحميل وحدود معدل طلبات.
• URL Inspection: مقدار 2 000 طلب يومياً و600 في الدقيقة لكل موقع، ولا تعرض إلا النسخة المفهرسة ولا تجري اختباراً مباشراً. هذه الحصة هي القيد الحقيقي للمراقبة واسعة النطاق.
• Sitemaps API تسرد الخرائط وتحصل عليها وترسلها وتحذفها، وSites API تسرد الملكيات وتضيفها وتزيلها.
• للمواقع الكبيرة استخدم التصدير المجمع إلى BigQuery، وهو مسار مجدول منفصل يمنح جميع بيانات الأداء المتاحة يومياً بلا حد للصفوف، باستثناء الاستعلامات مجهولة الهوية.
• الاستعلامات مجهولة الهوية فجوة حقيقية لا تسدها API أو التصدير؛ وقد قاس عمل Patrick في Ahrefs حجم هذه الشريحة المخفية.

الوثائق الرسمية

وثائق المصدر الأول من Google.

مرجع Search Console API

• نظرة عامة على Search Console API — وظيفة API ومتطلب الملكية المتحقق منها.
• مرجع استعلام Search Analytics — معامل rowLimit من 1 إلى 25 000 ومعاملات الأبعاد.
• مرجع URL Inspection API — بيانات حالة الفهرسة التي تعيدها طريقة الفحص.
• مرجع Sitemaps API — السرد والحصول والإرسال والحذف.
• مرجع Sites API — سرد الملكيات المتحقق منها وإضافتها وإزالتها.
• حدود الاستخدام — جدول الحصص الكامل لكل موقع ومستخدم ومشروع.
• تفويض الطلبات باستخدام OAuth 2,0 — النطاقات وتدفق المصادقة.

التصدير المجمع للبيانات

• حول التصدير المجمع للبيانات (مساعدة Search Console) — جدولة تصدير يومي إلى BigQuery لجميع بيانات الأداء عدا الاستعلامات مجهولة الهوية.
• إعلان التصدير المجمع للبيانات (مدونة Search Central) — إعلان الإطلاق الذي يضع التصدير المجمع في سياق المواقع الكبيرة.

اقتباسات من المصدر

تصريحات مسجلة في وثائق Google. يقفز كل رابط إلى المقطع المقتبس في صفحة المصدر.

Google — ما الذي تفعله API ومن يستطيع استخدامها

• “view, add, or remove properties and sitemaps, run advanced queries for Google Search results data for the properties that you manage in Search Console, and test individual pages.” (الترجمة العربية): «عرض الملكيات وخرائط الموقع أو إضافتها أو إزالتها، وتشغيل استعلامات متقدمة لبيانات نتائج بحث Google للملكيات التي تديرها في Search Console، واختبار صفحات فردية». — وثائق Google Search Console API (نظرة عامة). انتقل إلى الاقتباس
• “You must have appropriate access (owner, full, read) to any Google Search Console account that you wish to access using the API.” (الترجمة العربية): «يجب أن تملك مستوى الوصول المناسب، مالكاً أو كاملاً أو قراءة، إلى أي حساب Google Search Console تريد الوصول إليه عبر API». — وثائق Google Search Console API (نظرة عامة). انتقل إلى الاقتباس
• “All requests to the Google Search Console API must be authorized by an authenticated user.” (الترجمة العربية): «يجب أن يفوض مستخدم مصادق عليه جميع الطلبات إلى Google Search Console API». — دليل تفويض الطلبات. انتقل إلى الاقتباس

Google — واجهة Search Analytics API

• “[Optional; Valid range is 1–25,000; Default is 1,000]” (الترجمة العربية): «اختياري؛ النطاق الصالح من 1 إلى 25 000؛ والافتراضي 1 000» — معامل rowLimit. — مرجع استعلام Search Analytics. انتقل إلى الاقتباس
• “The URL of the property as defined in Search Console.” (الترجمة العربية): «عنوان URL للملكية كما هو محدد في Search Console» — معامل siteUrl، وتقدم أمثلته صيغة بادئة URL وهي http://www.example.com/ وصيغة ملكية النطاق sc-domain:example.com. — مرجع استعلام Search Analytics. انتقل إلى الاقتباس
• “The API is bounded by internal limitations of Search Console and does not guarantee to return all data rows but rather top ones.” (الترجمة العربية): «تخضع API لقيود Search Console الداخلية ولا تضمن إعادة جميع صفوف البيانات، بل الصفوف الأعلى فقط». — مرجع استعلام Search Analytics. انتقل إلى الاقتباس

Google — واجهة URL Inspection API

• “View the indexed, or indexable, status of the provided URL. Presently only the status of the version in the Google index is available; you cannot test the indexability of a live URL.” (الترجمة العربية): «تحقق من حالة فهرسة عنوان URL المقدم أو أهليته للفهرسة. ولا تتوفر حاليًا إلا حالة نسخته المفهرسة لدى Google؛ أما قابلية فهرسة النسخة المباشرة فلا يمكن اختبارها». — مرجع URL Inspection API. انتقل إلى الاقتباس

Google — واجهة Sitemaps API

• “Submits a sitemap for a site.” / “Deletes a sitemap from this site.” / “Lists the sitemaps-entries submitted for this site, or included in the sitemap index file.” (الترجمة العربية): «ترسل خريطة موقع لموقع» / «تحذف خريطة موقع من هذا الموقع» / «تسرد إدخالات خرائط الموقع المرسلة لهذا الموقع أو المضمنة في ملف فهرس خرائط الموقع». — مرجع Sitemaps API. انتقل إلى الاقتباس

Google — التصدير المجمع للبيانات

• “Schedule a daily export of your Search Console performance data to BigQuery… you’ll see all the performance data available to Search Console for your property, with the exception of anonymized queries.” (الترجمة العربية): «جدول تصديراً يومياً لبيانات أداء Search Console إلى BigQuery… سترى جميع بيانات الأداء المتاحة للملكية، باستثناء الاستعلامات مجهولة الهوية». — مساعدة Search Console: حول التصدير المجمع للبيانات. انتقل إلى الاقتباس

قائمة فحص إعداد OAuth والاستدعاء الأول

للانتقال من الصفر إلى استدعاء عامل لـSearch Console API:

• تأكد من أن لديك وصولاً متحققاً منه، بصفة مالك أو وصول كامل أو قراءة، إلى الملكية في Search Console؛ فلا تعيد API شيئاً للملكيات غير المتحقق منها.
• أنشئ مشروعاً في Google Cloud Console.
• فعّل Search Console API للمشروع.
• أنشئ بيانات اعتماد: عميل OAuth 2,0 للتطبيقات التفاعلية أو تطبيقات المستخدم، أو حساب خدمة للأتمتة بين الخوادم.
• إذا استخدمت حساب خدمة، فامنحه حق الوصول إلى الملكية في إعدادات Search Console.
• اطلب النطاق المناسب: webmasters.readonly للتقارير، أو webmasters إذا كنت سترسل خرائط الموقع أو تدير الملكيات.
• احصل على رمز وصول عبر تدفق OAuth أو مفتاح حساب الخدمة.
• تأكد من أن صيغة siteUrl تطابق طريقة التحقق: عنوان كامل لملكية بادئة URL، أو sc-domain:example.com لملكية نطاق.
• نفذ استدعاء اختبارياً إلى searchAnalytics.query بنطاق زمني صغير وrowLimit: 10 للتأكد من عودة البيانات.
• خطط للحصص: معدلات طلب Search Analytics سخية لكنها تستهلك أيضاً حصة تحميل منفصلة، بينما تقتصر URL Inspection على 2 000 يومياً و600 في الدقيقة لكل موقع. ولا تتوقع منها إجراء اختبار مباشر؛ فهو في الواجهة فقط.
• لعشرات الآلاف من الصفوف، أعدد التصدير المجمع إلى BigQuery بدلاً من الترقيم.

النماذج الذهنية

1. أربع واجهات API ومصادقة واحدة. تقرأ Search Analytics بيانات الأداء، وتقرأ URL Inspection حالة فهرسة عنوان، وتدير Sitemaps خرائط الموقع، وتدير Sites الملكيات. تمر الأربع عبر بوابة OAuth 2,0 نفسها وتحترم قاعدة الملكية المتحقق منها نفسها.

2. سلم حجم البيانات. اختر الأداة حسب الحجم:

• نظرة سريعة ← تصدير الواجهة، نحو 1 000 صف.
• حجم متوسط قابل للبرمجة ← Search Analytics API، حتى 25 000 لكل طلب مع الترقيم.
• موقع كبير وبيانات كاملة ← التصدير المجمع إلى BigQuery، كل البيانات يومياً بلا حد للصفوف. اصعد السلم عندما لا يعود المستوى الأدنى مناسباً لحجم بياناتك.

3. الصفوف الأعلى لا كل الصفوف. ثبت في ذهنك أن API تعيد «الأعلى» لا كل شيء، وأن الاستعلامات مجهولة الهوية مستبعدة من API والتصدير معاً. إذا كان الاكتمال مهماً، فإن BigQuery أقرب إليه، لكن الشريحة مجهولة الهوية غائبة في كل الأحوال.

4. احسب الحصة قبل البناء. قبل تصميم مراقب للفهرس احسب الأمر: تتيح URL Inspection مقدار 2 000 طلب يومياً لكل موقع. لا يمكن فحص موقع يضم 50 ألف عنوان يومياً، لذا وزع العناوين على دفعات وحدد الأولويات وجدولها عبر الأيام. صمم وفق الحد بدلاً من اكتشافه في الإنتاج.

ورقة مرجعية لـSearch Console API

واجهات API الأربع وحدودها الأساسية

المصادقة

• OAuth 2,0 فقط، بلا مفتاح API.
• النطاقان: webmasters للقراءة والكتابة، وwebmasters.readonly للقراءة.
• استخدم حسابات الخدمة للاتصال بين الخوادم وامنحها الوصول إلى الملكية.
• لا تعيد البيانات إلا الملكيات المتحقق منها.

حقائق سريعة

• تعيد API الصفوف الأعلى فقط ولا تضمن الاكتمال، مهما كان الترقيم.
• يتوقف تصدير الواجهة قرب 1 000 صف، بينما تمنح API حتى 25 000 لكل طلب مع الترقيم بواسطة startRow.
• تنقسم حصص Search Analytics إلى حدود تحميل قائمة على الموارد بفترات عشر دقائق ويوم واحد، وحدود معدل طلبات QPS وQPM وQPD.
• يقبل siteUrl ملكية بادئة URL مثل http://www.example.com/ أو ملكية نطاق مثل sc-domain:example.com، ويجب أن يطابق طريقة التحقق.
• تعرض URL Inspection النسخة المفهرسة فقط ولا تجري اختباراً مباشراً؛ فهذا متاح في الواجهة.
• الاستعلامات مجهولة الهوية مستبعدة من API ومن تصدير BigQuery.
• لعشرات الآلاف من الصفوف استخدم التصدير المجمع إلى BigQuery، وهو مسار مجدول منفصل لا مورداً خامساً لـAPI.
• تعرض API كثيراً من تقرير الأداء وأداة URL Inspection، لكنها لا تتكافأ تماماً مع الواجهة.

طلب Search Analytics بسيط

هذا المثال توضيحي وليس جاهزاً للنسخ والتشغيل. تحتاج إلى ربط بيانات اعتماد OAuth الخاصة بك وضبط التواريخ والملكية. وهو يبين شكل استدعاء searchAnalytics.query: جسم طلب يحوي النطاق الزمني والأبعاد المطلوبة وrowLimit.

جسم الطلب، وهو الجزء المهم

{
  "startDate": "2026-05-01",
  "endDate": "2026-05-31",
  "dimensions": ["query", "page"],
  "rowLimit": 25000,
  "startRow": 0
}

تصور بلغة Python باستخدام مكتبة google-api-python-client

# Illustrative only — assumes you've already built an authorized `service`
# via OAuth 2.0 (scope: webmasters.readonly) or a service account.
from googleapiclient.discovery import build

service = build("searchconsole", "v1", credentials=creds)

request = {
    "startDate": "2026-05-01",
    "endDate": "2026-05-31",
    "dimensions": ["query", "page"],
    "rowLimit": 25000,   # max per request; default is 1000
    "startRow": 0,       # bump by 25000 to paginate
}

response = service.searchanalytics().query(
    siteUrl="https://example.com/",  # URL-prefix property; use "sc-domain:example.com"
                                      # instead for a Domain property — must be verified
    body=request,
).execute()

for row in response.get("rows", []):
    print(row["keys"], row["clicks"], row["impressions"])

لتجاوز 25 000 صف، كرر الطلب وزد startRow بمقدار 25 000 حتى يعيد الطلب صفوفاً فارغة. وتذكر أن النتيجة تظل «الصفوف الأعلى» وليست تفريغاً كاملاً؛ وللاكتمال استخدم التصدير المجمع إلى BigQuery.

أدوات تستخدم Search Console API أو تغلفها

• Google Cloud Console — حيث تنشئ المشروع وتفعل API وتنشئ بيانات اعتماد OAuth أو حساب الخدمة.
• مكتبات العملاء الرسمية — تغلف مكتبات Google API للغات Python وJava وJavaScript/Node وPHP و.NET استدعاءات REST.
• BigQuery — وجهة التصدير المجمع للبيانات، حيث تستعلم عن بيانات الأداء كلها باستخدام SQL.
• Looker Studio — يتصل بـSearch Console وBigQuery لإنشاء لوحات معلومات فوق البيانات نفسها.
• Ahrefs — يدمج Search Console API، ويعرض Rank Tracker سجل GSC الكامل ونسبة النقرات المنسوبة إلى الاستعلامات مجهولة الهوية ومنحنى CTR مخصصاً من بياناتك.
• واجهة Search Console — تقرير الأداء وأداة URL Inspection هما النظيران اليدويان لـSearch Analytics وURL Inspection، مع فجوة لا تغلقها API: لا تجري اختباراً مباشراً لعنوان URL إلا أداة الواجهة.

مطالبات لتخطيط العمل على Search Console API

استخدم هذه المطالبات لتشكيل الشفرة أو خطة التحليل. أبق بيانات الاعتماد ورموز التحديث ومفاتيح حساب الخدمة خارج أي مدخل دردشة.

صمم طلب Search Analytics

ألصق عنوان الملكية والنطاق الزمني والأبعاد والمرشحات وهدف التقرير.

Design a Google Search Console Search Analytics API request for the following reporting task.

Property: [sc-domain:example.com or exact URL-prefix property]
Date range: [start and end]
Goal: [the question the report must answer]
Dimensions: [date, query, page, country, device, searchAppearance, or hour]
Filters: [include/exclude rules]

Return:
1. The request body, including a rowLimit no higher than 25,000.
2. Pagination logic using startRow.
3. The aggregation and grouping needed after retrieval.
4. Warnings about top-rows-only data and anonymized queries.
5. A small validation query I can run before scheduling the full pull.

Do not invent credentials or assume the result is a complete census.

خطط لجدول URL Inspection آمن من حيث الحصة

ألصق ملخص CSV أو أعداداً حسب أولوية عنوان URL بدلاً من الرموز السرية.

Create a quota-safe sampling and scheduling plan for the Search Console URL Inspection API.

Property: [property]
Total URLs: [count]
Priority groups: [critical templates, new URLs, changed URLs, long-tail sample]
Required revisit cadence: [daily, weekly, monthly]

Constraints from this article:
- 2,000 inspection queries per day per site.
- 600 inspection queries per minute per site.
- The API reports the indexed version, not a live test.

Return a daily allocation by priority group, a rotation method, retry/backoff rules,
and alerts for unexpected index or canonical states. Explain what cannot fit inside
the quota instead of silently dropping it.

اختر بين API وتصدير BigQuery

Help me choose between the Search Console interface, Search Analytics API, and BigQuery bulk export.

Reporting need: [one-off analysis, dashboard, warehouse, anomaly alerts]
Expected rows per day: [estimate]
History required: [range]
Refresh cadence: [cadence]
Dimensions needed: [list]
Infrastructure available: [spreadsheet, script runner, BigQuery, BI tool]

Compare setup cost, row/completeness limits, automation, and maintenance. Account for
the API returning top rows and for anonymized queries being absent from every path.
End with one recommendation and the smallest proof-of-concept to validate it.

موارد تستحق وقتك

أعمالي ذات الصلة

• منشوراتي في مدونة Ahrefs — بما فيها العمل على بيانات GSC واسعة النطاق والاستعلامات مجهولة الهوية.
• سجل GSC الكامل وحصة الاستعلامات مجهولة الهوية في Ahrefs Rank Tracker — ميزة منحنى CTR وسجل GSC التي أعلنتها.

وثائق Google

• نظرة عامة على Search Console API وحدود الاستخدام — الصفحتان اللتان ينبغي حفظهما أولاً.
• حول التصدير المجمع للبيانات — متى وكيف تنتقل إلى BigQuery.

من الآخرين

• الكلمات المفتاحية المخفية في GSC: دراسة Ahrefs ‏(تغطية Search Engine Journal) — تغطية خارجية لنتائج الاستعلامات مجهولة الهوية.
• تحليلات Search Console محسنة باستخدام BigQuery ‏(SEJ) — نظرة عملية إلى مسار التصدير المجمع.
• التصدير المجمع للبيانات: طريقة جديدة وقوية للوصول إلى بيانات Search Console ‏(مدونة Google Search Central) — إعلان فبراير 2023 الذي يقدم التصدير المجمع للمواقع الكبيرة.
• google-api-python-client (PyPI) — مكتبة Python الرسمية المستخدمة لاستدعاء Search Console API، وتتوفر أيضاً لعائلة Node وJava وPHP و.NET.
• r/TechSEO — مجتمع استكشاف مشكلات API وسحب البيانات.

إحصاءات تستحق الاستشهاد

• حد صفوف Search Analytics: مقدار 25 000 لكل طلب، والافتراضي 1 000، مقابل حد تصدير الواجهة البالغ نحو 1 000 صف. وهذا السبب الأساسي لاستخدام API. المصدر
• حصة URL Inspection: مقدار 2 000 طلب يومياً و600 في الدقيقة لكل موقع، وهي السقف الصارم لمراقبة الفهرسة واسعة النطاق، مقابل 10 ملايين يومياً و15 000 في الدقيقة لكل مشروع. المصدر
• تستبعد الاستعلامات مجهولة الهوية حتى من المسار الأكثر اكتمالاً، وهو تصدير BigQuery المجمع؛ فهي فجوة حقيقية لا يمكن تجنبها في بيانات الاستعلامات. المصدر
• تخفي Google عبارة الكلمة المفتاحية لنسبة كبيرة من النقرات، وفق دراسة Ahrefs التي ساعدت في إبرازها، والتي سحبت كل البيانات المتاحة من API عبر عينة كبيرة جداً من المواقع. التغطية

اختبر نفسك: Search Console API

خمسة أسئلة سريعة عن واجهات API والمصادقة وحدود البيانات والنطاق. اختر إجابة لكل سؤال ثم تحقق من نتيجتك.

سجل التغييرات