Search Analytics: query

يتطلّب تفويضًا

يمكنك طلب بيانات زيارات البحث باستخدام الفلاتر والمَعلمات التي تحدّدها. تعرض الطريقة صفر صف أو أكثر مجمّعة حسب مفاتيح الصفوف (السمات) التي تحدّدها. يجب تحديد نطاق زمني يتضمّن يومًا واحدًا أو أكثر.

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

يتم ترتيب النتائج حسب عدد النقرات تنازليًا. إذا كان لصفَين عدد النقرات نفسه، يتم ترتيبهما بطريقة عشوائية.

يمكنك الاطّلاع على نموذج Python لاستدعاء هذه الطريقة.

تخضع واجهة برمجة التطبيقات لقيود داخلية في Search Console، ولا تضمن عرض جميع صفوف البيانات، بل أهمها.

الاطّلاع على حدود كمية البيانات المتاحة

مثال على طلب POST بتنسيق JSON: 
POST https://www.googleapis.com/webmasters/v3/sites/https%3A%2F%2Fwww.example.com%2F/searchAnalytics/query?key={MY_API_KEY}
{
  "startDate": "2015-04-01",
  "endDate": "2015-05-01",
  "dimensions": ["country","device"]
}
جرِّبها الآن.

طلب

طلب HTTP

POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query

المعلمات

اسم المعلَمة القيمة الوصف
مَعلمات المسار
siteUrl string عنوان URL للموقع الإلكتروني على النحو المحدّد في Search Console أمثلة: http://www.example.com/ (لموقع إلكتروني يحمل بادئة عنوان URL) أو sc-domain:example.com (لموقع إلكتروني في نطاق)

التفويض

يتطلّب هذا الطلب الحصول على إذن باستخدام نطاق واحد على الأقل من النطاقات التالية (مزيد من المعلومات حول المصادقة ومنح الإذن).

النطاق
https://www.googleapis.com/auth/webmasters.readonly
https://www.googleapis.com/auth/webmasters

نص الطلب

في نص الطلب، قدِّم بيانات بالبنية التالية:

{
  "startDate": string,
  "endDate": string,
  "dimensions": [
    string
  ],
  "type": string,
  "dimensionFilterGroups": [
    {
      "groupType": string,
      "filters": [
        {
          "dimension": string,
          "operator": string,
          "expression": string
        }
      ]
    }
  ],
  "aggregationType": string,
  "rowLimit": integer,
  "startRow": integer
}
اسم السمة القيمة الوصف ملاحظات
startDate string [مطلوب] تاريخ بدء النطاق الزمني المطلوب، بالتنسيق YYYY-MM-DD، بتوقيت المحيط الهادئ (UTC - 7:00/8:00) يجب أن يكون أقل من أو يساوي تاريخ الانتهاء. يتم تضمين هذه القيمة في النطاق.
endDate string [مطلوبة] تاريخ انتهاء النطاق الزمني المطلوب، بالتنسيق YYYY-MM-DD، بتوقيت المحيط الهادئ (التوقيت العالمي المتفق عليه - 7:00/8:00). يجب أن يكون تاريخ الانتهاء أكبر من تاريخ البدء أو مساويًا له. يتم تضمين هذه القيمة في النطاق.
dimensions[] list [اختياري] صفر أو أكثر من السمات لتجميع النتائج حسبها. يتم تجميع النتائج بالترتيب الذي تقدّم به هذه السمات. يمكنك استخدام أي اسم سمة في dimensionFilterGroups[].filters[].dimension بالإضافة إلى "التاريخ" و "الساعة". يتمّ دمج قيم سمة التجميع لإنشاء مفتاح فريد لكلّ صفّ من صفوف النتائج. في حال عدم تحديد أي سمات، سيتم دمج جميع القيم في صف واحد. ليس هناك حدّ أقصى لعدد السمات التي يمكنك تجميعها حسبها، ولكن لا يمكنك التجميع حسب السمة نفسها مرّتين. مثال: [البلد، الجهاز]
searchType string تم إيقاف هذه السمة نهائيًا، يُرجى استخدام type بدلاً منها
type string [اختياري] فلترة النتائج حسب النوع التالي:
  • "discover": نتائج "اقتراحات"
  • ‫"googleNews": نتائج من news.google.com وتطبيق "أخبار Google" على أجهزة Android وiOS لا يشمل نتائج من علامة التبويب "الأخبار" في "بحث Google".
  • "news": نتائج البحث من علامة التبويب "الأخبار" في "بحث Google"
  • "image": نتائج البحث من علامة التبويب "الصورة" في "بحث Google"
  • "video": نتائج البحث عن الفيديوهات
  • "web": [تلقائي] لفلترة النتائج إلى علامة التبويب المجمّعة ("الكل") في "بحث Google" لا يشمل نتائج "اقتراحات" أو "أخبار Google".
