Loading Light/Dark Toggle
Volver al blog

gl vs hl vs location: Configuración de idioma y ubicación de la API de Búsqueda de Google

Alex Johnson
Alex Johnson

Senior Web Scraping Engineer

12-Nov-2026

Resumen:

  • gl, hl y location describen diferentes entradas de búsqueda. Mantén país, idioma y origen de búsqueda separados.
  • Siete solicitudes de país exitosas demuestran datos devueltos. No establecen un porcentaje de precisión a nivel de ciudad.
  • Una prueba de localización útil cambia una variable a la vez. Fija la consulta y otros ajustes antes de comparar resultados.
  • Los ajustes solicitados pertenecen junto a la evidencia observada. Marca una ubicación como no verificada hasta que una comprobación independiente la respalde.

Introducción: Un código de país es solo una parte de una búsqueda

Los resultados de búsqueda dependen de más que una palabra clave. Una preferencia de país, una configuración de idioma y un origen local proporcionan contexto, y pueden producir efectos diferentes.

Esta guía explica gl frente a hl frente a location para la API de Búsqueda de Google de Scrapeless. Muestra una matriz de solicitudes de siete países y un método para comprobar el comportamiento local de forma independiente. No trata una respuesta no vacía como prueba de que una ciudad en particular haya sido representada con precisión.

El contrato de parámetros de Búsqueda de Google es la referencia para los controles aceptados. El flujo de trabajo de solicitud del actor se mantiene igual mientras cambias esos controles dentro de input.

Qué controla cada parámetro

El parámetro gl selecciona el país de búsqueda, hl selecciona el idioma de búsqueda y location especifica el origen de búsqueda solicitado. Estas entradas deben almacenarse por separado en un registro de colección.

Parameter Example What Not to Infer
gl us Cada resultado debe pertenecer a una organización de EE. UU.
hl en Cada página de destino debe estar en inglés
location Austin, Texas, United States Cada resultado local ha sido geocodificado de forma independiente
google_domain google.com Un nombre de dominio por sí solo establece la precisión de la ciudad

Usa los valores aceptados por la API en lugar de traducir automáticamente las etiquetas mediante una librería de configuración regional no relacionada. Por ejemplo, la referencia actual usa uk para el Reino Unido. Un estándar general de idioma o territorio y los valores aceptados por una API en particular no siempre son idénticos.

El estándar de etiquetas de idioma explica cómo la identificación de idioma puede incluir varios subetiquetas, pero no amplía los valores aceptados por hl. Del mismo modo, las convenciones de configuración regional de Unicode ayudan a describir datos de configuración regional sin reemplazar el contrato de parámetros de un servicio.

Mantén separada la preferencia de país de la restricción de idioma

La entrada del idioma de búsqueda no debe interpretarse como una garantía de que cada documento de resultados use ese idioma. Una configuración de idioma, una restricción sobre el idioma del documento y una consulta escrita en un idioma concreto son controles distintos.

Google describe cómo el idioma afecta a los resultados de la búsqueda como algo que implica más de una señal. En tu experimento, registra el idioma de la consulta así como hl. Una consulta escrita en inglés y otra traducida al japonés son experimentos diferentes incluso si las demás entradas coinciden.

Evita traducir la consulta mientras también cambias país y ciudad en la misma comparación. Si los resultados difieren, no sabrías qué cambio de entrada deliberado contribuyó a la diferencia. Primero aísla una sola variable; luego prueba la configuración completa que tu aplicación necesita.

Un ejemplo de disponibilidad en siete países

Siete solicitudes para coffee, todas usando hl=en, devolvieron arreglos orgánicos no vacíos cuando gl se cambió entre los siguientes países. Cada una se completó con 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

Estos recuentos demuestran que se devolvieron datos para esas solicitudes configuradas. No miden la precisión de país, de idioma ni de ciudad. Las solicitudes no incluían una ciudad en location y a los destinos devueltos no se les asignó una verdad de base geográfica independiente.
Las diferentes cifras tampoco demuestran que la geografía haya causado las diferencias. Cada llamada es una instantánea de búsqueda independiente. Un estudio controlado necesita observaciones repetidas y una medición predefinida antes de poder hacer una afirmación causal o de precisión.

Empieza a hacer scraping con Scrapeless

Potencia tu flujo de trabajo de web scraping y automatización con Scrapeless.
Regístrate hoy y obtén 5 USD de crédito gratuito — no se requiere tarjeta de crédito.

Reclama tu crédito gratuito ahora en el Panel de Scrapeless.

Guarda una matriz de países reproducible

El siguiente programa conserva la entrada exacta y la respuesta completa para cada país y etiqueta explícitamente la validación de ubicación como incompleta. Esto evita convertir una solicitud de red exitosa en una puntuación de precisión no admitida.

Los requisitos previos son Python, Requests y SCRAPELESS_API_KEY en el entorno. Instala Requests con python -m pip install requests, guarda el programa como country_matrix.py y ejecuta python country_matrix.py. Cada ejecución crea un directorio independiente bajo country-runs.

El asistente gestiona las tareas pendientes mediante el flujo de trabajo de resultados documentado. El bucle es secuencial, por lo que el ejemplo no asume un límite de concurrencia específico de la cuenta.

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

El código deja location_verified en falso incluso cuando se devuelven datos. Ese campo es una decisión de la aplicación, no un campo cuya existencia se afirme en la respuesta de la API. Cámbialo solo después de completar tu validación independiente definida.

