يتطلب تفويضًا
يمكنك الاستعلام عن بيانات عدد الزيارات الواردة من "شبكة بحث Google" باستخدام فلاتر ومَعلمات تحدّدها أنت. تُنتج الطريقة صفًا واحدًا أو أكثر مجمّعًا حسب مفاتيح الصفوف (السمات) التي تحدّدها. يجب تحديد نطاق زمني يتألف من يوم واحد أو أكثر.
عندما يكون التاريخ أحد السمات، يتم حذف أي أيام لا تتضمّن بيانات من قائمة النتائج. لمعرفة الأيام التي تتضمّن بيانات، يمكنك إصدار طلب بحث بدون فلاتر مجمّعة حسب التاريخ، للنطاق الزمني الذي يهمّك.
يتم ترتيب النتائج تنازليًا حسب عدد النقرات. إذا كان هناك صفّان لهما عدد النقرات نفسه، يتم ترتيبهما بطريقة عشوائية.
اطّلِع على نموذج Python لاستدعاء هذه الطريقة.
تخضع واجهة برمجة التطبيقات لقيود داخلية في Search Console ولا تضمن عرض جميع صفوف البيانات، بل تعرض أهمها فقط.
الاطّلاع على حدود كمية البيانات المتاحة
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 |
[اختياري] فلترة النتائج حسب النوع التالي:
|
|
dimensionFilterGroups[] |
list |
[اختياري] صفر أو أكثر من مجموعات الفلاتر التي يتم تطبيقها على قيم تجميع السمات. يجب أن تتطابق جميع مجموعات الفلاتر لكي يتم عرض صف في الاستجابة. ضمن مجموعة فلاتر واحدة، يمكنك تحديد ما إذا كان يجب أن تتطابق جميع الفلاتر أو فلتر واحد على الأقل. | |
dimensionFilterGroups[].groupType |
string |
ما إذا كان يجب أن تعرض جميع الفلاتر في هذه المجموعة القيمة "صحيح" ("and")، أو يجب أن يعرض فلتر واحد أو أكثر القيمة "صحيح" (غير متاح بعد).
القيم المقبولة هي:
|
|
dimensionFilterGroups[].filters[] |
list |
[اختياري] صفر أو أكثر من الفلاتر لاختبارها على الصف. يتكوّن كل فلتر من اسم سمة وعامل تشغيل وقيمة. الحدّ الأقصى للطول هو 4096 حرفًا. أمثلة:
country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
البُعد الذي ينطبق عليه هذا الفلتر. يمكنك الفلترة حسب أي سمة مدرَجة هنا، حتى إذا لم تكن تجمع البيانات حسب تلك السمة.
القيم المقبولة هي:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[اختياري] كيف يجب أن تتطابق القيمة المحدّدة (أو لا تتطابق) مع قيمة السمة للصف.
القيم المقبولة هي:
|
|
dimensionFilterGroups[].filters[].expression |
string |
القيمة التي يجب أن يطابقها الفلتر أو يستبعدها، حسب عامل التشغيل. | |
dimensionFilterGroups[].filterLists[] |
list |
[اختياري] فلاتر سمات متعددة القيم بعدد صفر أو أكثر لاختبارها مقابل الصف.
على عكس filters[]، التي تطابق قيمة واحدة لكل إدخال، تتيح filterLists[] المطابقة مع قيم مطابقة تامة متعددة لسمة واحدة في فلتر واحد. يتطابق الصف مع قائمة الفلاتر إذا كانت قيمته للسمة dimension المحدّدة تساوي أيًا من قيم expressions المقدَّمة. يُرجى العِلم أنّه لا يمكن لطلب واحد فلترة السمة نفسها في كلّ من filters وfilterLists في الوقت نفسه. |
|
dimensionFilterGroups[].filterLists[].dimension |
string |
[مطلوبة] السمة التي تنطبق عليها قائمة الفلاتر هذه.
القيم المقبولة هي:
|
|
dimensionFilterGroups[].filterLists[].expressions[] |
list |
[مطلوب] قائمة القيم (string) التي تريد الفلترة وفقًا لها. |
|
aggregationType |
string |
[اختياري] كيفية تجميع البيانات إذا تم تجميع البيانات حسب الموقع الإلكتروني، يتم تجميع كل البيانات الخاصة بالموقع الإلكتروني نفسه. وإذا تم تجميعها حسب الصفحة، يتم تجميع كل البيانات حسب معرّف الموارد المنتظم (URI) الأساسي. إذا كنت تفلتر أو تجمّع حسب الصفحة، اختَر auto، وإلا يمكنك التجميع حسب الموقع الإلكتروني أو حسب الصفحة، وذلك استنادًا إلى الطريقة التي تريد بها احتساب بياناتك. يمكنك الاطّلاع على مستندات المساعدة لمعرفة كيفية احتساب البيانات بشكل مختلف حسب الموقع الإلكتروني مقارنةً بالصفحة. ملاحظة: إذا اخترت التجميع أو الفلترة حسب الصفحة، لا يمكنك التجميع حسب الموقع الإلكتروني. إذا حدّدت أي قيمة أخرى غير "تلقائي"، سيتطابق نوع التجميع في النتيجة مع النوع المطلوب، أو إذا طلبت نوعًا غير صالح، سيظهر لك خطأ. لن تغيّر واجهة برمجة التطبيقات نوع التجميع أبدًا إذا كان النوع المطلوب غير صالح. القيم المقبولة هي:
|
|
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 |
كيفية تجميع النتائج اطّلِع على مستندات المساعدة لمعرفة كيفية احتساب البيانات بشكل مختلف حسب الموقع الإلكتروني مقارنةً بالصفحة.
القيم المقبولة هي:
|
|
metadata |
object |
هو عنصر قد يتم عرضه مع نتائج طلب البحث، ويوفّر سياقًا حول حالة البيانات. عند طلب بيانات حديثة (باستخدام جميع التواريخ والأوقات المقدَّمة في هذا العنصر هي بتوقيت المنطقة الزمنية يعتمد الحقل المحدّد الذي يتم عرضه ضمن هذا العنصر على كيفية تجميع بياناتك في الطلب:
|
جرِّبها الآن.
يمكنك استخدام "مستكشف واجهات برمجة التطبيقات" أدناه لطلب هذه الطريقة على البيانات المباشرة والاطّلاع على الاستجابة.