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 بالإضافة إلى "تاريخ" و "ساعة". يتمّ دمج قيم سمة التجميع لإنشاء مفتاح فريد لكلّ صفّ من صفوف النتائج. في حال عدم تحديد أيّ سمات، سيتمّ دمج جميع القيم في صفّ واحد. ما مِن حدّ أقصى لعدد السمات التي يمكنك التجميع حسبها، ولكن لا يمكنك التجميع حسب السمة نفسها مرّتين. مثال: [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": الفلترة حسب البلد المحدّد، كما هو محدّد من خلال رمز البلد المكوّن من ثلاثة أحرف (ISO 3166-1 alpha-3)
  • "device": فلترة النتائج حسب نوع الجهاز المحدّد القيم المسموح بها:
    • كمبيوتر مكتبي
    • الأجهزة الجوّالة
    • جهاز لوحي
  • "page": الفلترة حسب سلسلة معرّف الموارد المتّصل المحدّدة
  • "query": فلترة حسب سلسلة طلب البحث المحدّدة
  • "searchAppearance": فلترة حسب ميزة محدّدة لنتيجة البحث للاطّلاع على قائمة بالقيم المتاحة، يمكنك تنفيذ طلب بحث مجمّع حسب "searchAppearance". تتوفّر أيضًا القائمة الكاملة للقيم والأوصاف في مستندات المساعدة.
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" (لا تراعي حالة الأحرف) أو إذا تم حذف هذه المَعلمة، لن تتضمّن البيانات المعروضة سوى البيانات النهائية. إذا كان الخيار "hourly_all" (غير حساس لحالة الأحرف)، ستتضمّن البيانات تفاصيل كل ساعة. سيشير ذلك إلى أنّ البيانات بالساعة تتضمّن بيانات جزئية ويجب استخدامها عند التجميع حسب سمة HOUR API.

الردّ

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