Localizações e idiomas: gl, hl, location, google_domain e device

Qual é a diferença entre gl, hl e location?

gl indica de qual país você quer os resultados. hl indica qual idioma a pessoa lê, o que muda a interface e muitas vezes as perguntas e os snippets. location restringe o país a uma cidade ou região, o que importa assim que uma consulta tem intenção local.

Eles se combinam livremente. Um falante de francês na Suíça é gl=ch, hl=fr. Uma pesquisa em inglês a partir de Berlim é gl=de, hl=en, location=Berlin, Berlin, Germany. Mantenha gl e o país de location iguais: uma cidade em um país com gl de outro gera resultados que nenhum visitante real vê.

Como faço para segmentar uma cidade?

Escreva o lugar em inglês, da menor unidade para a maior: City, Region, Country. Exemplos: Austin, Texas, United States, Manchester, England, United Kingdom, Munich, Bavaria, Germany, Lyon, Auvergne-Rhone-Alpes, France. Use o nome da cidade, não uma rua ou um CEP.

Verifique search_parameters.location na resposta: ele mostra o lugar que foi aplicado. Um valor que não pode ser usado retorna 400 invalid_parameter e não custa nada, então você pode testar uma lista de lugares gastando pouco.

# The same query from two cities: compare the local packs
for city in "Austin, Texas, United States" "Denver, Colorado, United States"; do
  curl -sG "https://serpcrypto.com/api/v1/search" \
    -H "Authorization: Bearer $SERPCRYPTO_API_KEY" \
    --data-urlencode "q=emergency plumber" \
    --data-urlencode "location=$city" \
    -d gl=us -d hl=en -d device=mobile \
    | jq -r --arg city "$city" '.local_results[]? | "\($city)\t\(.position)\t\(.title)"'
done

Qual domínio do Google devo usar?

Normalmente nenhum: deixe google_domain de fora e a API usa o domínio do país gl, como na tabela acima. Defina-o apenas para reproduzir uma configuração específica, por exemplo google.com com gl=gb.

O domínio sozinho não define o país dos resultados. gl e location fazem a maior parte do trabalho, e é por isso que a resposta registra os três em search_parameters.

Os resultados mobile e desktop são diferentes?

Muitas vezes, sim. A página mobile pode ordenar os blocos de forma diferente, mostrar mais resultados locais para intenções de proximidade e encurtar os snippets. Se seus visitantes usam principalmente celular, rastreie device=mobile; para uma visão completa, rastreie os dois e armazene o dispositivo junto com cada ranking.

Cada dispositivo é uma pesquisa separada, então rastrear os dois dobra os créditos para essas palavras-chave. A US$ 0,56/1K pesquisas no pacote 100.000 pesquisas, 1.000 palavras-chave em dois dispositivos por 30 dias usam 60.000 pesquisas.

Como comparo vários países em um único script?

Percorra uma lista de mercados e guarde o que a API aplicou. O exemplo em Python envia uma consulta para três países, cada um com uma cidade, e imprime o domínio usado e o primeiro link.

import os

import requests

MARKETS = [
    {"gl": "de", "hl": "de", "location": "Munich, Bavaria, Germany"},
    {"gl": "fr", "hl": "fr", "location": "Lyon, Auvergne-Rhone-Alpes, France"},
    {"gl": "br", "hl": "pt-BR", "location": "Curitiba, State of Parana, Brazil"},
]

for market in MARKETS:
    r = requests.get(
        "https://serpcrypto.com/api/v1/search",
        params={"q": "running shoes", **market},
        headers={"Authorization": "Bearer " + os.environ["SERPCRYPTO_API_KEY"]},
        timeout=60,
    )
    r.raise_for_status()
    applied = r.json()["search_parameters"]
    top = r.json().get("organic_results", [])[:1]
    print(applied["gl"], applied.get("google_domain"), [x["link"] for x in top])

O Bing aceita os mesmos parâmetros?

Sim para q, gl, hl, device e page: use os mesmos códigos com engine=bing. google_domain não se aplica ao Bing e é ignorado. A resposta tem a mesma estrutura, com organic_results e related_searches; veja a página do Bing para os casos de uso.