Loading Light/Dark Toggle
Quay lại blog

gl vs hl vs location: Cài đặt ngôn ngữ/khu vực của Google Search API

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

Tóm tắt nhanh:

  • gl, hl và location mô tả những đầu vào tìm kiếm khác nhau. Giữ riêng biệt quốc gia, ngôn ngữ và nguồn gốc tìm kiếm.
  • Bảy yêu cầu quốc gia thành công cho thấy dữ liệu được trả về. Chúng không thiết lập phần trăm độ chính xác ở cấp thành phố.
  • Một bài kiểm thử bản địa hóa hữu ích chỉ thay đổi một biến mỗi lần. Cố định truy vấn và các thiết lập khác trước khi so sánh kết quả.
  • Các thiết lập được yêu cầu phải nằm cạnh bằng chứng quan sát được. Đánh dấu một vị trí là chưa được xác minh cho đến khi có kiểm tra độc lập hỗ trợ.

Giới thiệu: Mã quốc gia chỉ là một phần của tìm kiếm

Kết quả tìm kiếm phụ thuộc vào nhiều hơn một từ khóa. Tùy chọn quốc gia, thiết lập ngôn ngữ và nguồn gốc địa phương đều cung cấp ngữ cảnh, và chúng có thể tạo ra những hiệu ứng khác nhau.

Hướng dẫn này giải thích gl so với hl so với location cho Scrapeless Google Search API. Nó trình bày một ma trận yêu cầu bảy quốc gia và một phương pháp để kiểm tra hành vi địa phương một cách độc lập. Nó không xem một phản hồi không rỗng là bằng chứng rằng một thành phố cụ thể đã được biểu diễn chính xác.

Hợp đồng tham số Google Search là tài liệu tham chiếu cho các điều khiển được chấp nhận. Quy trình yêu cầu của actor vẫn giống nhau khi bạn thay đổi các điều khiển đó bên trong input.

Mỗi tham số điều khiển điều gì

Tham số gl chọn quốc gia tìm kiếm, hl chọn ngôn ngữ tìm kiếm, và location xác định nguồn gốc tìm kiếm được yêu cầu. Các đầu vào này nên được lưu trữ riêng trong một bản ghi tập hợp.

Parameter Example What Not to Infer
gl us Mọi kết quả đều phải thuộc về một tổ chức ở Mỹ
hl en Mọi trang đích đều phải là tiếng Anh
location Austin, Texas, United States Mọi kết quả địa phương đều đã được mã hóa địa lý độc lập
google_domain google.com Chỉ riêng tên miền là đủ để xác lập độ chính xác cấp thành phố

Hãy dùng các giá trị được API chấp nhận thay vì tự động dịch nhãn thông qua một thư viện locale không liên quan. Ví dụ, tài liệu tham chiếu hiện tại dùng uk cho Vương quốc Anh. Một chuẩn ngôn ngữ hoặc lãnh thổ tổng quát và các giá trị được chấp nhận của một API cụ thể không phải lúc nào cũng giống hệt nhau.

Chuẩn thẻ ngôn ngữ giải thích cách nhận diện ngôn ngữ có thể bao gồm nhiều phần con, nhưng nó không mở rộng các giá trị được hl chấp nhận. Tương tự, quy ước locale của Unicode giúp mô tả dữ liệu locale mà không thay thế hợp đồng tham số của một dịch vụ.

Giữ riêng ưu tiên quốc gia khỏi giới hạn ngôn ngữ

Đầu vào ngôn ngữ tìm kiếm không nên được hiểu như một đảm bảo rằng mọi tài liệu kết quả đều dùng ngôn ngữ đó. Thiết lập ngôn ngữ, giới hạn về ngôn ngữ tài liệu, và truy vấn được viết bằng một ngôn ngữ cụ thể là những điều khiển khác nhau.

