Search Analytics: query

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

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

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

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

اطّلِع على نموذج 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
        }
      ],
      "filterLists": [
        {
          "dimension": string,
          "expressions": [
            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 بالإضافة إلى "التاريخ" و "الساعة". يتم دمج قيم سمات التجميع لإنشاء مفتاح فريد لكل صف نتائج. في حال عدم تحديد أي سمات، سيتم دمج جميع القيم في صف واحد. ما مِن حدّ أقصى لعدد السمات التي يمكنك التجميع حسبها، ولكن لا يمكنك التجميع حسب السمة نفسها مرّتين. مثال: [country, device]
searchType string تم إيقاف هذه السياسة نهائيًا، لذا يُرجى استخدام سياسة type بدلاً منها
type string [اختياري] فلترة النتائج حسب النوع التالي:
  • "discover": نتائج "اقتراحات"
  • ‫"googleNews": النتائج من news.google.com وتطبيق "أخبار Google" على أجهزة Android وiOS لا يشمل النتائج من علامة التبويب "الأخبار" في "بحث Google".
  • ‫"news": نتائج البحث من علامة التبويب "الأخبار" في "بحث Google"
  • ‫"image": نتائج البحث من علامة التبويب "الصورة" في "بحث Google"
  • "video": نتائج البحث عن الفيديوهات
  • ‫"web": [تلقائي] تتم فلترة النتائج لتظهر في علامة التبويب المجمّعة ("الكل") في "بحث Google". لا يشمل ذلك نتائج ميزة "اقتراحات" أو "أخبار Google".
  • ‫"webMultimodal": نتائج البحث من "عدسة Google" وميزة "دائرة البحث" على أجهزة Android وعمليات تحميل الصور في "بحث 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": لفلترة النتائج حسب نوع الجهاز المحدّد القيم المسموح بها:
    • أجهزة الكمبيوتر المكتبي
    • MOBILE
    • TABLET
  • ‫"page": فلترة حسب سلسلة معرّف الموارد المنتظم (URI) المحدّدة
  • "query": فلترة النتائج حسب سلسلة طلب البحث المحدّدة
  • ‫"searchAppearance": للفلترة حسب ميزة معيّنة في نتائج البحث للاطّلاع على قائمة بالقيم المتاحة، نفِّذ طلب بحث مجمّعًا حسب "searchAppearance". تتوفّر أيضًا القائمة الكاملة للقيم والأوصاف في مستندات المساعدة.
  • ‫"brandedClassification": لفلترة النتائج حسب تصنيف طلب البحث المحدّد الذي يذكر علامة تجارية (يتوفّر عامل التشغيل "equals" فقط) لا يمكن الجمع بين الفلترة أو التجميع حسب "brandedClassification" وفلتر "query" في الطلب نفسه. تتوفّر البيانات اعتبارًا من 21 فبراير 2026، وفقط للمواقع الإلكترونية ذات المستوى الأعلى التي تتلقّى عددًا كافيًا من طلبات البحث ومرات الظهور (راجِع الإشعار المتعلّق بطلبات البحث التي تذكر علامة تجارية). القيم المسموح بها:
    • BRANDED
    • NON_BRANDED
dimensionFilterGroups[].filters[].operator string [اختياري] كيف يجب أن تتطابق القيمة المحدّدة (أو لا تتطابق) مع قيمة السمة للصف.

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

القيم المقبولة هي:
  • ‫"country": للفلترة حسب البلدان المحدّدة، باستخدام رموز البلدان المكوّنة من 3 أحرف (ISO 3166-1 alpha-3).
  • ‫"device": الفلترة حسب أنواع الأجهزة المحدّدة (DESKTOP وMOBILE وTABLET).
dimensionFilterGroups[].filterLists[].expressions[] list [مطلوب] قائمة القيم (string) التي تريد الفلترة وفقًا لها.
aggregationType string

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

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

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

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

الردّ

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

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

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