ربط Google Search Console API لاستخراج آلاف الكلمات المفتاحية

ماذا سنبني اليوم؟

سنقوم ببناء سكريبت بايثون يتصل بـ Google Search Console API لاستخراج بيانات أداء البحث (الكلمات المفتاحية، الصفحات، النقرات، مرات الظهور، CTR، الموضع) لموقع ويب معين، وحفظها في ملف CSV. هذا يسمح لنا بتحليل كميات كبيرة من الكلمات المفتاحية بكفاءة لدعم استراتيجيات SEO.

المتطلبات الأساسية

• حساب Google مع إمكانية الوصول إلى Google Search Console للموقع المطلوب.
• مشروع Google Cloud Platform (GCP) مع تمكين Search Console API.
• ملف بيانات اعتماد JSON (Service Account Key) من GCP.
• بيئة بايثون (Python 3.x) مثبتة.

الخطوة 1: إعداد مشروع Google Cloud Platform

1. انتقل إلى Google Cloud Console.
2. أنشئ مشروعًا جديدًا أو اختر مشروعًا موجودًا.
3. من قائمة التنقل، انتقل إلى "APIs & Services" > "Enabled APIs & Services".
4. ابحث عن "Google Search Console API" وقم بتمكينه.
5. انتقل إلى "APIs & Services" > "Credentials".
6. انقر على "CREATE CREDENTIALS" واختر "Service Account".
7. امنح اسمًا لحساب الخدمة (مثلاً: search-console-api-reader) وامنحه دور "Project Viewer" أو "Search Console Viewer" (الأخير أفضل إذا كان متاحًا).
8. بمجرد إنشاء حساب الخدمة، انقر عليه، ثم انتقل إلى تبويب "KEYS".
9. انقر على "ADD KEY" > "Create new key"، واختر "JSON". سيتم تنزيل ملف JSON. احتفظ بهذا الملف بأمان وأعد تسميته إلى service_account.json (أو أي اسم تفضله).

ملاحظة هامة: يجب إضافة عنوان البريد الإلكتروني لحساب الخدمة (الموجود في ملف JSON تحت مفتاح client_email) كمالك أو مستخدم مع إذن "Full" أو "Restricted" في Google Search Console للموقع الذي تريد سحب البيانات منه. بدون هذا الإذن، لن يتمكن السكريبت من الوصول إلى البيانات.

الخطوة 2: إعداد بيئة بايثون

قم بتثبيت المكتبات اللازمة باستخدام pip:

pip install google-api-python-client pandas

الخطوة 3: كتابة كود بايثون

سنقوم بإنشاء سكريبت بايثون لاستخراج البيانات. تأكد من استبدال 'service_account.json' بمسار ملف بيانات الاعتماد الخاص بك إذا لم يكن في نفس مجلد السكريبت، و 'https://www.example.com/' بعنوان URL لموقعك في Search Console (يجب أن ينتهي بـ /).

import os
from google.oauth2 import service_account
from googleapiclient.discovery import build
import pandas as pd
from datetime import datetime, timedelta

# --- الإعدادات --- 
SERVICE_ACCOUNT_FILE = 'service_account.json' # تأكد من أن هذا الملف في نفس مجلد السكريبت أو حدد المسار الكامل
SITE_URL = 'https://www.example.com/' # استبدل بعنوان URL لموقعك في Search Console (يجب أن ينتهي بـ '/')
# استخراج بيانات آخر 90 يومًا. يمكن تعديلها لتاريخ محدد (مثلاً: START_DATE = '2023-01-01').
START_DATE = (datetime.now() - timedelta(days=90)).strftime('%Y-%m-%d')
END_DATE = datetime.now().strftime('%Y-%m-%d')
OUTPUT_FILE = 'search_console_keywords.csv'

# --- المصادقة --- 
try:
    credentials = service_account.Credentials.from_service_account_file(
        SERVICE_ACCOUNT_FILE,
        scopes=['https://www.googleapis.com/auth/webmasters.readonly']
    )
    # بناء خدمة Search Console API
    service = build('webmasters', 'v3', credentials=credentials)
    print("تمت المصادقة بنجاح على Google Search Console API.")
except Exception as e:
    print(f"خطأ في المصادقة: {e}")
    print("يرجى التأكد من أن ملف 'service_account.json' موجود وصحيح، وأن حساب الخدمة لديه الأذونات اللازمة.")
    exit()

