Search Analytics: query

Cần có quyền uỷ quyền

Truy vấn dữ liệu lưu lượng truy cập từ hoạt động tìm kiếm 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 các khoá hàng (phương diện) mà bạn xác định. Bạn phải xác định một 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ị loại khỏi danh sách kết quả. Để biết những ngày 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ì chúng sẽ được sắp xếp theo cách tuỳ ý.

Hãy xem mẫu python để gọi phương thức này.

API này bị giới hạn bởi các quy tắ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.

Ví dụ về yêu cầu 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"] }
Thử ngay.

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 đượ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 bằng í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 phần 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         }       ]     }   ],   "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 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 nằm trong 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. 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 mọi tên phương diện trong dimensionFilterGroups[].filters[].dimension cũng như "date" (ngày) và "hour" (giờ). Các giá trị phương diện phân nhóm được kết hợp để tạo một khoá riêng biệt cho mỗi hàng kết quả. Nếu bạn không chỉ định phương diện nào, thì tất cả các giá trị sẽ được kết hợp thành một hàng. 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 sử dụng type thay thế
type string [Không bắt buộc] Lọc kết quả theo loại sau:
  • "discover": Kết quả trong Khám phá
  • "googleNews": Kết quả từ news.google.com và ứng dụng Google News trên Android và iOS. Không bao gồm kết quả trên thẻ "Tin tức" trong Google Tìm kiếm.
  • "news": Kết quả tìm kiếm trong thẻ "Tin tức" trên Google Tìm kiếm.
  • "image": Kết quả tìm kiếm trên thẻ "Hình ảnh" trong Google Tìm kiếm.
  • "video": Kết quả tìm kiếm video
  • "web": [Mặc định] Lọc kết quả theo thẻ kết hợp ("Tất cả") trong Google Tìm kiếm. Không bao gồm kết quả trên Khám phá hoặc Google News.
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 theo 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 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 phải trả về giá trị 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 chấp nhận là:
  • "and": Tất cả bộ lọc trong nhóm phải trả về giá trị true để nhóm bộ lọc trả về giá trị true.
dimensionFilterGroups[].filters[] list [Không bắt buộc] Không có hoặc có nhiều bộ lọc để kiểm tra theo 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à:
  • "country": Lọc theo quốc gia được chỉ định, theo mã quốc gia gồm 3 chữ cái (ISO 3166-1 alpha-3).
  • "device": Lọc kết quả theo loại thiết bị được chỉ định. Giá trị được hỗ trợ:
    • DESKTOP
    • THIẾT BỊ DI ĐỘNG
    • MÁY TÍNH BẢNG
  • "page": Lọc theo chuỗi URI đã chỉ định.
  • "query": Lọc theo chuỗi truy vấn được chỉ định.
  • "searchAppearance": Lọc theo một tính năng cụ thể của kết quả tìm kiếm. Để xem danh sách các giá trị có sẵn, hãy chạy một truy vấn được nhóm theo "searchAppearance". Danh sách đầy đủ các giá trị và nội dung mô tả cũng có trong tài liệu trợ giúp.
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à:
  • "contains": Giá trị hàng phải chứa hoặc bằng với biểu thức của bạn (không phân biệt chữ hoa chữ thường).
  • "equals": [Mặc định] Biểu thức của bạn phải hoàn toàn bằng với giá trị hàng (phân biệt chữ hoa chữ thường đối với phương diện trang và truy vấn).
  • "notContains": Giá trị hàng không được chứa biểu thức của bạn dưới dạng chuỗi con hoặc giá trị khớp hoàn toàn (không phân biệt chữ hoa chữ thường).
  • "notEquals": Biểu thức của bạn không được hoàn toàn bằng giá trị hàng (phân biệt chữ hoa chữ thường đối với phương diện trang và truy vấn).
  • "includingRegex": Một biểu thức chính quy cú pháp RE2 phải được so khớp.
  • "excludingRegex": Một biểu thức chính quy cú pháp RE2 không được khớp.
