Cần có quyền uỷ quyền
Truy vấn dữ liệu lưu lượng truy cập tìm kiếm bằng các bộ lọc và tham số mà bạn xác định. Phương thức này trả về từ 0 hàng trở lên được bộ lọc nhóm theo khoá hàng (phương diện) mà bạn xác định. Bạn phải xác định phạm vi ngày gồm một hoặc nhiều ngày.
Khi ngày là một trong các phương diện, mọi ngày không có dữ liệu sẽ bị bỏ qua khỏi danh sách kết quả. Để biết ngày nào có dữ liệu, hãy đưa ra một truy vấn không có bộ lọc được nhóm theo ngày, cho phạm vi ngày mà bạn quan tâm.
Kết quả được sắp xếp theo số lượt nhấp giảm dần. Nếu hai hàng có cùng số lượt nhấp, thì các hàng đó sẽ được sắp xếp theo cách tuỳ ý.
Hãy xem mẫu Python để biết cách gọi phương thức này.
API này bị ràng buộc bởi các giới hạn nội bộ của Search Console và không đảm bảo trả về tất cả các hàng dữ liệu mà chỉ trả về các hàng dữ liệu hàng đầu.
Xem giới hạn về lượng dữ liệu có sẵn.
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"]
}Yêu cầu
Yêu cầu HTTP
POST https://www.googleapis.com/webmasters/v3/sites/siteUrl/searchAnalytics/query
Thông số
| Tên thông số | Giá trị | Mô tả |
|---|---|---|
| Tham số đường dẫn | ||
siteUrl |
string |
URL của tài sản như được xác định trong Search Console. Ví dụ:
http://www.example.com/ (đối với tài sản là URL có tiền tố được định sẵn) hoặc
sc-domain:example.com (đối với Tài sản miền)
|
Ủy quyền
Yêu cầu này cần được uỷ quyền với ít nhất một trong các phạm vi sau (đọc thêm về việc xác thực và uỷ quyền).
| Phạm vi |
|---|
https://www.googleapis.com/auth/webmasters.readonly |
https://www.googleapis.com/auth/webmasters |
Nội dung yêu cầu
Trong nội dung yêu cầu, hãy cung cấp dữ liệu có cấu trúc sau:
{
"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
}| Tên tài sản | Giá trị | Mô tả | Ghi chú |
|---|---|---|---|
startDate |
string |
[Bắt buộc] Ngày bắt đầu của phạm vi ngày được yêu cầu, theo định dạng YYYY-MM-DD, theo giờ PT (UTC - 7:00/8:00). Phải nhỏ hơn hoặc bằng ngày kết thúc. Giá trị này nằm trong dải ô. | |
endDate |
string |
[Bắt buộc] Ngày kết thúc của phạm vi ngày được yêu cầu, theo định dạng YYYY-MM-DD, theo giờ PT (UTC - 7:00/8:00). Phải lớn hơn hoặc bằng ngày bắt đầu. Giá trị này nằm trong dải ô. | |
dimensions[] |
list |
[Không bắt buộc] Không hoặc nhiều phương diện để nhóm kết quả. Kết quả được nhóm theo thứ tự mà bạn cung cấp các phương diện này. Bạn có thể sử dụng bất kỳ tên phương diện nào trong dimensionFilterGroups[].filters[].dimension cũng như "ngày" và "giờ". Các giá trị phương diện nhóm được kết hợp để tạo một khoá duy nhất cho mỗi hàng kết quả. Nếu bạn không chỉ định phương diện, thì tất cả giá trị sẽ được kết hợp thành một hàng duy nhất. Không có giới hạn về số lượng phương diện mà bạn có thể nhóm theo, nhưng bạn không thể nhóm theo cùng một phương diện hai lần. Ví dụ: [quốc gia, thiết bị] | |
searchType |
string |
Không dùng nữa, hãy chuyển sang sử dụng type
|
|
type |
string |
[Không bắt buộc] Lọc kết quả theo loại sau:
|
|
dimensionFilterGroups[] |
list |
[Không bắt buộc] Không hoặc nhiều nhóm bộ lọc để áp dụng cho các giá trị nhóm phương diện. Tất cả các nhóm bộ lọc phải khớp để một hàng được trả về trong phản hồi. Trong một nhóm bộ lọc, bạn có thể chỉ định rằng tất cả bộ lọc phải khớp hoặc ít nhất một bộ lọc phải khớp. | |
dimensionFilterGroups[].groupType |
string |
Liệu tất cả bộ lọc trong nhóm này có phải trả về giá trị true ("and") hay không, hoặc một hay nhiều bộ lọc phải trả về giá trị true (chưa được hỗ trợ).
Các giá trị được chấp nhận là:
|
|
dimensionFilterGroups[].filters[] |
list |
[Không bắt buộc] Không hoặc nhiều bộ lọc để kiểm tra hàng. Mỗi bộ lọc bao gồm một tên phương diện, một toán tử và một giá trị. Độ dài tối đa là 4096 ký tự. Ví dụ:
country equals FRA query contains mobile use device notContains tablet |
|
dimensionFilterGroups[].filters[].dimension |
string |
Phương diện mà bộ lọc này áp dụng. Bạn có thể lọc theo bất kỳ phương diện nào được liệt kê ở đây, ngay cả khi bạn không nhóm theo phương diện đó.
Các giá trị được chấp nhận là:
|
|
dimensionFilterGroups[].filters[].operator |
string |
[Không bắt buộc] Cách giá trị mà bạn chỉ định phải khớp (hoặc không khớp) với giá trị phương diện cho hàng.
Các giá trị được chấp nhận là:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Giá trị để bộ lọc so khớp hoặc loại trừ, tuỳ thuộc vào toán tử. | |
dimensionFilterGroups[].filterLists[] |
list |
[Không bắt buộc] Không hoặc nhiều bộ lọc phương diện nhiều giá trị để kiểm tra hàng.
Không giống như filters[] (khớp với một giá trị duy nhất cho mỗi mục nhập), filterLists[] cho phép so khớp với nhiều giá trị khớp chính xác cho một phương diện duy nhất trong một bộ lọc. Một hàng khớp với danh sách bộ lọc nếu giá trị của hàng đó cho dimension được chỉ định bằng với bất kỳ expressions nào được cung cấp. Xin lưu ý rằng một yêu cầu không thể lọc theo cùng một phương diện trong cả filters và filterLists cùng một lúc. |
|
dimensionFilterGroups[].filterLists[].dimension |
string |
[Bắt buộc] Phương diện mà danh sách bộ lọc này áp dụng.
Các giá trị được chấp nhận là:
|
|
dimensionFilterGroups[].filterLists[].expressions[] |
list |
[Bắt buộc] Danh sách các giá trị (string) để lọc. |
|
aggregationType |
string |
[Không bắt buộc] Cách tổng hợp dữ liệu. Nếu được tổng hợp theo tài sản, tất cả dữ liệu cho cùng một tài sản sẽ được tổng hợp; nếu được tổng hợp theo trang, tất cả dữ liệu sẽ được tổng hợp theo URI chính tắc. Nếu bạn lọc hoặc nhóm theo trang, hãy chọn tự động; nếu không, bạn có thể tổng hợp theo tài sản hoặc theo trang, tuỳ thuộc vào cách bạn muốn tính toán dữ liệu; hãy xem tài liệu trợ giúp để tìm hiểu cách tính toán dữ liệu theo trang web so với theo trang. Lưu ý: Nếu nhóm hoặc lọc theo trang, bạn không thể tổng hợp theo tài sản. Nếu bạn chỉ định bất kỳ giá trị nào khác ngoài auto, thì loại tổng hợp trong kết quả sẽ khớp với loại được yêu cầu hoặc nếu bạn yêu cầu một loại không hợp lệ, bạn sẽ gặp lỗi. API sẽ không bao giờ thay đổi loại tổng hợp nếu loại được yêu cầu không hợp lệ. Các giá trị được chấp nhận là:
|
|
rowLimit |
integer |
[Không bắt buộc; Phạm vi hợp lệ là 1 – 25.000; Giá trị mặc định là 1.000] Số hàng tối đa cần trả về. Để xem kết quả theo trang, hãy dùng thông số chênh lệch startRow. |
|
startRow |
integer |
[Không bắt buộc; Giá trị mặc định là 0] Chỉ mục dựa trên số 0 của hàng đầu tiên trong phản hồi. Phải là một số không âm. Nếu startRow vượt quá số lượng kết quả cho truy vấn, thì phản hồi sẽ là phản hồi thành công với không hàng. |
|
dataState |
string |
[Không bắt buộc] Nếu là "all" (không phân biệt chữ hoa chữ thường), thì dữ liệu sẽ bao gồm cả dữ liệu mới. Nếu bạn đặt giá trị là "final" (không phân biệt chữ hoa chữ thường) hoặc nếu bạn bỏ qua tham số này, thì dữ liệu được trả về sẽ chỉ bao gồm dữ liệu chính thức. Nếu là "hourly_all" (không phân biệt chữ hoa chữ thường), thì dữ liệu sẽ bao gồm thông tin chi tiết hằng giờ. Giá trị này cho biết rằng dữ liệu hằng giờ bao gồm cả dữ liệu chưa đầy đủ và nên được dùng khi nhóm theo phương diện HOUR của API. |
Phản hồi
Kết quả được nhóm theo các phương diện được chỉ định trong yêu cầu. Tất cả giá trị có cùng một nhóm giá trị phương diện sẽ được nhóm vào một hàng duy nhất. Ví dụ: nếu bạn nhóm theo phương diện quốc gia, thì tất cả kết quả cho "usa" sẽ được nhóm lại với nhau, tất cả kết quả cho "mdv" sẽ được nhóm lại với nhau, v.v. Nếu bạn nhóm theo quốc gia và thiết bị, thì tất cả kết quả cho "Hoa Kỳ, máy tính bảng" sẽ được nhóm lại, tất cả kết quả cho "Hoa Kỳ, thiết bị di động" sẽ được nhóm lại, v.v. Hãy xem tài liệu về báo cáo Phân tích tìm kiếm để tìm hiểu cụ thể về cách tính số lượt nhấp, số lượt hiển thị, v.v. và ý nghĩa của các chỉ số này.
Kết quả được sắp xếp theo số lượt nhấp, theo thứ tự giảm dần, trừ phi bạn nhóm theo ngày. Trong trường hợp đó, kết quả được sắp xếp theo ngày, theo thứ tự tăng dần (cũ nhất trước, mới nhất sau). Nếu có hai hàng bằng nhau, thứ tự sắp xếp sẽ là tuỳ ý.
Hãy xem thuộc tính rowLimit trong yêu cầu để biết số lượng giá trị tối đa có thể được trả về.
{
"rows": [
{
"keys": [
string
],
"clicks": double,
"impressions": double,
"ctr": double,
"position": double
}
],
"responseAggregationType": string
}| Tên tài sản | Giá trị | Mô tả | Ghi chú |
|---|---|---|---|
rows[] |
list |
Danh sách các hàng được bộ lọc nhóm theo giá trị khoá theo thứ tự được cung cấp trong truy vấn. | |
rows[].keys[] |
list |
Danh sách các giá trị phương diện cho hàng đó, được nhóm theo các phương diện trong yêu cầu, theo thứ tự được chỉ định trong yêu cầu. | |
rows[].clicks |
double |
Số lượt nhấp cho hàng. | |
rows[].impressions |
double |
Số lần hiển thị cho hàng. | |
rows[].ctr |
double |
Tỷ lệ nhấp (CTR) cho hàng. Giá trị nằm trong khoảng từ 0 đến 1, 0. | |
rows[].position |
double |
Vị trí trung bình trong kết quả tìm kiếm. | |
responseAggregationType |
string |
Cách tổng hợp kết quả. Hãy xem tài liệu trợ giúp để tìm hiểu cách tính dữ liệu theo trang web so với theo trang.
Các giá trị được chấp nhận là:
|
|
metadata |
object |
Một đối tượng có thể được trả về cùng với kết quả truy vấn, cung cấp bối cảnh về trạng thái của dữ liệu. Khi bạn yêu cầu dữ liệu gần đây (bằng cách sử dụng Tất cả ngày và giờ được cung cấp trong đối tượng này đều theo múi giờ Trường cụ thể được trả về trong đối tượng này phụ thuộc vào cách bạn nhóm dữ liệu trong yêu cầu:
|
Hãy dùng thử!
Sử dụng APIs Explorer bên dưới để gọi phương thức này trên dữ liệu trực tiếp và xem phản hồi.