dimensionFilterGroups[] list [اختياري] صفر أو أكثر من مجموعات الفلاتر التي سيتم تطبيقها على قيم تجميع السمات. يجب أن تتطابق جميع مجموعات الفلاتر لكي يتم عرض صف في الردّ. ضمن مجموعة فلاتر واحدة، يمكنك تحديد ما إذا كان يجب أن تتطابق جميع الفلاتر، أو يجب أن يتطابق فلتر واحد على الأقل.
dimensionFilterGroups[].groupType string تحديد ما إذا كان يجب أن تعرض جميع الفلاتر في هذه المجموعة القيمة "صحيح" (and)، أو ما إذا كان يجب أن تعرض قيمة واحدة أو أكثر القيمة "صحيح" (غير متاح بعد).

القيم المقبولة هي:
  • "and": يجب أن تعرض جميع الفلاتر في المجموعة القيمة "صحيح" لكي تكون مجموعة الفلاتر صحيحة.
dimensionFilterGroups[].filters[] list [اختياري] صفر أو أكثر من الفلاتر لاختبار الصف. يتكوّن كل فلتر من اسم سمة وعامل تشغيل وقيمة. الحد الأقصى للطول هو 4096 حرفًا. أمثلة: 
country equals FRA
query contains mobile use
device notContains tablet
dimensionFilterGroups[].filters[].dimension string السمة التي ينطبق عليها هذا الفلتر. يمكنك الفلترة حسب أي سمة مُدرَجة هنا، حتى إذا لم تكن تُجري تجميعًا حسب تلك السمة.

القيم المقبولة هي:
  • استخدِم "country": للفلترة حسب البلد المحدّد، كما هو محدّد برمز البلد المكوّن من 3 أحرف (ISO 3166-1 alpha-3).
  • استبدِل device بفلترة النتائج حسب نوع الجهاز المحدّد. القيم المسموح بها:
    • الكمبيوتر
    • MOBILE
    • TABLET
  • استبدِل page بفلتر مقابل سلسلة URI المحدّدة.
  • استبدِل query بفلتر مقابل سلسلة طلب البحث المحدّدة.
  • استبدِل searchAppearance بفلتر للبحث عن ميزة محدّدة من ميزات نتائج البحث. للاطّلاع على قائمة بالقيم المتاحة، نفِّذ طلب بحث مجمّعًا حسب "searchAppearance". تتوفّر أيضًا القائمة الكاملة بالقيم والأوصاف في مستندات المساعدة.
dimensionFilterGroups[].filters[].operator string [اختياري] طريقة مطابقة القيمة المحدّدة (أو عدم مطابقتها) لقيمة السمة في الصف

القيم المقبولة هي:
  • "contains": يجب أن تحتوي قيمة الصف على التعبير أو أن تكون مساوية له (غير حساسة لحالة الأحرف).
  • "equals": [القيمة التلقائية] يجب أن يكون التعبير مساويًا تمامًا لقيمة الصف (مع مراعاة حالة الأحرف بالنسبة إلى سمات الصفحة وطلب البحث).
  • ‫"notContains": يجب ألا تحتوي قيمة الصف على عبارتك كجزء من سلسلة أو كمطابقة كاملة (غير حساسة لحالة الأحرف).
  • "notEquals": يجب ألا يكون التعبير مساويًا تمامًا لقيمة الصف (حساس لحالة الأحرف بالنسبة إلى سمات الصفحة وطلب البحث).
  • ‫"includingRegex": تعبير عادي بصيغة RE2 يجب مطابقته.
  • ‫"excludingRegex": تعبير عادي بصيغة RE2 يجب عدم مطابقته.
