Search Analytics: query

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

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

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

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

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

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

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

مثال على طلب POST بتنسيق 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
}
اسم الموقع القيمة الوصف ملاحظات
startDate string [مطلوبة] تاريخ بدء النطاق الزمني المطلوب، بالتنسيق YYYY-MM-DD، بالتوقيت البرتغالي (التوقيت العالمي المنسق - 7:00/8:00) يجب أن يكون تاريخ البدء أقل من أو يساوي تاريخ الانتهاء. يتم تضمين هذه القيمة في النطاق.
endDate string [مطلوبة] تاريخ انتهاء النطاق الزمني المطلوب، بالتنسيق YYYY-MM-DD، بالتوقيت البرتغالي (التوقيت العالمي المنسق - 7:00/8:00). يجب أن يكون تاريخ البدء أكبر من أو يساويه. ويتم تضمين هذه القيمة في النطاق.
dimensions[] list [اختياري] سمات صفرية أو أكثر لتجميع النتائج حسبها يتم تجميع النتائج بالترتيب الذي تقدّم به هذه السمات. يمكنك استخدام أيّ اسم سمة في dimensionFilterGroups[].filters[].dimension بالإضافة إلى "date".يتم دمج قيم أبعاد التجميع لإنشاء مفتاح فريد لكل صف نتيجة. في حال عدم تحديد أيّ سمات، سيتمّ دمج جميع القيم في صفّ واحد. ما مِن حدّ أقصى لعدد السمات التي يمكنك التجميع وفقًا لها، ولكن لا يمكنك التجميع حسب السمة نفسها مرّتين. مثال: [country, device]
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": فلترة النتائج حسب نوع الجهاز المحدّد القيم المسموح بها:
    • DESKTOP
    • الأجهزة الجوّالة
    • جهاز لوحي
  • "page": الفلترة حسب سلسلة معرّف الموارد المتّصل المحدّدة
  • "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": تجميع القيم حسب عنوان URL
  • "byProperty": تجميع القيم حسب الموقع الإلكتروني هذه الميزة غير متاحة في type=discover أو type=googleNews.
rowLimit integer [اختياري، النطاق الصالح هو 1 إلى 25,000، والقيمة التلقائية هي 1,000] الحدّ الأقصى لعدد الصفوف المطلوب عرضها. للتنقّل بين النتائج، استخدِم الإزاحة startRow.
startRow integer [اختياري؛ الإعداد التلقائي هو 0] فهرس مستند إلى الصفر للصف الأول في الاستجابة. يجب أن يكون رقمًا غير سالب. إذا تجاوز startRow عدد نتائج طلب البحث، سيكون الردّ ناجحاً بدون أي صفوف.
dataState string [اختياري] إذا كانت القيمة "all" (لا تراعي حالة الأحرف)، ستتضمّن البيانات البيانات الجديدة. إذا كانت المعلَمة "final" (لا تراعي حالة الأحرف) أو إذا تم حذف هذه المعلَمة، لن تتضمّن البيانات المعروضة سوى البيانات النهائية.

الرد

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

جرّب الآن

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