# --- استخراج البيانات --- 
def get_search_console_data(site_url, start_date, end_date):
    """
    يستخرج بيانات أداء البحث (الكلمات المفتاحية والصفحات) من Google Search Console.
    """
    search_request = {
        'startDate': start_date,
        'endDate': end_date,
        'dimensions': ['query', 'page'], # يمكن أن تكون query, page, device, country
        'rowLimit': 25000, # الحد الأقصى للصفوف لكل طلب في Search Console API
        'startRow': 0
    }
    
    all_rows = []
    has_more_data = True
    
    print(f"بدء استخراج البيانات للموقع: {site_url} من {start_date} إلى {end_date}")

    while has_more_data:
        try:
            # تنفيذ الطلب
            response = service.searchanalytics().query(siteUrl=site_url, body=search_request).execute()
            rows = response.get('rows', [])
            
            if rows:
                all_rows.extend(rows)
                # تحديث startRow لطلب الدفعة التالية
                search_request['startRow'] += len(rows)
                print(f"تم استخراج {len(all_rows)} صف حتى الآن...")
                
                # إذا كانت الدفعة المستلمة أقل من الحد الأقصى، فهذا يعني أننا وصلنا إلى النهاية
                if len(rows) < search_request['rowLimit']:
                    has_more_data = False
            else:
                # لا توجد المزيد من الصفوف
                has_more_data = False

        except Exception as e:
            print(f"خطأ أثناء استخراج البيانات: {e}")
            print("قد يكون السبب هو تجاوز حصة API اليومية، أو مشكلة في إعدادات الموقع/الأذونات.")
            has_more_data = False # إيقاف الاستخراج عند حدوث خطأ
            
    return all_rows

# --- تنفيذ السكريبت --- 
data = get_search_console_data(SITE_URL, START_DATE, END_DATE)

if data:
    # تحويل البيانات إلى DataFrame
    # لاحظ أن كل صف في 'data' هو قائمة من القيم، وليس قاموساً
    # [ [query, page], clicks, impressions, ctr, position ]
    df = pd.DataFrame(data)
    
    # إعادة تسمية الأعمدة لتكون أكثر وضوحًا
    # الأعمدة الافتراضية بعد التحويل هي 0, 1, 2, 3, 4
    df.columns = ['keys', 'clicks', 'impressions', 'ctr', 'position']
    
    # فصل الكلمات المفتاحية والصفحات من عمود 'keys' (الذي هو قائمة)
    df['query'] = df['keys'].apply(lambda x: x[0])
    df['page'] = df['keys'].apply(lambda x: x[1])
    df.drop(columns=['keys'], inplace=True) # إزالة عمود المفاتيح الأصلي
    
    # ترتيب الأعمدة لسهولة القراءة
    df = df[['query', 'page', 'clicks', 'impressions', 'ctr', 'position']]
    
    # حفظ البيانات في ملف CSV
    df.to_csv(OUTPUT_FILE, index=False, encoding='utf-8-sig')
    print(f"\nتم استخراج {len(df)} صفًا بنجاح وحفظها في {OUTPUT_FILE}")
else:
    print("لم يتم العثور على بيانات أو حدث خطأ أثناء الاستخراج.")

النتيجة النهائية المتوقعة

بعد إعداد مشروع Google Cloud Platform بشكل صحيح وتشغيل سكريبت بايثون، ستحصل على ملف CSV باسم search_console_keywords.csv (أو الاسم الذي حددته) في نفس مجلد السكريبت. سيحتوي هذا الملف على آلاف (أو حتى عشرات الآلاف) من الكلمات المفتاحية التي يظهر بها موقعك في نتائج بحث Google، بالإضافة إلى بيانات الأداء لكل كلمة مفتاحية وصفحة مثل النقرات، مرات الظهور، نسبة النقر إلى الظهور (CTR)، ومتوسط الموضع. يمكنك بعد ذلك استخدام هذا الملف لتحليل أداء SEO، تحديد فرص الكلمات المفتاحية، ومراقبة التغييرات في رؤية موقعك بشكل فعال، مما يسهل اتخاذ قرارات مبنية على البيانات لتحسين استراتيجية المحتوى والروابط الداخلية.

← السابقالفهرسالتالي →