dimensionFilterGroups[].filters[].expression string القيمة التي يجب أن يطابقها الفلتر أو يستبعدها، وذلك حسب عامل التشغيل
aggregationType string

[اختياري] كيفية تجميع البيانات في حال التجميع حسب الموقع، يتم تجميع كل البيانات الخاصة بالموقع نفسه. أما في حال التجميع حسب الصفحة، فيتم تجميع كل البيانات حسب معرّف الموارد المنتظم الأساسي. إذا كنت تريد الفلترة أو التجميع حسب الصفحة، اختَر "تلقائي"، وإلا يمكنك التجميع حسب الموقع الإلكتروني أو حسب الصفحة، وذلك استنادًا إلى الطريقة التي تريد احتساب بياناتك بها. يمكنك الاطّلاع على مستندات المساعدة لمعرفة كيف يتم احتساب البيانات بشكل مختلف حسب الموقع الإلكتروني مقارنةً بالصفحة.

ملاحظة: إذا كنت تُجمّع أو تفلتر حسب الصفحة، لا يمكنك التجميع حسب الموقع.

إذا حدّدت أي قيمة أخرى غير "تلقائي"، سيتطابق نوع التجميع في النتيجة مع النوع المطلوب، أو ستتلقّى رسالة خطأ إذا طلبت نوعًا غير صالح. لن تغيّر واجهة برمجة التطبيقات نوع التجميع أبدًا إذا كان النوع المطلوب غير صالح.

القيم المقبولة هي:
  • "auto": [تلقائي] السماح للخدمة بتحديد نوع التجميع المناسب.
  • "byNewsShowcasePanel": تجميع القيم حسب لوحة "مختارات الأخبار" يجب استخدام هذا الفلتر مع الفلتر NEWS_SHOWCASE searchAppearance وإما type=discover أو type=googleNews. إذا كنت تصنّف حسب الصفحة أو تفلتر حسب الصفحة أو تفلتر إلى searchAppearance آخر، لا يمكنك التجميع حسب byNewsShowcasePanel.
  • "byPage": تجميع القيم حسب معرّف الموارد المنتظم (URI).
  • "byProperty": تجميع القيم حسب الموقع. غير متاح لـ type=discover أو type=googleNews
rowLimit integer [اختياري؛ النطاق الصالح هو 1–25,000؛ القيمة التلقائية هي 1,000] الحد الأقصى لعدد الصفوف المطلوب عرضها. للتنقّل بين صفحات النتائج، استخدِم الإزاحة startRow.
startRow integer [اختياري؛ القيمة التلقائية هي 0] فهرس مستند إلى الصفر للصف الأول في الردّ. يجب أن يكون رقمًا غير سالب. إذا كان startRow يتجاوز عدد النتائج لطلب البحث، سيكون الردّ ردًا ناجحًا بدون صفوف.
dataState string [اختياري] إذا كانت القيمة "all" (غير حساسة لحالة الأحرف)، ستتضمّن البيانات بيانات حديثة. إذا كانت القيمة هي "final" (غير حساسة لحالة الأحرف) أو إذا تم حذف هذه المَعلمة، ستتضمّن البيانات التي يتم إرجاعها البيانات النهائية فقط. إذا كانت القيمة هي "hourly_all" (غير حساسة لحالة الأحرف)، ستتضمّن البيانات تفصيلاً لكل ساعة. سيشير ذلك إلى أنّ البيانات الخاصة بكل ساعة تتضمّن بيانات جزئية ويجب استخدامها عند التجميع حسب سمة الساعة في واجهة برمجة التطبيقات.

الردّ

يتم تجميع النتائج وفقًا للسمات المحدّدة في الطلب. سيتم تجميع جميع القيم التي تتضمّن المجموعة نفسها من قيم السمات في صف واحد. على سبيل المثال، إذا كنت تصنّف حسب سمة البلد، سيتم تجميع كل النتائج الخاصة بـ "الولايات المتحدة الأمريكية" معًا، وكل النتائج الخاصة بـ "جزر المالديف" معًا، وهكذا. إذا تم التجميع حسب البلد والجهاز، سيتم تجميع جميع النتائج الخاصة بـ "الولايات المتحدة الأمريكية، جهاز لوحي"، وجميع النتائج الخاصة بـ "الولايات المتحدة الأمريكية، جهاز جوّال"، وهكذا. راجِع مستندات تقرير "إحصاءات البحث" للتعرّف على تفاصيل طريقة احتساب النقرات ومرات الظهور وما إلى ذلك، ومعرفة معناها.

