Kết nối Google Search Console API bằng Python

Toàn bộ quy trình, từ chuẩn bị công cụ đến cách dùng Python lấy dữ liệu Google Search Console, được trình bày theo từng bước cụ thể dành cho bạn.

25.000

dòng dữ liệu tối đa mỗi lần gọi API

3.600

giây hiệu lực của mã truy cập OAuth

ngày sống của mã làm mới ở chế độ thử nghiệm

Nếu bạn đang tìm cách kết nối Google Search Console API bằng Python để tự động hóa việc theo dõi hiệu suất website, bài viết này sẽ đồng hành cùng bạn ngay từ những bước đầu tiên. Bạn sẽ được hướng dẫn cách dùng Python lấy dữ liệu Google Search Console theo một quy trình rõ ràng, bắt đầu từ việc chuẩn bị công cụ trên Google Cloud, cài đặt thư viện phù hợp, xác thực OAuth cho đến khi truy vấn thành công báo cáo hiệu suất tìm kiếm. Mỗi bước đều kèm ví dụ cụ thể, giúp bạn tránh những lỗi mà nhiều lập trình viên từng gặp phải.

Hướng dẫn chi tiết cách kết nối Google Search Console API bằng Python

Quy trình gồm năm bước chính, đi tuần tự từ việc chuẩn bị quyền truy cập cho đến khi dữ liệu đổ về máy của bạn dưới dạng có thể phân tích được. Bạn nên đọc kỹ từng bước một lần trước khi bắt tay vào viết mã, vì phần lớn lỗi phát sinh đến từ việc bỏ qua điều kiện tiên quyết ở những bước đầu. Ngoài ra, mỗi bước trong hướng dẫn này đều gắn liền với một phần việc cụ thể mà bạn sẽ lặp lại nhiều lần về sau, nên việc hiểu đúng bản chất ngay từ lần đầu sẽ giúp bạn tiết kiệm rất nhiều thời gian khi mở rộng sang những website hoặc dự án khác.

Chuẩn bị tài khoản và dự án trên Google Cloud

Trước khi viết bất kỳ dòng lệnh Python nào, bạn cần chuẩn bị đầy đủ điều kiện trên Google Cloud và Search Console. Đây là nền tảng quyết định việc xác thực có diễn ra suôn sẻ hay không, bởi mọi yêu cầu gửi tới Google đều phải đi kèm thông tin định danh hợp lệ. Nếu bỏ qua bước này, bạn rất dễ gặp lỗi quyền truy cập ngay từ lần gọi đầu tiên. Nhiều lập trình viên mới thường bỏ sót phần cấu hình màn hình đồng ý, dẫn đến việc chương trình chạy đúng cú pháp nhưng vẫn bị Google từ chối ngay khi mở trình duyệt đăng nhập.

Một website đã được xác minh quyền sở hữu trong Search Console.
Một dự án được tạo mới hoặc được chọn sẵn trên Google Cloud.
Search Console API được bật trong thư viện API của dự án đó.
Màn hình đồng ý OAuth được cấu hình đầy đủ thông tin ứng dụng.
Tệp thông tin xác thực OAuth được tải về và lưu trữ an toàn trên máy.

Ghi nhớ

Bạn nên thêm chính tài khoản Google của mình vào danh sách người dùng thử nghiệm nếu ứng dụng đang ở chế độ kiểm thử. Nếu bỏ sót thao tác này, màn hình đồng ý sẽ từ chối cho bạn đăng nhập dù mọi cấu hình khác đều đúng.

Cài đặt các thư viện Python cần thiết

Sau khi đã có đầy đủ tệp thông tin xác thực, bạn tiến hành cài đặt các thư viện hỗ trợ giao tiếp với Google. Phần lớn công việc xác thực và gọi API đều được những thư viện này xử lý sẵn, nên bạn không cần tự viết lại toàn bộ giao thức OAuth từ đầu. Nếu môi trường làm việc của bạn dùng nhiều dự án Python khác nhau, hãy cân nhắc tạo một môi trường ảo riêng để tránh xung đột phiên bản giữa các gói thư viện.

pip install upgrade google api python client google auth httplib2 google auth oauthlib pandas

Gói dành cho client Google đảm nhiệm việc dựng dịch vụ gọi API, hai gói liên quan đến xác thực hỗ trợ toàn bộ luồng OAuth, còn pandas giúp bạn xử lý dữ liệu trả về dưới dạng bảng để phân tích hoặc xuất báo cáo về sau.

