gl vs hl vs localização: Configurações de localidade da API de Pesquisa do Google
Senior Web Scraping Engineer
Resumo:
- gl, hl e location descrevem entradas de busca diferentes. Mantenha país, idioma e origem da busca separados.
- Sete requisições de países bem-sucedidas demonstram dados retornados. Elas não estabelecem uma porcentagem de exatidão em nível de cidade.
- Um teste de localização útil altera uma variável por vez. Fixe a consulta e outras configurações antes de comparar saídas.
- Configurações solicitadas pertencem ao lado das evidências observadas. Marque uma localização como não verificada até que uma verificação independente a comprove.
Introdução: Um Código de País é Apenas Parte de uma Busca
Resultados de busca dependem de mais do que uma palavra-chave. Uma preferência de país, configuração de idioma e origem local fornecem contexto, e podem produzir efeitos diferentes.
Este guia explica gl versus hl versus location para a Scrapeless Google Search API. Ele mostra uma matriz de requisições para sete países e um método para verificar o comportamento local de forma independente. Ele não trata uma resposta não vazia como prova de que uma determinada cidade foi representada com precisão.
O contrato de parâmetros do Google Search é a referência para controles aceitos. O fluxo de trabalho de requisição do ator permanece o mesmo à medida que você altera esses controles dentro de input.
O Que Cada Parâmetro Controla
O parâmetro gl seleciona o país da busca, hl seleciona o idioma da busca, e location especifica a origem da busca solicitada. Essas entradas devem ser armazenadas separadamente em um registro de coleção.
| Parameter | Example | What Not to Infer |
|---|---|---|
gl |
us |
Que todo resultado deve pertencer a uma organização dos EUA |
hl |
en |
Que toda página de destino deve estar em inglês |
location |
Austin, Texas, United States |
Que todo resultado local foi geocodificado de forma independente |
google_domain |
google.com |
Que apenas um nome de domínio estabelece a precisão da cidade |
Use os valores aceitos pela API em vez de traduzir automaticamente rótulos por meio de uma biblioteca de locale não relacionada. Por exemplo, a referência atual usa uk para o Reino Unido. Um padrão geral de idioma ou território e os valores aceitos por uma API específica nem sempre são idênticos.
O padrão de tags de idioma explica como a identificação de idioma pode incluir diversos subtags, mas não amplia os valores aceitos por hl. Da mesma forma, as convenções de locale do Unicode ajudam a descrever dados de locale sem substituir o contrato de parâmetros de um serviço.
Mantenha a Preferência de País Separada da Restrição de Idioma
A entrada de idioma de busca não deve ser interpretada como uma garantia de que todo documento de resultado usa esse idioma. Uma configuração de idioma, uma restrição sobre o idioma do documento e uma consulta escrita em um determinado idioma são controles distintos.
O Google descreve como o idioma afeta os resultados de busca como algo que envolve mais de um sinal. Em seu experimento, registre o idioma da consulta assim como hl. Uma consulta escrita em inglês e outra traduzida para japonês são experimentos diferentes, mesmo que as outras entradas coincidam.
Evite traduzir a consulta enquanto também altera país e cidade na mesma comparação. Se os resultados diferirem, você não saberá qual mudança deliberada de entrada contribuiu para a diferença. Primeiro isole uma única variável; depois teste a configuração completa de que sua aplicação precisa.
Um Exemplo de Disponibilidade em Sete Países
Sete requisições para coffee, todas usando hl=en, retornaram arrays orgânicos não vazios quando gl foi alterado entre os seguintes países. Cada uma foi concluída com 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 |
Essas contagens demonstram que dados foram retornados para essas requisições configuradas. Elas não medem a precisão em nível de país, a precisão de idioma ou a precisão em nível de cidade. As requisições não incluíram uma cidade em location, e os destinos retornados não receberam uma verificação geográfica independente como verdade de base.
As diferentes contagens também não provam que a geografia causou as diferenças. Cada chamada é uma captura de pesquisa separada. Um estudo controlado precisa de observações repetidas e de uma medição pré-definida antes que possa fazer uma afirmação causal ou de precisão.
Comece a fazer scraping com o Scrapeless
Potencialize o seu fluxo de trabalho de web scraping e automação com o Scrapeless!
Cadastre-se hoje e receba US$ 5 em crédito gratuito — sem necessidade de cartão de crédito.Solicite seu crédito gratuito agora no Painel do Scrapeless.
Salve uma Matriz de Países Reproduzível
O programa a seguir mantém o exato input e a resposta completa para cada país e rotula explicitamente a validação de localização como incompleta. Isso evita transformar uma requisição de rede bem-sucedida em uma pontuação de precisão sem suporte.
Os pré-requisitos são Python, Requests e SCRAPELESS_API_KEY no ambiente. Instale Requests com python -m pip install requests, salve o programa como country_matrix.py e execute python country_matrix.py. Cada execução cria um diretório separado em country-runs.
O helper lida com tarefas pendentes por meio do fluxo de resultados documentado. O loop é sequencial, portanto o exemplo não assume um limite de concorrência específico da conta.
python
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 código mantém location_verified como falso mesmo quando os dados são retornados. Esse campo é uma decisão da aplicação, não um campo que se afirma existir na resposta da API. Altere-o apenas depois de concluir sua validação independente definida.
Valide uma Cidade de Forma Independente
Uma validação de cidade deve comparar a origem solicitada com a evidência de localização na página retornada e uma referência independente. Resultados orgânicos não vazios por si só não estabelecem essa correspondência.
Comece com uma consulta pública que tenha intenção local, como coffee shops. Mantenha q, gl, hl, o modo de pesquisa e outros filtros fixos. Execute uma requisição com uma localização de Austin totalmente especificada e outra com uma localização de Seattle totalmente especificada. A orientação do endpoint da API recomenda localizações em nível de cidade e trata location e uule como mutuamente exclusivos.
As requisições de preparação para esses dois nomes de cidade retornaram cada uma nove registros orgânicos. Isso confirma a disponibilidade de dados para os inputs configurados. Não estabelece que a localização de pesquisa visível ou cada resultado corresponderam à cidade pretendida.
Antes de coletar uma amostra maior, defina sua planilha de validação. Colunas úteis incluem cidade solicitada, evidência de localização visível, endereços de empresas locais de amostra quando disponíveis, método de referência independente, horário da observação e resultado do revisor. Salve o metadata.rawUrl associado quando presente para que a página possa ser inspecionada.
Use uma linha de base manual com configurações documentadas ou uma medição independente confiável. Um revisor deve inspecionar a evidência em vez de inferir a localização apenas a partir de um domínio com código de país. Um veículo de mídia nacional pode aparecer em uma pesquisa local, e uma empresa local pode usar um domínio genérico.
Marque os resultados como confirmados, conflitantes ou com evidência insuficiente. Não force observações incertas em uma categoria de aprovação. Para publicar uma porcentagem de precisão, defina o denominador e a regra de adjudicação antes de olhar os resultados.
Mantenha Comparações Contínuas Comparáveis
Um conjunto de dados de localização precisa de inputs estáveis e contexto de coleta visível. Salve as configurações solicitadas mesmo que a resposta inclua seus próprios metadados; os dois registros respondem a questões diferentes.
Registre exatamente a consulta, o país e o idioma solicitados, qualquer string de localização, modo de pesquisa, horário da coleta e resultado da resposta. Mantenha linhas de base somente de país distintas de experimentos específicos de cidade. Não compare um resultado de pesquisa na web em desktop com um resultado em modo Local como se apenas a cidade tivesse mudado.
Para um fluxo de trabalho de produção, decida o que deve acontecer quando a evidência de localização estiver ausente. Reter essa observação para revisão é mais informativo do que apresentá-la como um snapshot de cidade validado. Use a precificação atual para orçar observações repetidas e verificações independentes separadamente.
Conclusão: Valide a Localização que Você Afirma
Inputs de país, idioma e cidade tornam a coleta de pesquisa mais deliberada, mas a afirmação de localização mais forte deve corresponder à evidência. Comece com uma pequena matriz de configuração, preserve as respostas e valide a geografia pretendida antes de criar relatórios em nível de cidade.
A página do produto Google Search API apresenta o serviço; o contrato de parâmetros controla a implementação. Trate uma resposta bem-sucedida como o início da validação, não como o fim dela.
Crie Seu Workflow de Dados de Busca
Junte-se aos desenvolvedores que trabalham com dados de busca em nossa comunidade: Discord · Telegram.
Crie uma conta Scrapeless e aplique este tutorial a um pequeno conjunto de consultas antes de programar uma coleta maior.
FAQ
P: gl e hl são intercambiáveis?
Não. gl seleciona o país de busca e hl seleciona o idioma de busca. Armazene e teste-os separadamente.
P: hl=en restringe todos os resultados ao inglês?
Não o trate como uma garantia sobre cada documento de resultado. Configurações de idioma de busca e restrições de idioma de documento são conceitos diferentes.
P: Location e uule podem ser fornecidos juntos?
Não. O contrato de parâmetros atual os torna mutuamente exclusivos. Escolha o controle compatível que se ajusta à sua configuração.
P: Sete respostas não vazias para países provam precisão em sete países?
Não. Elas mostram dados retornados para sete configurações solicitadas. A precisão exige evidências de localização verificadas de forma independente.
P: Um domínio com código de país é prova suficiente de relevância local?
Não. A nomenclatura de domínio por si só não estabelece a geografia da página ou a origem representada pela SERP.
P: O exemplo exige um navegador ou agente de IA?
Não. Ele usa Python e a API HTTP. A validação visual independente pode envolver um navegador, mas isso é uma etapa de verificação separada.
Na Scorretless, acessamos apenas dados disponíveis ao público, enquanto cumprem estritamente as leis, regulamentos e políticas de privacidade do site aplicáveis. O conteúdo deste blog é apenas para fins de demonstração e não envolve atividades ilegais ou infratoras. Não temos garantias e negamos toda a responsabilidade pelo uso de informações deste blog ou links de terceiros. Antes de se envolver em qualquer atividade de raspagem, consulte seu consultor jurídico e revise os termos de serviço do site de destino ou obtenha as permissões necessárias.