يتم ترتيب النتائج حسب عدد النقرات، بترتيب تنازلي، ما لم يتم التجميع حسب التاريخ، وفي هذه الحالة يتم ترتيب النتائج حسب التاريخ، بترتيب تصاعدي (الأقدم أولاً، والأحدث آخرًا). في حال تساوي قيمتَي صفَّين، يكون ترتيب الفرز اختياريًا.

راجِع السمة rowLimit في الطلب للتعرّف على الحدّ الأقصى لعدد القيم التي يمكن عرضها.

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
اسم السمة القيمة الوصف ملاحظات
rows[] list قائمة بالصفوف مجمّعة حسب القيم الرئيسية بالترتيب الوارد في طلب البحث
rows[].keys[] list قائمة بقيم السمة لهذا الصف، ويتم تجميعها وفقًا للسمات الواردة في الطلب، وبالترتيب المحدّد في الطلب.
rows[].clicks double انقر على عدد الصفوف.
rows[].impressions double عدد مرّات الظهور للصف
rows[].ctr double نسبة النقر إلى الظهور للصف تتراوح القيم من 0 إلى 1.0، بما في ذلك هذين الرقمَين.
rows[].position double متوسط موضع الإعلان في نتائج البحث
responseAggregationType string كيف تم تجميع النتائج اطّلِع على مستندات المساعدة للتعرّف على كيفية احتساب البيانات بشكل مختلف حسب الموقع الإلكتروني مقارنةً باحتسابها حسب الصفحة.

القيم المقبولة هي:
  • "auto"
  • "byPage": تم تجميع النتائج حسب الصفحة.
  • "byProperty": تم تجميع النتائج حسب الموقع الإلكتروني.
metadata object

عنصر يمكن إرجاعه مع نتائج طلب البحث، ويوفّر سياقًا حول حالة البيانات.

عند طلب بيانات حديثة (باستخدام all أو hourly_all في dataState)، قد تمثّل بعض الصفوف التي يتم عرضها بيانات غير مكتملة، ما يعني أنّه لا يزال يتم جمع البيانات ومعالجتها. يساعدك عنصر البيانات الوصفية هذا في تحديد وقت بدء هذا الحدث وانتهائه بدقة.

جميع التواريخ والأوقات الواردة في هذا العنصر تكون بتوقيت المنطقة الزمنية America/Los_Angeles.

يعتمد الحقل المحدّد الذي يتم عرضه ضمن هذا العنصر على طريقة تجميع البيانات في الطلب:

  • ‫first_incomplete_date (string): تمثّل هذه السمة أول تاريخ لا يزال يتم فيه جمع البيانات ومعالجتها، ويتم عرضها بالتنسيق YYYY-MM-DD (تنسيق التاريخ المحلي الموسّع ISO-8601).

    لا تتم تعبئة هذا الحقل إلا عندما تكون قيمة dataState في الطلب هي all ويتم تجميع البيانات حسب date، ويتضمّن النطاق الزمني المطلوب نقاط بيانات غير مكتملة.

    قد تتغيّر جميع القيم بعد first_incomplete_date بشكل ملحوظ.

  • first_incomplete_hour (string): تمثّل هذه السمة الساعة الأولى التي لا يزال يتم فيها جمع البيانات ومعالجتها، ويتم عرضها بالتنسيق YYYY-MM-DDThh:mm:ss[+|-]hh:mm (تنسيق ISO-8601 الموسّع لتاريخ ووقت الإزاحة).

    لا تتم تعبئة هذا الحقل إلا عندما تكون قيمة dataState في الطلب هي hourly_all، ويتم تجميع البيانات حسب hour، ويحتوي النطاق الزمني المطلوب على نقاط بيانات غير مكتملة.

    قد تتغيّر جميع القيم بعد first_incomplete_hour بشكل ملحوظ.

جرِّبها الآن.

استخدِم "مستكشف واجهات برمجة التطبيقات" أدناه لطلب البيانات من خلال هذه الطريقة والاطّلاع على الردّ.