Xác thực OAuth và khởi tạo dịch vụ kết nối

Khi thư viện đã sẵn sàng, bạn bắt đầu luồng xác thực OAuth bằng tệp thông tin xác thực đã tải về ở bước đầu tiên. Trình duyệt sẽ tự mở ra để bạn đăng nhập và cấp quyền, sau đó chương trình Python nhận lại mã truy cập dùng cho những lần gọi tiếp theo. Phần khai báo phạm vi quyền truy cập, gọi là scope, cần được lựa chọn cẩn thận ngay tại bước này.

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

SCOPES = ['https://www.googleapis.com/auth/webmasters.readonly']

flow = InstalledAppFlow.from_client_secrets_file('client_secret.json', scopes=SCOPES)
credentials = flow.run_local_server(port=0)
service = build('searchconsole', 'v1', credentials=credentials)

Google cung cấp hai mức phạm vi phổ biến cho việc kết nối với Search Console:

Phạm vi chỉ đọc, ký hiệu là webmasters.readonly, phù hợp khi bạn chỉ cần xem báo cáo hiệu suất.
Phạm vi đầy đủ, ký hiệu là webmasters, dùng khi ứng dụng cần thao tác sâu hơn với thuộc tính.

Ưu tiên phạm vi hẹp nhất có thể khi xin quyền truy cập, vì điều này giúp quá trình xét duyệt ứng dụng diễn ra nhanh hơn và giảm rủi ro cho dữ liệu người dùng.

Nguyên tắc thiết kế quyền truy cập an toàn

Gọi API lấy dữ liệu Search Analytics

Sau khi có dịch vụ kết nối hợp lệ, bạn có thể truy vấn báo cáo Search Analytics theo nhiều chiều dữ liệu khác nhau như truy vấn tìm kiếm, trang, quốc gia hoặc thiết bị. Đây chính là phần thể hiện rõ nhất cách dùng Python lấy dữ liệu Google Search Console phục vụ công việc phân tích, bởi dữ liệu trả về là nguyên liệu cho mọi báo cáo SEO sau này.

response = service.searchanalytics().query(
    siteUrl='https://vidu.com/',
    body={
        'startDate': '2026.07.01',
        'endDate': '2026.07.22',
        'dimensions': ['query', 'page'],
        'rowLimit': 25000,
        'startRow': 0
    }
).execute()

Bạn có thể thay đổi dimensions bằng page, country, device hoặc kết hợp nhiều chiều cùng lúc để có góc nhìn chi tiết hơn về từng nhóm nội dung trên website. Việc lựa chọn chiều dữ liệu phù hợp giúp bạn tránh tải về những cột không cần thiết, đồng thời rút ngắn thời gian xử lý khi lượng truy vấn của website khá lớn.

Theo tài liệu chính thức của Google, số dòng dữ liệu trả về mặc định cho mỗi lần gọi chỉ là 1.000 dòng, tuy nhiên bạn hoàn toàn có thể nâng tham số rowLimit lên tối đa 25.000 dòng trong một lần truy vấn. Nếu website của bạn có lượng dữ liệu lớn, hãy phân trang bằng tham số startRow, vì tổng dữ liệu tối đa lấy được mỗi ngày cho mỗi loại tìm kiếm trên mỗi trang web là 50.000 dòng, cao hơn nhiều so với giới hạn 1.000 dòng khi xuất trực tiếp từ giao diện Search Console.

Xử lý lỗi thường gặp khi kết nối

Ngay cả khi làm đúng từng bước, bạn vẫn có thể gặp một số lỗi quen thuộc trong quá trình xác thực và truy vấn. Bảng liệt kê những tình huống phổ biến nhất cùng hướng xử lý tương ứng, giúp bạn tiết kiệm thời gian tìm hiểu nguyên nhân thay vì phải dò từng dòng nhật ký lỗi một cách thủ công.

