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
}
اسم الموقع القيمة الوصف ملاحظات
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 إلى جانب "التاريخ".يتمّ دمج قيم أبعاد التجميع لإنشاء مفتاح فريد لكل صف نتيجة. إذا لم يتم تحديد أي سمات، سيتم دمج كل القيم في صف واحد. ما مِن حدّ أقصى لعدد السمات التي يمكنك التجميع وفقًا لها، ولكن لا يمكنك التجميع حسب السمة نفسها مرّتين. مثال: [البلد، الجهاز]
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

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

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

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

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

الرد

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

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

يمكنك الاطّلاع على السمة 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": تم تجميع النتائج حسب الموقع الإلكتروني.

جرّب الآن

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