Cần có sự cho phép
Truy vấn dữ liệu về lưu lượng truy cập tìm kiếm của bạn bằng các bộ lọc và thông số mà bạn xác định. Phương thức này trả về 0 hoặc nhiều hàng đượ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 thì bất kỳ ngày nào không có dữ liệu đều sẽ bị loại khỏi danh sách kết quả. Để tìm hiểu những ngày nào có dữ liệu, hãy tạo một truy vấn mà không có cá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, các hàng này sẽ được sắp xếp một cách tuỳ ý.
Hãy xem mẫu python để gọi phương thức này.
API này chịu ảnh hưởng của các giới hạn nội bộ của Search Console và không đảm bảo sẽ trả về tất cả các hàng dữ liệu mà là trả về các hàng hàng đầu.
Xem các giới hạn đối với 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
Các tham số
Tên thông số | Giá trị | Nội dung 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 có tiền tố URL) 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ề quy trình 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, 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 } ] } ], "aggregationType": string, "rowLimit": integer, "startRow": integer }
Tên tài sản | Giá trị | Nội dung 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, ở định dạng YYYY-MM-DD, theo giờ Thái Bình Dương (UTC – 7:00/8:00). Phải nhỏ hơn hoặc bằng ngày kết thúc. Giá trị này được đưa vào phạm vi. | |
endDate |
string |
[Bắt buộc] Ngày kết thúc của phạm vi ngày được yêu cầu, ở đị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 được đưa vào phạm vi. | |
dimensions[] |
list |
[Không bắt buộc] Không có hoặc có nhiều phương diện để nhóm kết quả theo.Các kết quả được nhóm lại theo thứ tự mà bạn cung cấp các phương diện này.Bạn có thể sử dụng tên phương diện bất kỳ trong dimensionFilterGroups[].filters[].dimension cũng như "ngày".Hệ thống kết hợp các giá trị phương diện nhóm để tạo ra 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, hệ thống sẽ kết hợp tất cả giá trị vào 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 hai lần theo cùng một phương diện. Ví dụ: [quốc gia, thiết bị] | |
searchType |
string |
Không dùng nữa, chuyển sang 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 có hoặc 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 để hệ thống trả về một hàng trong phản hồi. Trong một nhóm bộ lọc, bạn có thể chỉ định xem tất cả bộ lọc phải khớp hay í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ề true ("và") hay một hoặc nhiều bộ lọc phải trả về giá trị true (chưa được hỗ trợ).
Các giá trị có thể chấp nhận là:
|
|
dimensionFilterGroups[].filters[] |
list |
[Không bắt buộc] Không có hoặc có nhiều bộ lọc để thử nghiệm đối với 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 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ó thể 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ị thứ nguyên cho hàng.
Các giá trị có thể chấp nhận là:
|
|
dimensionFilterGroups[].filters[].expression |
string |
Giá trị cần khớp hoặc loại trừ cho bộ lọc, tuỳ thuộc vào toán tử. | |
aggregationType |
string |
[Không bắt buộc] Cách tổng hợp dữ liệu. Nếu bạn tổng hợp theo tài sản thì mọi dữ liệu cho cùng một tài sản sẽ được tổng hợp; còn nếu được tổng hợp theo trang thì 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 dữ liệu. Vui lòng xem tài liệu trợ giúp để tìm hiểu cách tính dữ liệu theo trang web khác với 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ông phải là giá trị tự động, 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 của bạn nếu loại được yêu cầu là 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; Mặc định là 1.000] Số hàng tối đa cần trả về. Để xem các trang kết quả, hãy sử dụng mức chênh lệch startRow . |
|
startRow |
integer |
[Không bắt buộc; Mặc định là 0] Chỉ mục dựa trên giá trị 0 của hàng đầu tiên trong phản hồi. Phải là 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 0 hàng. |
|
dataState |
string |
[Không bắt buộc] Nếu chọn "all" (không phân biệt chữ hoa chữ thường), dữ liệu sẽ bao gồm dữ liệu mới. Nếu "cuối cùng" (không phân biệt chữ hoa chữ thường) hoặc nếu tham số này bị bỏ qua, dữ liệu được trả về sẽ chỉ bao gồm dữ liệu cuối cùng. |
Phản hồi
Kết quả sẽ được nhóm theo phương diện được chỉ định trong yêu cầu. Tất cả cá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, 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 "usa, máy tính bảng" sẽ được nhóm, tất cả kết quả cho "usa, mobile" 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 thông tin cụ thể về cách tính số lượt nhấp, số lượt hiển thị và các dữ liệu khác cũng như ý nghĩa của các số liệu 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 xếp trước, mới nhất xếp trước). Nếu có sự ràng buộc giữa hai hàng, thì thứ tự sắp xếp này là tuỳ ý.
Hãy xem thuộc tính rowLimit trong yêu cầu để tìm hiểu 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ị | Nội dung mô tả | Ghi chú |
---|---|---|---|
rows[] |
list |
Danh sách các hàng được nhóm theo các 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ượt 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ả.Xem tài liệu trợ giúp để tìm hiểu cách tính dữ liệu theo từng trang web khác với cách tính dữ liệu theo trang.
Các giá trị có thể chấp nhận là:
|
Hãy dùng thử!
Hãy 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.