Google mô tả cách ngôn ngữ ảnh hưởng đến kết quả tìm kiếm là liên quan đến nhiều hơn một tín hiệu. Trong thí nghiệm của bạn, hãy ghi lại ngôn ngữ truy vấn cũng như hl. Một truy vấn viết bằng tiếng Anh và một truy vấn được dịch sang tiếng Nhật là những thí nghiệm khác nhau ngay cả khi các đầu vào khác trùng nhau.

Tránh dịch truy vấn đồng thời cũng thay đổi quốc gia và thành phố trong cùng một phép so sánh. Nếu kết quả khác nhau, bạn sẽ không biết thay đổi chủ ý nào đã góp phần vào sự khác biệt đó. Trước tiên hãy cô lập một biến duy nhất; sau đó kiểm thử cấu hình đầy đủ mà ứng dụng của bạn cần.

Ví dụ về khả dụng ở bảy quốc gia

Bảy yêu cầu cho coffee, tất cả đều dùng hl=en, đã trả về các mảng organic không rỗng khi gl được thay đổi giữa các quốc gia sau. Mỗi yêu cầu đều hoàn tất với HTTP 200.

Country gl hl Returned Organic Records
United States us en 8
United Kingdom uk en 9
Germany de en 9
France fr en 10
Japan jp en 10
Canada ca en 9
Australia au en 9

Các số lượng này cho thấy dữ liệu đã được trả về cho những yêu cầu đã cấu hình đó. Chúng không đo lường độ chính xác quốc gia, độ chính xác ngôn ngữ, hay độ chính xác thành phố. Các yêu cầu không bao gồm thành phố trong location, và các điểm đến được trả về không được gán chân lý mặt đất địa lý độc lập.
Các số lượng khác nhau cũng không chứng minh rằng địa lý là nguyên nhân gây ra sự khác biệt. Mỗi lần gọi là một ảnh chụp nhanh tìm kiếm riêng biệt. Một nghiên cứu có kiểm soát cần có các quan sát lặp lại và một phép đo được xác định trước trước khi có thể đưa ra tuyên bố về quan hệ nhân quả hoặc độ chính xác.

Bắt đầu Scraping với Scrapeless

Tăng sức mạnh cho 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í ngay bây giờ trong Bảng điều khiển Scrapeless.

Lưu Ma Trận Quốc Gia Có Thể Tái Lập

Chương trình sau đây giữ nguyên đầu vào và toàn bộ phản hồi cho từng quốc gia và ghi rõ rằng việc xác thực vị trí là chưa hoàn thành. Điều này tránh việc biến một yêu cầu mạng thành công thành một điểm số độ chính xác không được hỗ trợ.

Điều kiện tiên quyết là Python, Requests và SCRAPELESS_API_KEY trong môi trường. Cài đặt Requests với python -m pip install requests, lưu chương trình dưới tên country_matrix.py và chạy python country_matrix.py. Mỗi lần chạy tạo một thư mục riêng dưới country-runs.

Trình trợ giúp xử lý các tác vụ đang chờ thông qua quy trình kết quả được ghi lại. Vòng lặp là tuần tự nên ví dụ này không giả định giới hạn đồng thời cụ thể theo tài khoản.

python Copy
import json
import os
import time
from pathlib import Path
from urllib.parse import quote

import requests

BASE = "https://api.scrapeless.com/api/v1/scraper"


def google_search(query):
    headers = {"x-api-token": os.environ["SCRAPELESS_API_KEY"]}
    response = requests.post(
        BASE + "/request", headers=headers,
        json={"actor": "scraper.google.search", "input": query},
        timeout=(10, 60), allow_redirects=False,
    )
    task_id = None
    for poll in range(11):
        response.raise_for_status()
        if response.status_code not in (200, 201):
            raise RuntimeError(f"Unexpected HTTP status: {response.status_code}")
        data = response.json()
        if not isinstance(data, dict):
            raise ValueError("Expected a JSON object")
        if response.status_code == 200:
            return data
        if task_id is None:
            task_id = data.get("taskId")
        if not isinstance(task_id, str) or not task_id:
            raise ValueError("Pending response has no taskId")
        if poll == 10:
            raise TimeoutError(f"Task still pending; retain taskId={task_id}")
        time.sleep(2)
        response = requests.get(
            BASE + "/result/" + quote(task_id, safe=""),
            headers=headers, timeout=(10, 30), allow_redirects=False,
        )


