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

القيم المقبولة هي:
  • "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": الفلترة حسب ميزة محدّدة من نتائج البحث لعرض قائمة بالقيم المتاحة، شغِّل طلب بحث مجمّعًا حسب "شكل الظهور في البحث".
dimensionFilterGroups[].filters[].operator string [اختياري] كيفية مطابقة القيمة المحدّدة (أو عدم المطابقة) لقيمة السمة للصف.

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

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

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

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

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

الإجابة

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

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

يمكنك الاطّلاع على السمة 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 نسبة النقر إلى الظهور (CTR) للصف. تتراوح القيم من 0 إلى 1.0، بما في ذلك القيم الواقعة بينهما.
rows[].position double متوسط موضع الإعلان في نتائج البحث.
responseAggregationType string كيفية تجميع النتائج.اطّلِع على مستندات المساعدة للتعرُّف على كيفية حساب البيانات بشكلٍ مختلف حسب الموقع الإلكتروني مقارنةً بالصفحة.

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

جرِّب هذه الميزة الآن.

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