Lỗi	Nguyên nhân	Cách xử lý
Quyền truy cập không đủ	Tài khoản chưa có quyền trên thuộc tính hoặc phạm vi khai báo quá hẹp	Kiểm tra quyền của tài khoản trên thuộc tính và điều chỉnh scope phù hợp
Thông tin xác thực không hợp lệ	Mã truy cập hết hạn hoặc tệp thông tin xác thực gắn sai vào client	Chạy lại luồng OAuth hoặc dùng mã làm mới để lấy mã truy cập mới
Bị từ chối cấp quyền	Người dùng từ chối màn hình đồng ý hoặc màn hình đó chưa cấu hình đúng	Kiểm tra lại cấu hình màn hình đồng ý và danh sách người dùng thử nghiệm
Không thấy thuộc tính	Tài khoản đăng nhập khác tài khoản có quyền hoặc thuộc tính chưa xác minh	Đăng nhập đúng tài khoản có quyền và xác minh lại thuộc tính trong Search Console
Địa chỉ chuyển hướng không khớp	Địa chỉ khai báo trên Google Cloud không trùng với địa chỉ trong mã nguồn	Đồng bộ chính xác địa chỉ chuyển hướng ở cả hai nơi

Ghi nhớ

Mã truy cập OAuth chỉ có hiệu lực trong khoảng 3.600 giây, tương đương một giờ đồng hồ, nên chương trình của bạn cần dùng mã làm mới để lấy mã truy cập kế tiếp một cách tự động. Nếu ứng dụng vẫn ở chế độ thử nghiệm, mã làm mới sẽ hết hiệu lực sau 7 ngày, buộc bạn phải đăng nhập lại từ đầu.

Ứng dụng thực tế của dữ liệu Search Console trong công việc SEO

Khi bạn đã làm chủ được cách kết nối và truy vấn dữ liệu, bước tiếp theo là biến những con số thô thành báo cáo có giá trị cho công việc hằng ngày. Nhiều đội ngũ SEO chọn Python thay vì thao tác thủ công trên giao diện, bởi khối lượng truy vấn và trang trên một website lớn thường vượt xa những gì có thể xem trực tiếp trên màn hình.

Tổng hợp dữ liệu truy vấn theo từng trang để phát hiện nội dung đang mất thứ hạng.
Gộp dữ liệu nhiều thuộc tính lại với nhau để có góc nhìn toàn cảnh về hiệu suất.
Đưa dữ liệu vào pandas nhằm tính toán tỷ lệ nhấp, vị trí trung bình theo thời gian.
Xuất báo cáo định kỳ dưới dạng bảng tính hoặc bảng điều khiển cho khách hàng.

Một quy trình phổ biến mà bạn có thể áp dụng ngay là đăng nhập bằng OAuth, kéo dữ liệu theo truy vấn và trang, sau đó đẩy toàn bộ kết quả sang pandas để tính toán và cuối cùng xuất ra tệp báo cáo. Khi quy trình này chạy ổn định, bạn hoàn toàn có thể đặt lịch chạy tự động mỗi ngày hoặc mỗi tuần, giúp đội ngũ SEO có dữ liệu cập nhật mà không cần thao tác tay trên giao diện Search Console.

Lưu ý về bảo mật thông tin xác thực

Tệp thông tin xác thực và mã làm mới là những thứ có giá trị tương đương mật khẩu, bởi bất kỳ ai sở hữu chúng cũng có thể gọi API thay cho bạn. Bạn nên lưu những tệp này ở nơi tách biệt khỏi mã nguồn công khai và tuyệt đối không đưa chúng lên các kho lưu trữ chia sẻ công cộng.

Khi triển khai trên máy chủ dùng chung cho nhiều người, bạn nên giới hạn quyền đọc tệp thông tin xác thực chỉ cho tài khoản chạy chương trình, đồng thời cân nhắc luân phiên tạo lại thông tin xác thực định kỳ để giảm thiểu rủi ro nếu một trong các tệp này chẳng may bị lộ ra ngoài.

Lời kết

Việc kết nối Google Search Console API bằng Python không còn là thử thách nếu bạn đi đúng trình tự đã trình bày, từ chuẩn bị dự án trên Google Cloud, xác thực OAuth cho đến gọi Search Analytics để lấy dữ liệu. Khi đã nắm vững cách dùng Python lấy dữ liệu Google Search Console, bạn hoàn toàn có thể xây dựng báo cáo tự động phục vụ việc phân tích từ khóa, theo dõi trang và tối ưu chiến lược nội dung. Hãy bắt đầu với một dự án nhỏ và mở rộng dần khi bạn đã quen thuộc với luồng xác thực này.