Ubicaciones e idiomas: gl, hl, location, google_domain y device

¿Cuál es la diferencia entre gl, hl y location?

gl indica de qué país quieres los resultados. hl indica en qué idioma lee la persona, lo que cambia la interfaz y a menudo las preguntas y los fragmentos. location reduce el país a una ciudad o región, lo que importa en cuanto una consulta tiene intención local.

Se combinan libremente. Un francófono en Suiza es gl=ch, hl=fr. Una búsqueda en inglés desde Berlín es gl=de, hl=en, location=Berlin, Berlin, Germany. Mantén gl y el país de location iguales: una ciudad de un país con gl de otro da resultados que ningún visitante real ve.

¿Cómo apunto a una ciudad?

Escribe el lugar en inglés, de la unidad más pequeña a la más grande: City, Region, Country. Ejemplos: Austin, Texas, United States, Manchester, England, United Kingdom, Munich, Bavaria, Germany, Lyon, Auvergne-Rhone-Alpes, France. Usa el nombre de la ciudad, no una calle ni un código postal.

Comprueba search_parameters.location en la respuesta: muestra el lugar que se aplicó. Un valor que no se puede usar devuelve 400 invalid_parameter y no cuesta nada, así que puedes probar una lista de lugares a bajo coste.

# 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

¿Qué dominio de Google debería usar?

Normalmente ninguno: omite google_domain y la API usa el dominio del país de gl, como en la tabla de arriba. Defínelo solo para reproducir una configuración concreta, por ejemplo google.com con gl=gb.

El dominio por sí solo no define el país de los resultados. gl y location hacen la mayor parte del trabajo, por eso la respuesta registra los tres en search_parameters.

¿Difieren los resultados de móvil y escritorio?

A menudo sí. La página de móvil puede ordenar los bloques de otra forma, mostrar más resultados locales para intenciones cercanas y recortar más los snippets. Si tus visitantes usan sobre todo el teléfono, haz seguimiento de device=mobile; para una visión completa, haz seguimiento de ambos y guarda el dispositivo con cada ranking.

Cada dispositivo es una búsqueda distinta, así que hacer seguimiento de ambos duplica los créditos de esas palabras clave. A 0,56 US$/1K búsquedas en el pack 100.000 búsquedas, 1,000 palabras clave en dos dispositivos durante 30 días usan 60,000 búsquedas.

¿Cómo comparo varios países en un solo script?

Recorre una lista de mercados y guarda lo que aplicó la API. El ejemplo en Python envía una consulta a tres países con una ciudad cada uno e imprime el dominio usado y el primer enlace.

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])

¿Bing acepta los mismos parámetros?

Sí para q, gl, hl, device y page: usa los mismos códigos con engine=bing. google_domain no se aplica a Bing y se ignora. La respuesta tiene la misma estructura, con organic_results y related_searches; consulta la página de Bing para ver sus casos de uso.