dimensionFilterGroups[].filters[].expression string Giá trị của bộ lọc cần khớp hoặc loại trừ, 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 đượ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 chuẩn. 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 dữ liệu được tính toán theo cách khác nhau 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 với 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ệ, thì 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 không hợp lệ.

Các giá trị được chấp nhận là:
  • "auto": [Mặc định] Cho phép dịch vụ quyết định loại tổng hợp phù hợp.
  • "byNewsShowcasePanel": Tổng hợp các giá trị theo bảng điều khiển Nổi bật trên Google News. Bạn phải sử dụng bộ lọc này cùng với bộ lọc NEWS_SHOWCASE searchAppearance và type=discover hoặc type=googleNews. Nếu nhóm theo trang, lọc theo trang hoặc lọc theo searchAppearance khác, bạn không thể tổng hợp theo byNewsShowcasePanel.
  • "byPage": Tổng hợp các giá trị theo URI.
  • "byProperty": Tổng hợp các giá trị theo tài sản. Không được hỗ trợ trên type=discover hoặc type=googleNews
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ề. Để phân trang kết quả, hãy sử 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 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à một phản hồi thành công với 0 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), dữ liệu sẽ bao gồm dữ liệu mới nhất. Nếu 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, dữ liệu trả về sẽ chỉ bao gồm dữ liệu đã hoàn tất. Nếu là "hourly_all" (không phân biệt chữ hoa chữ thường), dữ liệu sẽ bao gồm thông tin chi tiết theo giờ. Giá trị này cho biết rằng dữ liệu hằng giờ bao gồm cả dữ liệu một phần và nên được dùng khi nhóm theo phương diện API GIỜ.

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ả các giá trị có cùng một nhóm giá trị phương diện sẽ được nhóm thành 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 "Hoa Kỳ, máy tính bảng" sẽ được nhóm, tất cả kết quả cho "Hoa Kỳ, thiết bị di động" sẽ được nhóm, 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ả sẽ đượ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ó sự ràng buộc giữa hai hàng, thì thứ tự sắp xếp sẽ 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ị 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 đưa ra 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 dữ liệu được tính theo trang web khác với theo trang.

Các giá trị được chấp nhận là:
  • "auto"
  • "byPage": Kết quả được tổng hợp theo trang.
  • "byProperty": Kết quả được tổng hợp theo tài sản.
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 ngữ 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 all hoặc hourly_all cho dataState), một số hàng được trả về có thể biểu thị dữ liệu chưa đầy đủ, tức là dữ liệu vẫn đang được thu thập và xử lý. Đối tượng siêu dữ liệu này giúp bạn xác định chính xác thời điểm bắt đầu và kết thúc.

Tất cả ngày và giờ được cung cấp trong đối tượng này đều thuộc múi giờ America/Los_Angeles.

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:

  • first_incomplete_date (string): Ngày đầu tiên mà dữ liệu vẫn đang được thu thập và xử lý, được trình bày ở định dạng YYYY-MM-DD (định dạng ngày địa phương mở rộng ISO-8601).

    Trường này chỉ được điền sẵn khi dataState của yêu cầu là all và dữ liệu được nhóm theo date, đồng thời phạm vi ngày được yêu cầu có chứa các điểm dữ liệu không đầy đủ.

    Tất cả các giá trị sau first_incomplete_date vẫn có thể thay đổi đáng kể.

  • first_incomplete_hour (string): Giờ đầu tiên mà dữ liệu vẫn đang được thu thập và xử lý, được trình bày ở định dạng YYYY-MM-DDThh:mm:ss[+|-]hh:mm (định dạng ngày giờ có độ lệch mở rộng ISO-8601).

    Trường này chỉ được điền sẵn khi dataState của yêu cầu là hourly_all và dữ liệu được nhóm theo hour, đồng thời phạm vi ngày được yêu cầu chứa các điểm dữ liệu không đầy đủ.

    Tất cả các giá trị sau first_incomplete_hour vẫn có thể thay đổi đáng kể.

Hãy dùng thử!

Hãy sử dụng Trình khám phá API bên dưới để gọi phương thức này trên dữ liệu thực và xem phản hồi.