Valida una ciudad de manera independiente

Una validación de ciudad debe comparar el origen solicitado con la evidencia de ubicación en la página devuelta y una referencia independiente. Los resultados orgánicos no vacíos por sí solos no establecen esa coincidencia.

Empieza con una consulta pública que tenga intención local, como coffee shops. Mantén q, gl, hl, el modo de búsqueda y otros filtros fijos. Ejecuta una solicitud con una ubicación de Austin completamente especificada y otra con una ubicación de Seattle completamente especificada. La guía del endpoint de la API recomienda ubicaciones a nivel de ciudad y trata location y uule como mutuamente excluyentes.

Las solicitudes de preparación para esos dos nombres de ciudad devolvieron cada una nueve registros orgánicos. Eso confirma la disponibilidad de datos para las entradas configuradas. No establece que la ubicación de búsqueda visible o cada resultado coincidieran con la ciudad prevista.

Antes de recopilar una muestra más grande, define tu hoja de validación. Entre las columnas útiles se incluyen la ciudad solicitada, evidencia visible de ubicación, direcciones de negocios locales de muestra cuando estén disponibles, método de referencia independiente, hora de la observación y resultado del revisor. Guarda el metadata.rawUrl asociado cuando esté presente para que la página se pueda inspeccionar.

Usa una referencia manual con configuraciones documentadas o una medición independiente confiable. Un revisor debe inspeccionar la evidencia en lugar de inferir la ubicación únicamente a partir de un dominio con código de país. Un medio nacional puede aparecer en una búsqueda local, y un negocio local puede usar un dominio genérico.

Marca los resultados como confirmados, en conflicto o con evidencia insuficiente. No fuerces observaciones inciertas en una categoría aprobatoria. Para publicar un porcentaje de precisión, define el denominador y la regla de adjudicación antes de examinar los resultados.

Mantén comparables las comparaciones continuas

Un conjunto de datos de localización necesita entradas estables y un contexto de recopilación visible. Guarda las configuraciones solicitadas incluso si la respuesta incluye sus propios metadatos; los dos registros responden a preguntas distintas.

Registra la consulta exactamente, el país e idioma solicitados, cualquier cadena de ubicación, el modo de búsqueda, la hora de recopilación y el resultado de la respuesta. Mantén las referencias solo por país diferenciadas de los experimentos específicos de ciudad. No compares un resultado de búsqueda web de escritorio con un resultado en modo Local como si solo hubiera cambiado la ciudad.

Para un flujo de trabajo de producción, decide qué debería ocurrir cuando falte evidencia de ubicación. Retener esa observación para revisión es más informativo que presentarla como una instantánea de ciudad validada. Usa la tarificación actual para presupuestar por separado las observaciones repetidas y las comprobaciones independientes.

Conclusión: valida la ubicación que afirmas

Las entradas de país, idioma y ciudad hacen que la recopilación de búsquedas sea más deliberada, pero la afirmación de ubicación más sólida debe coincidir con la evidencia. Comienza con una pequeña matriz de configuración, conserva las respuestas y valida la geografía prevista antes de crear informes a nivel de ciudad.
La página de producto de la Google Search API presenta el servicio; el contrato de parámetros controla la implementación. Trata una respuesta exitosa como el inicio de la validación, no como el final.

Crea tu flujo de trabajo de datos de búsqueda

Únete a desarrolladores que trabajan con datos de búsqueda en nuestra comunidad: Discord · Telegram.

Crea una cuenta de Scrapeless y aplica este tutorial a un conjunto pequeño de consultas antes de programar una recolección más grande.

Preguntas frecuentes

P: ¿Son gl y hl intercambiables?

No. gl selecciona el país de búsqueda y hl selecciona el idioma de búsqueda. Guárdalos y pruébalos por separado.

P: ¿hl=en restringe cada resultado al inglés?

No lo trates como una garantía sobre cada documento de resultado. La configuración de idioma de búsqueda y las restricciones de idioma del documento son conceptos diferentes.

P: ¿Se pueden proporcionar location y uule juntos?

No. El contrato de parámetros actual los hace mutuamente excluyentes. Elige el control admitido que se ajuste a tu configuración.

P: ¿Siete respuestas de países no vacías prueban precisión en siete países?

No. Muestran datos devueltos para siete configuraciones solicitadas. La precisión requiere evidencia de ubicación comprobada de forma independiente.

P: ¿Es un dominio con código de país una prueba suficiente de relevancia local?

No. La nomenclatura del dominio por sí sola no establece la geografía de la página ni el origen representado por la SERP.

P: ¿El ejemplo requiere un navegador o un agente de IA?

No. Usa Python y la API HTTP. La validación visual independiente puede implicar un navegador, pero eso es una etapa de verificación separada.

En Scrapeless, solo accedemos a datos disponibles públicamente y cumplimos estrictamente con las leyes, regulaciones y políticas de privacidad del sitio web aplicables. El contenido de este blog es sólo para fines de demostración y no implica ninguna actividad ilegal o infractora. No ofrecemos garantías y renunciamos a toda responsabilidad por el uso de la información de este blog o enlaces de terceros. Antes de realizar cualquier actividad de scraping, consulte a su asesor legal y revise los términos de servicio del sitio web de destino u obtenga los permisos necesarios.

Artículos más populares

Catalogar