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، حسب توقيت المحيط الهادئ (UTC - 7:00/8:00). يجب أن يكون تاريخ البدء أقل من تاريخ الانتهاء أو مساويًا له. يتم تضمين هذه القيمة في النطاق.
endDate string [مطلوبة] تاريخ الانتهاء للنطاق الزمني المطلوب، بالتنسيق YYYY-MM-DD، حسب توقيت المحيط الهادئ (UTC - 7:00/8:00) يجب أن يكون تاريخ الانتهاء أكبر من تاريخ البدء أو مساويًا له. يتم تضمين هذه القيمة في النطاق.
dimensions[] list [اختيارية] صفر من السمات أو أكثر لتجميع النتائج حسبها يتم تجميع النتائج بالترتيب الذي تقدّم به هذه السمات.يمكنك استخدام أي اسم سمة في dimensionFilterGroups[].filters[].dimension بالإضافة إلى "date" و "hour". يتم دمج قيم سمات التجميع لإنشاء مفتاح فريد لكل صف من صفوف النتائج. إذا لم يتم تحديد أي سمات، سيتم دمج جميع القيم في صف واحد. ما مِن حدّ أقصى لعدد السمات التي يمكنك التجميع حسبها، ولكن لا يمكنك التجميع حسب السمة نفسها مرّتين. مثال: [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")، أو أن يعرض فلتر واحد أو أكثر القيمة "صحيح" (غير متاح بعد)

القيم المقبولة هي:
  • "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
    • MOBILE
    • TABLET
  • ‫"page": الفلترة حسب سلسلة URI المحدّدة
  • ‫"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": تجميع القيم حسب عنوان URI
  • ‫"byProperty": تجميع القيم حسب الموقع الإلكتروني غير متاح لـ type=discover أو type=googleNews
rowLimit integer [اختياري: النطاق الصالح هو من 1 إلى 25,000، والقيمة التلقائية هي 1,000] الحدّ الأقصى لعدد الصفوف المطلوب عرضها للانتقال بين صفحات النتائج، استخدِم الإزاحة startRow.
startRow integer [اختياري: القيمة التلقائية هي 0] الفهرس المستند إلى الصفر للصف الأول في الردّ يجب أن يكون رقمًا غير سالب. إذا كان startRow يتجاوز عدد نتائج طلب البحث، سيكون الردّ ناجحًا بدون أي صفوف.
dataState string [اختيارية] إذا كانت القيمة "all" (غير حساسة لحالة الأحرف)، ستشمل البيانات بيانات جديدة. إذا كانت القيمة "final" (غير حساسة لحالة الأحرف) أو إذا تم حذف هذه المَعلمة، ستشمل البيانات المعروضة البيانات النهائية فقط. إذا كانت القيمة "hourly_all" (غير حساسة لحالة الأحرف)، ستشمل البيانات تفصيلاً بالساعة. سيشير ذلك إلى أنّ البيانات الخاصة بكل ساعة تتضمّن بيانات جزئية ويجب استخدامها عند التجميع حسب سمة الساعة في واجهة برمجة التطبيقات.

الردّ

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

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

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

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

عند طلب بيانات حديثة (باستخدام all أو hourly_all لـ dataState)، قد تمثّل بعض الصفوف المعروضة بيانات غير مكتملة، ما يعني أنّه لا يزال يتم جمع البيانات ومعالجتها. يساعدك كائن البيانات الوصفية هذا في تحديد وقت بدء ذلك وانتهائه بالضبط.

تظهر جميع التواريخ والأوقات المقدَّمة في هذا الكائن في المنطقة الزمنية America/Los_Angeles

يعتمد الحقل المحدّد الذي يتم عرضه ضمن هذا الكائن على كيفية تجميع بياناتك في الطلب:

  • first_incomplete_date (string): أول تاريخ لا يزال يتم جمع البيانات ومعالجتها له، ويتم عرضه بالتنسيق YYYY-MM-DD (تنسيق التاريخ المحلي الممتد ISO-8601).

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

    قد تظل جميع القيم بعد first_incomplete_date تتغيّر بشكل ملحوظ.

  • first_incomplete_hour (string): أول ساعة لا يزال يتم جمع البيانات ومعالجتها لها، ويتم عرضها بالتنسيق YYYY-MM-DDThh:mm:ss[+|-]hh:mm (تنسيق التاريخ والوقت الممتد مع الإزاحة ISO-8601).

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

    قد تظل جميع القيم بعد first_incomplete_hour تتغيّر بشكل ملحوظ.

جرِّبها الآن.

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