def organic_rows(data):
    rows = data.get("organic_results")
    if not isinstance(rows, list):
        raise ValueError("organic_results is missing or is not an array")
    if not all(isinstance(row, dict) for row in rows):
        raise ValueError("organic_results contains a non-object item")
    return rows


if __name__ == "__main__":
    from datetime import datetime, timezone
    run_dir = Path("country-runs") / datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S%fZ")
    run_dir.mkdir(parents=True)
    summary = []
    for country in ("us", "uk", "de", "fr", "jp", "ca", "au"):
        query = {"q": "coffee", "gl": country, "hl": "en"}
        data = google_search(query)
        (run_dir / f"{country}.json").write_text(json.dumps({"input": query, "response": data}, ensure_ascii=False, indent=2), encoding="utf-8")
        rows = organic_rows(data)
        summary.append({"gl": country, "hl": "en", "rows": len(rows), "location_verified": False})
    (run_dir / "summary.json").write_text(json.dumps(summary, indent=2), encoding="utf-8")
    print(json.dumps(summary))

Đoạn mã để location_verified ở trạng thái false ngay cả khi dữ liệu được trả về. Trường đó là một quyết định của ứng dụng, không phải trường được cho là tồn tại trong phản hồi API. Chỉ thay đổi nó sau khi hoàn thành việc xác thực độc lập theo định nghĩa của bạn.

Xác Thực Một Thành Phố Một Cách Độc Lập

Xác thực thành phố nên so sánh xuất xứ được yêu cầu với bằng chứng vị trí trong trang trả về và một đường cơ sở độc lập. Chỉ riêng các kết quả tự nhiên không rỗng là không đủ để thiết lập sự trùng khớp đó.

Bắt đầu với một truy vấn công khai có ý định địa phương, chẳng hạn như coffee shops. Giữ q, gl, hl, chế độ tìm kiếm và các bộ lọc khác cố định. Chạy một yêu cầu với vị trí Austin được chỉ định đầy đủ và một yêu cầu khác với vị trí Seattle được chỉ định đầy đủ. Hướng dẫn endpoint của API khuyến nghị các vị trí cấp thành phố và coi location và uule là loại trừ lẫn nhau.

Các yêu cầu chuẩn bị cho hai tên thành phố đó mỗi bên đều trả về chín bản ghi tự nhiên. Điều đó xác nhận khả năng có dữ liệu cho các đầu vào đã cấu hình. Nó không khẳng định rằng vị trí tìm kiếm hiển thị hoặc mọi kết quả đều khớp với thành phố dự định.

Trước khi thu thập một mẫu lớn hơn, hãy xác định bảng xác thực của bạn. Các cột hữu ích bao gồm thành phố được yêu cầu, bằng chứng vị trí hiển thị, mẫu địa chỉ doanh nghiệp địa phương nếu có, phương pháp đường cơ sở độc lập, thời gian quan sát và kết quả của người đánh giá. Lưu metadata.rawUrl liên quan khi có để có thể kiểm tra trang.

Sử dụng một đường cơ sở thủ công với các thiết lập được ghi lại hoặc một phép đo độc lập đáng tin cậy. Người đánh giá nên kiểm tra bằng chứng thay vì suy luận vị trí chỉ từ tên miền mã quốc gia. Một nhà xuất bản quốc gia có thể xuất hiện trong một tìm kiếm địa phương và một doanh nghiệp địa phương có thể sử dụng tên miền chung.

Đánh dấu kết quả là đã xác nhận, xung đột hoặc bằng chứng không đầy đủ. Đừng ép các quan sát không chắc chắn vào hạng mục đạt. Để công bố một tỷ lệ phần trăm độ chính xác, hãy xác định mẫu số và quy tắc phân xử trước khi xem kết quả.

