Respuesta JSON de la API de Búsqueda de Google: organic_results explicado
Senior Web Scraping Engineer
Resumen rápido:
- organic_results es una colección de registros de búsqueda orgánica. Lee la posición devuelta, el título, el fragmento y el enlace de cada registro sin mezclar otros módulos de búsqueda.
- La posición devuelta y el orden del arreglo son valores distintos. Conserva ambos al preparar un conjunto de datos.
- Un enlace devuelto no es automáticamente una URL final verificada. Mantén separados los estados de intermediario y candidato de destino.
- Los campos faltantes deben seguir siendo visibles. Un fragmento ausente, una cadena vacía y un registro malformado requieren un manejo diferente.
Introducción: Lee la respuesta antes de aplanarla
Una respuesta JSON de la API de Búsqueda de Google puede contener resultados orgánicos junto con paneles de conocimiento, secciones locales, preguntas relacionadas y otros módulos que dependen de la consulta. Aplanar cada objeto que contiene un campo title produce un conjunto de datos con significados mezclados.
Este tutorial se centra en organic_results en la Scrapeless Google Search API. El objetivo es un formato de registro pequeño e inspeccionable para títulos, fragmentos, posiciones y enlaces. No construye un rastreador de rankings ni afirma que cada enlace devuelto ya haya sido verificado contra una URL de destino final.
El ejemplo de respuesta de Búsqueda de Google y el flujo de trabajo de la solicitud del actor proporcionan el contexto de la solicitud. Aquí, el trabajo útil comienza después de que se ha guardado una respuesta completada.
Qué contiene organic_results
El campo organic_results es un arreglo de objetos de resultados orgánicos, con campos cuya disponibilidad debe comprobarse en cada elemento. Un registro no es una copia completa de la página de destino.
| Field | Meaning in the Dataset | Handling Rule |
|---|---|---|
position |
Posición devuelta por la API | Consérvala sin volver a calcularla |
title |
Título del resultado | Mantén los valores nulos o ausentes diferenciables del texto |
snippet |
Extracto del resultado de búsqueda | Trátalo como una observación de búsqueda, no como contenido completo de la página |
link |
URL de resultado devuelta | Clasifícala antes del emparejamiento de destino en etapas posteriores |
redirect_link |
Enlace adicional en formato de redirección cuando está presente | Almacénalo por separado; no reemplaces link automáticamente |
source |
Etiqueta de origen mostrada cuando está disponible | No asumas que es un dominio registrable |
La tabla describe campos que deben inspeccionarse, no una garantía de que cada elemento contenga cada clave. La referencia de parámetros define los controles de la solicitud; no debe leerse como una promesa de módulos de resultados idénticos en todas las consultas.
JSON permite valores como null, cadenas y arreglos, tal como se describe en la especificación JSON. Un formato de respuesta flexible aún necesita un contrato deliberado por parte del consumidor. Decide qué valores faltantes puede conservar tu aplicación y cuáles deberían detener el procesamiento.
Conserva la posición sin inventar un ranking
Mantén position devuelto, el índice del arreglo y el desplazamiento de la solicitud como campos separados al combinar páginas. Cada valor describe una parte diferente de la observación.
El índice del arreglo registra dónde apareció un elemento en el arreglo devuelto. La posición devuelta es el valor proporcionado por la API. El desplazamiento de la solicitud registra qué página solicitaste. Sumar un desplazamiento a una posición sin antes establecer la semántica de esa posición puede contar dos veces un desplazamiento o implicar un ranking que la respuesta no declaró.
No cuentes anuncios, un grafo de conocimiento y registros orgánicos en una sola secuencia a menos que hayas definido y validado esa medida personalizada. Un desarrollador que necesite rankings orgánicos debe conservar suficiente contexto para inspeccionar la página de búsqueda que produjo el registro.
Almacena el JSON sin modificar incluso si tu base de datos solo necesita unas pocas columnas. Más adelante podrías necesitar un campo que el primer script de normalización descartó, o podrías necesitar distinguir un campo ausente de un valor introducido por tu propia transformación.
Clasifica los enlaces antes de resolverlos
La clasificación de una URL es una decisión de enrutamiento para validaciones posteriores; no es una prueba de un destino final. La respuesta base para coffee incluía valores link directos y valores redirect_link de Google separados en los mismos registros orgánicos.
Inspecciona el esquema, el nombre de host y la ruta en lugar de comprobar si una cadena simplemente contiene la palabra Google. El modelo de componentes de URI hace que esas partes sean explícitas. Una URL con un nombre de marca familiar dentro de su ruta no está necesariamente alojada por esa marca.
Clasificaciones útiles incluyen un valor ausente, un enlace relativo, un intermediario de Google observado y un candidato de URL absoluta. Conserva los valores opacos en los enlaces /goto?url=.... Un parámetro opaco no es un destino que se pueda recuperar adivinando un esquema de decodificació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.
Normaliza una respuesta JSON guardada
El siguiente programa crea registros normalizados sin visitar ninguna URL de resultados. Conserva ambos campos de enlace y adjunta una clasificación local para revisión posterior.
Los prerrequisitos son Python y una respuesta completada de Google Search guardada como serp.json. Guarda el propio objeto de respuesta de la API, no un contenedor personalizado que incluya tus metadatos de registro. La solicitud de inicio rápido proporciona esa respuesta. Guarda el script como normalize_organic.py y ejecuta python normalize_organic.py junto al archivo JSON.
El nombre de host establecido en el ejemplo cubre los hosts de Google observados en esta familia de respuestas. No es intencionalmente un registro global de todos los dominios de Google. Amplíalo solo cuando tus respuestas reales justifiquen la adición. Otras URLs absolutas siguen siendo candidatas no verificadas.
python
import json
from pathlib import Path
from urllib.parse import urlsplit
def classify_link(value):
if not isinstance(value, str) or not value.strip():
return "missing"
if value.startswith("/"):
return "relative_review"
try:
parts = urlsplit(value)
host = (parts.hostname or "").lower()
except ValueError:
return "invalid_review"
if parts.scheme not in ("https", "http") or not host:
return "invalid_review"
# These are observed Google hosts, not a global Google-domain registry.
google_hosts = {"google.com", "www.google.com"}
if host in google_hosts and parts.path in ("/url", "/goto"):
return "google_intermediary"
if host in google_hosts:
return "google_page_review"
return "absolute_candidate"
data = json.loads(Path("serp.json").read_text(encoding="utf-8"))
if not isinstance(data, dict) or not isinstance(data.get("organic_results"), list):
raise ValueError("Expected an object with an organic_results array")
normalized = []
for index, row in enumerate(data["organic_results"], start=1):
if not isinstance(row, dict):
raise ValueError(f"Invalid result at index {index}")
normalized.append({
"array_index": index,
"returned_position": row.get("position"),
"title": row.get("title"),
"snippet": row.get("snippet"),
"link": row.get("link"),
"redirect_link": row.get("redirect_link"),
"link_state": classify_link(row.get("link")),
})
Path("organic-normalized.json").write_text(
json.dumps(normalized, ensure_ascii=False, indent=2), encoding="utf-8"
)
counts = {}
for row in normalized:
state = row["link_state"]
counts[state] = counts.get(state, 0) + 1
print(json.dumps({"rows": len(normalized), "link_states": counts}))
Las funciones de análisis de URL de Python separan los componentes, pero el análisis por sí solo no valida la confianza ni la alcanzabilidad en red. Por lo tanto, el estado absolute_candidate del script significa exactamente eso: estaba presente una URL HTTP absoluta con un nombre de host.
Decide cuándo es necesaria una URL final
La verificación de la URL final se vuelve necesaria cuando tu conclusión depende de la identidad de la página de destino. El descubrimiento de palabras clave puede conservar un enlace candidato para una inspección posterior; la clasificación por dominio objetivo, la atribución y la entrega de citas requieren pruebas más sólidas.
| Tarea posterior | Qué puede respaldar el enlace devuelto | Trabajo adicional |
|---|---|---|
| Descubrimiento de temas | Un candidato de fuente junto a un fragmento | Revisa la página antes de confiar en sus afirmaciones |
| Auditoría de respuesta de búsqueda | El texto del enlace que devolvió la API | Conserva la respuesta original y el HTML cuando sea necesario |
| Coincidencia de dominio | Una clasificación de candidato preliminar | Resuelve y valida el dominio de destino |
| Cita verificada | Una referencia candidata | Comprueba la URL final, el contenido accesible y el respaldo de la afirmación |
Si creas un resolvedor de destinos, conserva la URL original y la URL final como columnas separadas. Registra la cadena de redirecciones y el resultado de la resolución. No envíes la clave de la API de Scrapeless a los sitios web de resultados, y no trates un fallo de red como evidencia de que la página no existe.
Evita eliminar parámetros de consulta indiscriminadamente. Algunos parámetros forman parte de la identidad de una página. Incluso eliminar una barra inclinada final puede fusionar URLs que un origen trata de forma diferente. Comienza con reglas de comparación conservadoras y luego documenta cualquier política de normalización que use tu conjunto de datos.
Diagnostica campos faltantes o inesperados
Un informe de calidad de campos debería mostrar lo que llegó en lugar de generar silenciosamente valores de reemplazo. Cuenta las cadenas no vacías por separado de las claves que simplemente existen.
Para snippet, distingue entre una clave omitida, un valor nulo, una cadena vacía y un texto no vacío. Esos estados afectan si una fila puede respaldar el análisis de texto. Conserva una fila con un fragmento faltante si su título aún sirve para tu tarea, pero marca el material que falta para que un analista entienda la limitación.
A nivel de colección, una matriz orgánica ausente no es equivalente a una matriz orgánica vacía. Los elementos del tipo incorrecto deberían detener a un consumidor estricto o registrarse en un informe de rechazo. Ninguna de las dos opciones debería aumentar silenciosamente una métrica de éxito.
Conclusión: conserva el significado de cada campo
Un analizador fiable de respuestas JSON de la Google Search API conserva los campos de origen y solo añade transformaciones que puede explicar. La posición, el orden de la matriz y el estado de la URL permanecen visibles, mientras que las suposiciones de destino no respaldadas se mantienen fuera del registro.
Comienza con la API de Búsqueda de Google sin Scraping (Scrapeless Google Search API), elige la frecuencia de recopilación según la tarifa actual y valida algunas respuestas guardadas antes de comprometerte con un esquema de base de datos.
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 de consultas pequeño antes de programar una recopilación mayor.
Preguntas frecuentes
P: ¿Incluye organic_results todas las secciones visibles en la SERP?
No. Otras funciones de búsqueda pueden aparecer en secciones de respuesta separadas. Un analizador del arreglo orgánico no debería absorber silenciosamente esos módulos.
P: ¿Es position lo mismo que el índice del elemento en el arreglo?
No asumas que son intercambiables. Conserva por separado la posición devuelta y el índice del arreglo, en particular a través de solicitudes paginadas.
P: ¿Debería redirect_link reemplazar link?
No. Conserva ambos cuando estén presentes. Elige una política de procesamiento de destino basada en el estado real de la URL y en tu tarea posterior.
P: ¿Se puede tratar un enlace codificado de Google como un destino decodificado?
No. Conserva los valores opacos y utiliza un proceso de resolución validado cuando se requiera la identidad del destino final.
P: ¿Demuestra un snippet no vacío que el resumen es preciso?
No. El texto no vacío mide la disponibilidad del campo. La precisión y el respaldo de las afirmaciones requieren la inspección del contenido de origen.
P: ¿La normalización necesita un agente de IA o un proxy separado?
No. Este script de normalización opera sobre JSON guardado y no realiza solicitudes de red.
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.



