به مجوز نیاز دارد
دادههای ترافیک جستجویتان را با فیلترها و پارامترهایی که تعریف میکنید پُرسمان کنید. این روش صفر یا چند ردیف را که براساس کلیدهای ردیف (ابعاد) تعریفشده توسط شما گروهبندی شدهاند برمیگرداند. باید محدوده تاریخی یک یا چند روزه تعریف کنید.
وقتی تاریخ یکی از ابعاد باشد، هر روزی که داده نداشته باشد از فهرست نتایج حذف میشود. برای اینکه بدانید کدام روزها داده دارند، پُرسمانی بدون فیلترهای گروهبندیشده براساس تاریخ برای محدوده تاریخ موردنظر صادر کنید.
نتایج براساس تعداد کلیک بهصورت نزولی مرتب شدهاند. اگر دو ردیف تعداد کلیک یکسانی داشته باشند، بهصورت دلخواه مرتب میشوند.
برای فراخوانی این روش، نمونه پایتون را ببینید.
این میانای برنامهسازی کاربردی با محدودیتهای داخلی 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 |
نشانی وب دارایی همانطور که در «کنسول جستجو» تعریف شده است. مثالها:
http://www.example.com/ (برای خصوصیت پیشوند نشانی وب) یا
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، در زمان PT (ساعت هماهنگ جهانی - 7:00/8:00). باید کمتر یا مساوی با تاریخ پایان باشد. این مقدار در محدوده گنجانده شده است. | |
endDate |
string |
[الزامی] تاریخ پایان محدوده تاریخ درخواستی، در قالب YYYY-MM-DD، در زمان PT (ساعت هماهنگ جهانی - 7:00/8:00). باید بزرگتر یا مساوی تاریخ شروع باشد. این مقدار در محدوده گنجانده شده است. | |
dimensions[] |
list |
[اختیاری] صفر یا چند بُعد برای گروهبندی نتایج. نتایج بهترتیبی که این ابعاد را ارائه میدهید گروهبندی میشوند. میتوانید از هر نام بُعدی در dimensionFilterGroups[].filters[].dimension و همچنین «تاریخ» و «ساعت» استفاده کنید. مقادیر بُعد گروهبندی ترکیب میشوند تا کلید یکتایی برای هر ردیف نتیجه ایجاد شود. اگر هیچ بُعدی مشخص نشده باشد، همه مقادیر در یک ردیف ترکیب خواهند شد. محدودیتی برای تعداد ابعادی که میتوانید براساس آنها گروهبندی کنید وجود ندارد، اما نمیتوانید براساس یک بعد دو بار گروهبندی کنید. مثال: [کشور، دستگاه] | |
searchType |
string |
منسوخ شده است، درعوض از type استفاده کنید
|
|
type |
string |
[اختیاری] نتایج را براساس نوع زیر فیلتر کنید:
|
|
dimensionFilterGroups[] |
list |
[اختیاری] صفر یا چند گروه فیلتر برای اعمال کردن روی مقادیر گروهبندی بُعد. همه گروههای فیلتر باید مطابقت داشته باشند تا ردیفی در پاسخ برگردانده شود. در یک گروه فیلتر، میتوانید مشخص کنید که همه فیلترها باید مطابقت داشته باشند یا حداقل یکی باید مطابقت داشته باشد. | |
dimensionFilterGroups[].groupType |
string |
اینکه آیا همه فیلترهای این گروه باید مقدار درست را برگردانند («و»)، یا یک یا چند فیلتر باید مقدار درست را برگردانند (هنوز پشتیبانی نمیشود).
مقادیر پذیرفتنی عبارتاند از:
|
|
dimensionFilterGroups[].filters[] |
list |
[اختیاری] صفر یا چند فیلتر برای آزمایش دربرابر ردیف. هر فیلتر شامل
نام بُعد، عملگر، و مقدار است. حداکثر طول ۴۰۹۶ نویسه. مثالها:
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 را انتخاب کنید؛ درغیراینصورت میتوانید براساس دارایی یا صفحه انبوهش کنید، بسته به اینکه میخواهید دادههایتان چگونه محاسبه شود؛ برای آشنایی با نحوه محاسبه متفاوت دادهها براساس سایت درمقابل صفحه، سند راهنما را ببینید. توجه: اگر براساس صفحه گروهبندی یا فیلتر کنید، نمیتوانید براساس دارایی تجمیع کنید. اگر هر مقداری بهغیراز auto را مشخص کنید، نوع انبوهش در نتیجه با نوع درخواستی مطابقت خواهد داشت، یا اگر نوع نامعتبری را درخواست کنید، خطا دریافت خواهید کرد. اگر نوع درخواستشده نامعتبر باشد، میانای برنامهسازی کاربردی هرگز نوع انبوهش شما را تغییر نخواهد داد. مقادیر پذیرفتنی عبارتاند از:
|
|
rowLimit |
integer |
[اختیاری؛ محدوده معتبر ۱ تا ۲۵٬۰۰۰ است؛ پیشفرض ۱٬۰۰۰ است] حداکثر تعداد ردیفها برای برگرداندن. برای ورق زدن نتایج، از افست startRow استفاده کنید. |
|
startRow |
integer |
[اختیاری؛ پیشفرض ۰ است] نمایه مبتنی بر صفر ردیف اول در پاسخ. باید عدد غیرمنفی باشد. اگر startRow از تعداد نتایج پُرسمان فراتر رود، پاسخ موفقیتآمیز با صفر ردیف خواهد بود. |
|
dataState |
string |
[اختیاری] اگر «همه» (غیرحساس به حروف بزرگ و کوچک) باشد، دادهها شامل دادههای جدید خواهد بود. اگر «final» (غیرحساس به حروف بزرگ و کوچک) باشد یا اگر این پارامتر حذف شود، دادههای برگرداندهشده فقط شامل دادههای نهاییشده خواهد بود. اگر «hourly_all» (غیرحساس به حروف بزرگ و کوچک) باشد، دادهها شامل تفکیک ساعتی خواهد بود. این نشان میدهد که دادههای ساعتی شامل دادههای جزئی است و باید هنگام گروهبندی براساس بُعد HOUR API استفاده شود. |
پاسخ
نتایج براساس ابعاد مشخصشده در درخواست گروهبندی میشوند. همه مقادیر با مجموعه یکسانی از مقادیر بُعد در یک ردیف گروهبندی خواهند شد. برای مثال، اگر براساس بُعد کشور گروهبندی کنید، همه نتایج مربوط به «usa» باهم گروهبندی میشوند، همه نتایج مربوط به «mdv» باهم گروهبندی میشوند، و غیره. اگر براساس کشور و دستگاه گروهبندی کرده باشید، همه نتایج مربوط به «ایالات متحده، رایانه لوحی» گروهبندی میشود، همه نتایج مربوط به «ایالات متحده، تلفن همراه» گروهبندی میشود، و غیره. برای آشنایی با جزئیات نحوه محاسبه کلیکها، ظهورها، و غیره و معنی آنها، سند گزارش Search Analytics را ببینید.
نتایج براساس تعداد کلیکها بهترتیب نزولی مرتب میشوند، مگراینکه براساس تاریخ گروهبندی کنید که دراینصورت نتایج براساس تاریخ بهترتیب صعودی مرتب میشوند (قدیمیترین در ابتدا، جدیدترین در انتها). اگر دو ردیف باهم برابر باشند، ترتیب مرتبسازی اختیاری است.
برای اطلاع از حداکثر تعداد مقادیری که میتوانند برگردانده شوند، ویژگی 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) برای ردیف. مقادیر از ۰ تا ۱٫۰ است و میتواند این دو عدد را نیز دربر بگیرد. | |
rows[].position |
double |
جایگاه میانگین در نتایج جستجو. | |
responseAggregationType |
string |
نحوه تجمیع نتایج. برای آشنایی با نحوه محاسبه متفاوت دادهها براساس سایت درمقابل صفحه،سند راهنما را ببینید.
مقادیر پذیرفتنی عبارتاند از:
|
|
metadata |
object |
شیئی که ممکن است با نتایج پُرسمان شما برگردانده شود و زمینهای درباره وضعیت دادهها ارائه دهد. وقتی دادههای اخیر را درخواست میکنید (بااستفاده از همه تاریخها و زمانهای ارائهشده در این شیء در منطقه زمانی فیلد خاصی که در این شیء برگردانده میشود به نحوه گروهبندی دادههایتان در درخواست بستگی دارد:
|
امتحان کنید!
از «کاوشگر میاناهای برنامهسازی کاربردی» زیر برای فراخوانی این روش در دادههای زنده و دیدن پاسخ استفاده کنید.