Giữ Các So Sánh Liên Tục Ở Mức Có Thể So Sánh Được

Một tập dữ liệu bản địa hóa cần các đầu vào ổn định và ngữ cảnh thu thập hiển thị. Lưu các thiết lập được yêu cầu ngay cả khi phản hồi bao gồm metadata riêng của nó; hai bản ghi trả lời những câu hỏi khác nhau.

Ghi lại chính xác truy vấn, quốc gia và ngôn ngữ được yêu cầu, bất kỳ chuỗi vị trí nào, chế độ tìm kiếm, thời gian thu thập và kết quả phản hồi. Giữ riêng các đường cơ sở chỉ theo quốc gia với các thử nghiệm cụ thể theo thành phố. Đừng so sánh một kết quả tìm kiếm web trên máy tính với một kết quả chế độ Local như thể chỉ thành phố thay đổi.

Đối với quy trình sản xuất, hãy quyết định điều gì sẽ xảy ra khi thiếu bằng chứng vị trí. Giữ quan sát đó để xem xét sẽ nhiều thông tin hơn là trình bày nó như một ảnh chụp thành phố đã được xác thực. Sử dụng giá hiện tại để lập ngân sách cho các quan sát lặp lại và các lần kiểm tra độc lập riêng biệt.

Kết Luận: Xác Thực Vị Trí Bạn Tuyên Bố

Đầu vào quốc gia, ngôn ngữ và thành phố khiến việc thu thập tìm kiếm có chủ đích hơn, nhưng tuyên bố vị trí mạnh nhất phải khớp với bằng chứng. Bắt đầu với một ma trận cấu hình nhỏ, lưu các phản hồi và xác thực địa lý dự định trước khi xây dựng báo cáo cấp thành phố.
Trang sản phẩm Google Search API giới thiệu dịch vụ; hợp đồng tham số kiểm soát việc triển khai. Hãy coi phản hồi thành công là điểm bắt đầu của việc xác thực, không phải kết thúc của nó.

Xây Dựng Quy Trình Dữ Liệu Tìm Kiếm Của Bạn

Tham gia cộng đồng các nhà phát triển đang làm việc với dữ liệu tìm kiếm: Discord · Telegram.

Tạo 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ập lịch một đợt thu thập lớn hơn.

Câu Hỏi Thường Gặp

Hỏi: gl và hl có thể thay thế cho nhau không?

Không. gl chọn quốc gia tìm kiếm và hl chọn ngôn ngữ tìm kiếm. Hãy lưu trữ và kiểm thử chúng riêng biệt.

Hỏi: hl=en có giới hạn mọi kết quả ở tiếng Anh không?

Đừng coi đó là một đảm bảo về mọi tài liệu kết quả. Cài đặt ngôn ngữ tìm kiếm và các ràng buộc về ngôn ngữ tài liệu là hai khái niệm khác nhau.

Hỏi: location và uule có thể được cung cấp cùng nhau không?

Không. Hợp đồng tham số hiện tại khiến chúng loại trừ lẫn nhau. Hãy chọn cơ chế điều khiển được hỗ trợ phù hợp với cấu hình của bạn.

Hỏi: Bảy phản hồi không rỗng từ bảy quốc gia có chứng minh độ chính xác ở bảy quốc gia không?

Không. Chúng chỉ cho thấy dữ liệu được trả về cho bảy cấu hình được yêu cầu. Độ chính xác cần được chứng minh bằng bằng chứng vị trí độc lập.

Hỏi: Một tên miền mã quốc gia có đủ để chứng minh mức độ liên quan địa phương không?

Không. Việc đặt tên miền một mình không xác định địa lý của trang hoặc nguồn gốc được thể hiện bởi SERP.

Hỏi: Ví dụ này có yêu cầu trình duyệt hoặc tác nhân AI không?

Không. Nó sử dụng Python và HTTP API. Việc xác thực hình ảnh độc lập có thể liên quan đến trình duyệt, nhưng đó là một bước xác minh riêng biệt.

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.

Bài viết phổ biến nhất

Danh mục