Search Analytics: query

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

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

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

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

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

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

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

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

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

الإجابة

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

تجربة

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