Phản hồi JSON của Google Search API: Giải thích organic_results
Senior Web Scraping Engineer
Tóm tắt nhanh:
- organic_results là một tập hợp các bản ghi kết quả tìm kiếm tự nhiên. Đọc vị trí trả về, tiêu đề, đoạn trích và liên kết của từng bản ghi mà không trộn lẫn với các mô-đun tìm kiếm khác.
- Vị trí trả về và thứ tự trong mảng là hai giá trị riêng biệt. Giữ nguyên cả hai khi chuẩn bị tập dữ liệu.
- Một liên kết được trả về không tự động là URL đích cuối cùng đã được xác minh. Giữ trạng thái trung gian và ứng viên đích tách biệt nhau.
- Các trường bị thiếu phải được giữ hiển thị. Thiếu đoạn trích, chuỗi rỗng và bản ghi lỗi định dạng đòi hỏi cách xử lý khác nhau.
Giới thiệu: Đọc Response Trước Khi Làm Phẳng
Một JSON response của Google Search API có thể chứa kết quả tự nhiên bên cạnh knowledge panel, phần local, câu hỏi liên quan và các mô-đun phụ thuộc truy vấn khác. Làm phẳng mọi object có trường title sẽ tạo ra một tập dữ liệu với các ý nghĩa bị trộn lẫn.
Hướng dẫn này tập trung vào organic_results trong Scrapeless Google Search API. Mục tiêu là một định dạng bản ghi nhỏ, dễ kiểm tra cho tiêu đề, đoạn trích, vị trí và liên kết. Nó không xây dựng trình theo dõi thứ hạng hay khẳng định rằng mọi liên kết trả về đều đã được kiểm tra so với URL đích cuối cùng.
Ví dụ response Google Search và quy trình yêu cầu actor cung cấp ngữ cảnh request xung quanh. Ở đây, công việc hữu ích bắt đầu sau khi một response đã hoàn tất được lưu lại.
organic_results Chứa Gì
Trường organic_results là một mảng các object kết quả tự nhiên, với những trường mà tính sẵn có của chúng phải được kiểm tra trên từng mục. Một bản ghi không phải là bản sao đầy đủ của trang đích.
| Field | Ý nghĩa trong tập dữ liệu | Quy tắc xử lý |
|---|---|---|
position |
Vị trí được API trả về | Giữ nguyên, không tính lại |
title |
Tiêu đề kết quả | Giữ cho giá trị null hoặc thiếu phân biệt được với văn bản |
snippet |
Đoạn trích kết quả tìm kiếm | Xem nó như một quan sát từ tìm kiếm, không phải nội dung đầy đủ của trang |
link |
URL kết quả được trả về | Phân loại nó trước khi đối sánh đích ở bước tiếp theo |
redirect_link |
Liên kết dạng redirect bổ sung khi có | Lưu riêng; không tự động thay thế link |
source |
Nhãn nguồn được hiển thị khi có | Không giả định đó là domain có thể đăng ký |
Bảng mô tả các trường cần kiểm tra, không phải đảm bảo rằng mọi mục đều chứa mọi khóa. Tài liệu tham chiếu tham số định nghĩa các điều khiển request; nó không nên được đọc như một lời hứa rằng các mô-đun kết quả sẽ giống hệt nhau giữa các truy vấn.
JSON cho phép các giá trị như null, chuỗi và mảng, như được mô tả bởi đặc tả JSON. Một định dạng response linh hoạt vẫn cần một hợp đồng tiêu thụ có chủ đích. Hãy quyết định những giá trị thiếu nào ứng dụng của bạn có thể giữ lại và giá trị nào nên dừng quá trình xử lý.
Giữ Nguyên Position Mà Không Tự Sáng Chế Rank
Giữ nguyên position được trả về, chỉ số mảng và offset của request như các trường riêng khi gộp nhiều trang. Mỗi giá trị mô tả một phần khác nhau của quan sát.
Chỉ số mảng ghi lại vị trí mà một mục xuất hiện trong mảng được trả về. Vị trí trả về là giá trị do API cung cấp. Offset của request ghi lại bạn đã yêu cầu trang nào. Cộng offset vào position mà không xác định trước ngữ nghĩa của position đó có thể dẫn đến đếm offset hai lần hoặc ngụ ý một xếp hạng mà response không nêu ra.
Đừng đếm quảng cáo, knowledge graph và bản ghi tự nhiên trong một chuỗi duy nhất trừ khi bạn đã định nghĩa và xác thực phép đo tùy chỉnh đó. Một lập trình viên cần thứ hạng organic nên giữ đủ ngữ cảnh để kiểm tra trang tìm kiếm đã tạo ra bản ghi.
Lưu lại JSON nguyên gốc ngay cả khi cơ sở dữ liệu của bạn chỉ cần một vài cột. Sau này bạn có thể cần một trường mà script chuẩn hóa đầu tiên đã loại bỏ, hoặc bạn có thể cần phân biệt một trường vắng mặt với một giá trị được chính phép biến đổi của bạn đưa vào.
Phân Loại Liên Kết Trước Khi Resolve Chúng
Phân loại URL là một quyết định định tuyến cho bước xác thực tiếp theo; nó không phải là bằng chứng về đích cuối cùng. Response cơ bản cho coffee bao gồm các giá trị link trực tiếp và các giá trị redirect_link của Google riêng biệt trong cùng các bản ghi organic.
Kiểm tra scheme, hostname và path thay vì chỉ kiểm tra xem một chuỗi chỉ đơn thuần có chứa từ Google hay không. Mô hình thành phần URI làm cho những phần đó trở nên rõ ràng. Một URL có tên thương hiệu quen thuộc trong path của nó không nhất thiết được lưu trữ bởi thương hiệu đó.
Những phân loại hữu ích bao gồm giá trị bị thiếu, liên kết tương đối, một trình trung gian của Google đã được quan sát, và một URL tuyệt đối ứng viên. Giữ nguyên các giá trị mờ trong các liên kết /goto?url=.... Một tham số mờ (opaque parameter) không phải là một đích đến mà bạn có thể khôi phục bằng cách đoán một sơ đồ giải mã.
Bắt đầu Scraping với Scrapeless
Tăng cường quy trình web scraping và tự động hóa của bạn với Scrapeless!
Đăng ký hôm nay và nhận $5 tín dụng miễn phí — không cần thẻ tín dụng.Nhận tín dụng miễn phí của bạn ngay trong Bảng điều khiển Scrapeless.
Chuẩn hóa một Phản hồi JSON đã Lưu
Chương trình sau tạo các bản ghi đã chuẩn hóa mà không cần truy cập bất kỳ URL kết quả nào. Nó giữ lại cả hai trường liên kết và đính kèm một phân loại cục bộ để xem xét sau.
Điều kiện tiên quyết là Python và một phản hồi Google Search đã hoàn tất được lưu thành serp.json. Hãy lưu chính đối tượng phản hồi của API, không phải một wrapper tùy chỉnh chứa metadata ghi log của bạn. Yêu cầu quickstart cung cấp phản hồi đó. Lưu script dưới dạng normalize_organic.py và chạy python normalize_organic.py bên cạnh tệp JSON.
Hostname được đặt trong ví dụ bao phủ các host Google được quan sát trong họ phản hồi này. Nó cố ý không phải là một đăng ký toàn cầu của mọi miền Google. Chỉ mở rộng nó khi các phản hồi thực tế của bạn chứng minh rằng cần bổ sung. Các URL tuyệt đối khác vẫn là các ứng viên chưa được xác minh.
python
import json
from pathlib import Path
from urllib.parse import urlsplit
def classify_link(value):
if not isinstance(value, str) or not value.strip():
return "missing"
if value.startswith("/"):
return "relative_review"
try:
parts = urlsplit(value)
host = (parts.hostname or "").lower()
except ValueError:
return "invalid_review"
if parts.scheme not in ("https", "http") or not host:
return "invalid_review"
# These are observed Google hosts, not a global Google-domain registry.
google_hosts = {"google.com", "www.google.com"}
if host in google_hosts and parts.path in ("/url", "/goto"):
return "google_intermediary"
if host in google_hosts:
return "google_page_review"
return "absolute_candidate"
data = json.loads(Path("serp.json").read_text(encoding="utf-8"))
if not isinstance(data, dict) or not isinstance(data.get("organic_results"), list):
raise ValueError("Expected an object with an organic_results array")
normalized = []
for index, row in enumerate(data["organic_results"], start=1):
if not isinstance(row, dict):
raise ValueError(f"Invalid result at index {index}")
normalized.append({
"array_index": index,
"returned_position": row.get("position"),
"title": row.get("title"),
"snippet": row.get("snippet"),
"link": row.get("link"),
"redirect_link": row.get("redirect_link"),
"link_state": classify_link(row.get("link")),
})
Path("organic-normalized.json").write_text(
json.dumps(normalized, ensure_ascii=False, indent=2), encoding="utf-8"
)
counts = {}
for row in normalized:
state = row["link_state"]
counts[state] = counts.get(state, 0) + 1
print(json.dumps({"rows": len(normalized), "link_states": counts}))
Các hàm phân tích URL của Python tách các thành phần, nhưng chỉ phân tích cú pháp thì không xác thực được độ tin cậy hay khả năng truy cập mạng. Do đó, trạng thái absolute_candidate của script có nghĩa chính xác là: một URL HTTP tuyệt đối với hostname đã xuất hiện.
Quyết định Khi Nào Cần URL Cuối Cùng
Việc xác minh URL cuối cùng trở nên cần thiết khi kết luận của bạn phụ thuộc vào danh tính của trang đích. Khám phá từ khóa có thể giữ lại một liên kết ứng viên để kiểm tra sau; xếp hạng miền mục tiêu, gán nguồn và cung cấp trích dẫn yêu cầu bằng chứng mạnh hơn.
| Tác vụ Hạ nguồn | Điều Liên kết Trả về Có thể Hỗ trợ | Công việc Bổ sung |
|---|---|---|
| Khám phá chủ đề | Một nguồn ứng viên bên cạnh đoạn trích | Xem lại trang trước khi dựa vào các tuyên bố của nó |
| Kiểm toán phản hồi tìm kiếm | Văn bản liên kết mà API trả về | Giữ lại phản hồi gốc và HTML khi cần |
| Khớp miền | Một phân loại ứng viên sơ bộ | Phân giải và xác minh miền đích |
| Trích dẫn đã xác minh | Một tham chiếu ứng viên | Kiểm tra URL cuối cùng, nội dung có thể truy cập và sự hỗ trợ cho tuyên bố |
Nếu bạn xây dựng một bộ phân giải đích đến, hãy giữ URL gốc và URL cuối cùng thành các cột riêng biệt. Ghi lại chuỗi chuyển hướng và kết quả phân giải. Không gửi khóa API Scrapeless tới các website kết quả, và không coi lỗi mạng là bằng chứng rằng trang không tồn tại.
Tránh loại bỏ tham số truy vấn một cách bừa bãi. Một số tham số là một phần của danh tính trang. Ngay cả việc xóa dấu gạch chéo ở cuối cũng có thể gộp các URL mà một origin xử lý khác nhau. Bắt đầu với các quy tắc so sánh thận trọng, sau đó ghi lại mọi chính sách chuẩn hóa mà tập dữ liệu của bạn sử dụng.
Chẩn đoán Các Trường Thiếu hoặc Bất Ngờ
Một báo cáo chất lượng trường nên hiển thị những gì đã nhận được thay vì âm thầm tạo ra các giá trị thay thế. Đếm các chuỗi không rỗng tách biệt với các key chỉ đơn thuần tồn tại.
Đối với snippet, hãy phân biệt một key bị lược bỏ, một giá trị null, một chuỗi rỗng và văn bản không rỗng. Những trạng thái đó ảnh hưởng đến việc một hàng có thể hỗ trợ phân tích văn bản hay không. Giữ một hàng với snippet bị thiếu nếu tiêu đề của nó vẫn phục vụ tác vụ của bạn, nhưng hãy gắn cờ phần thiếu để một nhà phân tích hiểu được hạn chế.
Ở cấp độ thu thập, một mảng organic vắng mặt không tương đương với một mảng organic trống. Các mục sai kiểu nên dừng một bộ tiêu thụ nghiêm ngặt hoặc được ghi lại trong một báo cáo từ chối. Cả hai lựa chọn đều không nên âm thầm làm tăng chỉ số thành công.
Kết luận: Giữ Nguyên Ý Nghĩa của Mỗi Trường
Một bộ phân tích phản hồi JSON Google Search API đáng tin cậy giữ nguyên các trường nguồn và chỉ thêm những biến đổi mà nó có thể giải thích. Vị trí, thứ tự mảng và trạng thái URL vẫn hiển thị, trong khi các giả định về đích đến không được hỗ trợ sẽ không xuất hiện trong bản ghi.
Bắt đầu với Scrapeless Google Search API, chọn tần suất thu thập so với bảng giá hiện tại, và kiểm tra một vài phản hồi đã lưu trước khi chốt một lược đồ cơ sở dữ liệu.
Xây Dựng Quy Trình Dữ Liệu Tìm Kiếm Của Bạn
Tham gia cùng các nhà phát triển làm việc với dữ liệu tìm kiếm trong cộng đồng của chúng tôi: Discord · Telegram.
Tạo một tài khoản Scrapeless và áp dụng hướng dẫn này cho một tập truy vấn nhỏ trước khi lên lịch cho một đợt thu thập lớn hơn.
FAQ
Hỏi: organic_results có bao gồm mọi phần hiển thị trên SERP không?
Không. Các tính năng tìm kiếm khác có thể xuất hiện trong các phần phản hồi riêng. Một bộ phân tích mảng organic không nên âm thầm hấp thụ các mô-đun đó.
Hỏi: position có giống với chỉ số mảng của mục không?
Đừng cho rằng chúng có thể hoán đổi cho nhau. Giữ riêng giá trị position được trả về và chỉ số mảng, đặc biệt là trên các yêu cầu phân trang.
Hỏi: redirect_link có nên thay thế link không?
Không. Giữ cả hai khi cùng xuất hiện. Chọn một chính sách xử lý đích dựa trên trạng thái URL thực tế và tác vụ ở bước sau của bạn.
Hỏi: Một liên kết Google đã mã hóa có thể được xử lý như một đích đã giải mã không?
Không. Giữ nguyên các giá trị mờ và sử dụng một quy trình phân giải đã được kiểm chứng khi cần xác định danh tính đích cuối cùng.
Hỏi: Một snippet không rỗng có chứng minh bản tóm tắt là chính xác không?
Không. Văn bản không rỗng đo lường tính sẵn có của trường. Độ chính xác và việc hỗ trợ tuyên bố cần phải kiểm tra nội dung nguồn.
Hỏi: Việc chuẩn hóa có cần một tác nhân AI hoặc một proxy riêng không?
Không. Script chuẩn hóa này hoạt động trên JSON đã lưu và không thực hiện bất kỳ yêu cầu mạng nào.
Tại Scrapless, chúng tôi chỉ truy cập dữ liệu có sẵn công khai trong khi tuân thủ nghiêm ngặt các luật, quy định và chính sách bảo mật trang web hiện hành. Nội dung trong blog này chỉ nhằm mục đích trình diễn và không liên quan đến bất kỳ hoạt động bất hợp pháp hoặc vi phạm nào. Chúng tôi không đảm bảo và từ chối mọi trách nhiệm đối với việc sử dụng thông tin từ blog này hoặc các liên kết của bên thứ ba. Trước khi tham gia vào bất kỳ hoạt động cạo nào, hãy tham khảo ý kiến cố vấn pháp lý của bạn và xem xét các điều khoản dịch vụ của trang web mục tiêu hoặc có được các quyền cần thiết.



