Search Analytics: query

يجب تقديم تفويض

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

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

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

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

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

معرفة حدود مقدار البيانات المتاحة.

مثال على JSON POST:
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
}
اسم الموقع القيمة الوصف Notes
startDate string [مطلوبة] تاريخ بدء النطاق الزمني المطلوب، بالتنسيق YYYY-MM-DD، بتوقيت المحيط الهادئ (UTC - 7:00/8:00). يجب أن يكون أقل من تاريخ الانتهاء أو مساويًا له. هذه القيمة مُدرَجة في النطاق.
endDate string [مطلوبة] تاريخ انتهاء النطاق الزمني المطلوب، بالتنسيق YYYY-MM-DD، بتوقيت المحيط الهادئ (UTC - 7:00/8:00). يجب أن يكون أكبر من تاريخ البدء أو مساويًا له. هذه القيمة مُدرَجة في النطاق.
dimensions[] list [اختياري] لا تتوفّر سمات أو أكثر لتجميع النتائج حسبها.يتم تجميع النتائج بالترتيب الذي تقدِّمه لهذه السمات.يمكنك استخدام أي اسم سمة في dimensionFilterGroups[].filters[].dimension بالإضافة إلى السمة "date".ويتم دمج قيم سمات التجميع لإنشاء مفتاح فريد لكل صف نتائج. إذا لم يتم تحديد أي سمات، سيتم دمج كل القيم في صف واحد. ما من حدّ أقصى لعدد السمات التي يمكنك التجميع حسبها، ولكن لا يمكنك التجميع حسب السمة نفسها مرّتين. مثال: [البلد، الجهاز]
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": يجب أن تعرض جميع الفلاتر في المجموعة true حتى تكون مجموعة الفلاتر صحيحة.
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": يتيح لك هذا الخيار فلترة النتائج حسب نوع الجهاز المحدَّد. القيم المسموح بها:
    • الكمبيوتر المكتبي
    • الأجهزة الجوّالة
    • جهاز لوحي
  • "page": الفلترة حسب سلسلة معرّف الموارد المنتظم (URI) المحدّدة
  • "query": الفلترة حسب سلسلة طلب البحث المحدّدة
  • "searchAppearance": يتيح لك هذا الخيار فلترة البيانات حسب ميزة معيّنة في نتائج البحث. للاطّلاع على قائمة القيم المتاحة، نفِّذ طلب بحث مجمّعًا حسب "searchالمظهر".
dimensionFilterGroups[].filters[].operator string [اختياري] كيف يجب أن تتطابق (أو لا تتطابق) القيمة المحدّدة مع قيمة السمة للصف.

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

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

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

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

القيم المقبولة هي:
  • "auto": [تلقائي] السماح للخدمة بتحديد نوع التجميع المناسب.
  • "byNewsShowcasePanel": يمكنك تجميع القيم حسب لوحة "مختارات الأخبار". ويجب استخدام هذا الإجراء مع الفلتر searchAppearance NEWS_SHOWCASE ومع 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 [اختياري] إذا كانت "الكل" (غير حساسة لحالة الأحرف)، ستتضمن البيانات بيانات حديثة. إذا كانت الحالة "Final" (غير حساسة لحالة الأحرف) أو إذا تم حذف هذه المَعلمة، لن تتضمّن البيانات المعروضة سوى البيانات النهائية.

الإجابة

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

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

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

{
  "rows": [
    {
      "keys": [
        string
      ],
      "clicks": double,
      "impressions": double,
      "ctr": double,
      "position": double
    }
  ],
  "responseAggregationType": string
}
اسم الموقع القيمة الوصف Notes
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": تم تجميع النتائج حسب الموقع الإلكتروني.

تجربة

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