Search Analytics: query

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

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

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

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

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

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

الإجابة

يتم تجميع النتائج وفقًا للسمات المحددة في الطلب. سيتم تجميع كل القيم التي لها المجموعة نفسها من قيم السمات في صف واحد. على سبيل المثال، في حال التجميع حسب سمة البلد، سيتم تجميع كل نتائج "USa" معًا، وسيتم تجميع كل نتائج "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": تم تجميع النتائج حسب الموقع الإلكتروني.

تجربة

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