Una API SERP ejecuta una consulta de motor de búsqueda por ti y devuelve la página de resultados en forma de JSON estructurado: resultados orgánicos con su posición, anuncios, fragmentos destacados, resultados locales y más. En lugar de construir scrapers para Google y mantenerlos funcionando, envías una solicitud y lees los campos que necesitas.
Esta guía recorre cómo configurar una desde cero: obtener y almacenar una clave de API, hacer tu primera búsqueda, obtener resultados para la ubicación y el dispositivo correctos, gestionar errores y convertir los resultados en una comprobación de ranking. Usa la API SERP de Shifter como ejemplo; la mayoría de las APIs SERP funcionan de forma similar.
Paso 1: obtén tu clave de API
Cada solicitud lleva una clave de API. En el panel de Shifter, abre SERP API, luego API Keys, y copia una clave activa.
Trata la clave como una contraseña:
- Mantenla fuera del código y de los repositorios. Guárdala en una variable de entorno o en un gestor de secretos.
- Usa claves separadas para desarrollo y producción cuando puedas, para que una clave de prueba filtrada no afecte a producción.
- Rota una clave si pudiera haberse expuesto, y actualízala en todos los lugares donde se use.
export SHIFTER_SERP_KEY="your-key-here"Paso 2: ejecuta tu primera búsqueda
La API es un único endpoint, https://serp.shifter.io/v1. Elige el motor de búsqueda con engine y pasa la consulta como q:
curl "https://serp.shifter.io/v1?engine=google&api_key=$SHIFTER_SERP_KEY&q=residential+proxies"La respuesta es JSON. Para una búsqueda en Google, organic_results contiene los resultados normales, cada uno con position, title, link, displayed_link y snippet. Otras secciones, como anuncios y resultados locales, aparecen cuando la página de resultados las incluye.
El mismo endpoint cubre otros motores de búsqueda y superficies de Google: cambia engine a bing o yandex para esos motores de búsqueda, o a google_maps, google_news o google_shopping para otros resultados de Google. El resto de esta guía se aplica a todos ellos; solo cambian los campos de la respuesta.
Paso 3: obtén resultados para el lugar y dispositivo correctos
Los resultados de búsqueda difieren según la ubicación, el idioma y el dispositivo, a menudo bastante. Una comprobación de ranking que no fija todos ellos mide una página de resultados distinta cada vez.
| Parámetro | Qué establece | Ejemplo |
|---|---|---|
location | Desde dónde se hace la búsqueda | Austin,Texas,United States |
gl | El país de los resultados | us |
hl | El idioma de la interfaz | en |
device | Resultados de escritorio, móvil o tablet | mobile |
Escribe la ubicación de forma completa (ciudad, región, país), porque nombres cortos como “Springfield” son ambiguos. Nuestra guía sobre APIs SERP con segmentación geográfica para SEO local explica por qué la precisión de la ubicación importa tanto.
Paso 4: gestiona los errores
Las solicitudes pueden fallar por razones que pasan y razones que no:
- Reintenta los límites de frecuencia y los errores temporales del servidor, con una pausa que crece cada vez.
- Detente y corrige los errores de autenticación y de solicitud mal formada; reintentarlos solo repite el fallo.
- Establece un tiempo de espera en cada solicitud, para que una búsqueda lenta no bloquee toda la ejecución.
Juntándolo todo
El siguiente ayudante lee la clave del entorno, siempre envía ubicación, idioma y dispositivo, reintenta los errores que merece la pena reintentar, e incluye una función que encuentra dónde está posicionado un dominio en los resultados orgánicos:
import os
import time
from urllib.parse import urlparse
import requests
API = "https://serp.shifter.io/v1"
RETRY = {408, 429, 500, 502, 503}
def google_search(query, location, gl="us", hl="en", device="desktop", session=None, attempts=3):
"""One Google search as seen from `location`, returned as parsed JSON."""
session = session or requests.Session()
params = {"engine": "google", "api_key": os.environ["SHIFTER_SERP_KEY"], "q": query,
"location": location, "gl": gl, "hl": hl, "device": device}
for attempt in range(1, attempts + 1):
response = session.get(API, params=params, timeout=60)
if response.status_code == 200:
return response.json()
if response.status_code not in RETRY or attempt == attempts:
raise RuntimeError(f"{query!r}: HTTP {response.status_code} {response.text[:200]}")
time.sleep(2 * attempt)
def rank_of(serp, domain):
"""Position of the first organic result on `domain`, or None if it is not there."""
for result in serp.get("organic_results", []):
host = urlparse(result["link"]).netloc.lower()
if host == domain or host.endswith("." + domain):
return result["position"]
return NoneComprobando dónde está posicionado un sitio para dos palabras clave, visto desde un móvil en Austin:
from serp import google_search, rank_of
keywords = ["emergency plumber", "water heater repair"]
for keyword in keywords:
serp = google_search(keyword, location="Austin,Texas,United States", device="mobile")
print(keyword, rank_of(serp, "example-plumbing.com"))Hemos probado los parámetros de solicitud, los reintentos, la gestión de errores y la búsqueda de ranking del ayudante frente a respuestas simuladas.
Paso 5: conviértelo en seguimiento de ranking
Una búsqueda es una instantánea. Hacer seguimiento significa ejecutar las mismas búsquedas según un calendario y almacenar los resultados:
- Fija la lista de palabras clave y la ubicación, el idioma y el dispositivo para cada una.
- Ejecuta según un calendario, a diario o semanalmente según cuánto se muevan los rankings en tu mercado.
- Almacena cada respuesta completa con su hora y configuración, no solo la posición, para que puedas revisar qué cambió.
- Activa alertas ante cambios que importen: una caída fuera de los tres primeros puestos, un competidor que aparece por encima de ti, un fragmento destacado perdido.
Nuestra guía sobre automatización del seguimiento diario de posiciones de palabras clave trata la programación y el almacenamiento con más profundidad. Si el seguimiento de rankings es una parte central de tu trabajo, nuestra página de monitorización SEO cubre la configuración más amplia.
Errores habituales de configuración
- No fijar la ubicación. Entonces los resultados proceden de una ubicación predeterminada que probablemente no es tu mercado.
- Mezclar escritorio y móvil entre ejecuciones, lo que hace que los rankings salten sin una razón real.
- Hacer coincidir por URL exacta en lugar de por dominio, de modo que una página posicionada que cambió de ruta parece un ranking perdido.
- Almacenar solo posiciones. Sin la respuesta completa no puedes saber por qué cambió una posición.
- Codificar la clave directamente, que acaba en un repositorio tarde o temprano.
Preguntas frecuentes
¿Qué es una API SERP?
Un servicio que ejecuta consultas de motores de búsqueda por ti y devuelve la página de resultados como datos estructurados, como resultados orgánicos con posiciones, anuncios, fragmentos destacados y resultados locales, para que no tengas que hacer scraping ni analizar páginas de búsqueda tú mismo.
¿Cómo consigo una clave de API SERP?
Regístrate con un proveedor de API SERP y crea una clave en su panel. En el panel de Shifter, las claves están en SERP API, luego API Keys. Guarda la clave en una variable de entorno en lugar de en tu código.
¿Por qué mis resultados de la API SERP difieren de lo que veo en Google?
Normalmente porque la ubicación, el idioma, el dispositivo o la personalización difieren. Tus propias búsquedas están personalizadas y proceden de tu ubicación; establece explícitamente la ubicación, el idioma y el dispositivo de la API para que coincidan con el mercado que quieres medir.
¿Con qué frecuencia debería comprobar los rankings?
A diario para palabras clave competitivas y mercados que se mueven rápido, semanalmente para la mayoría de los demás. Mantén la configuración idéntica entre ejecuciones para que los cambios reflejen los resultados, no la medición.
En resumen
Configurar una API SERP lleva unos pocos pasos: guarda la clave de forma segura, envía la consulta con el motor, la ubicación, el idioma y el dispositivo fijados, reintenta solo los errores que pueden pasar, y lee las posiciones de los resultados estructurados. Ejecuta las mismas búsquedas según un calendario, conserva las respuestas completas, y tendrás un rastreador de rankings que mide la misma página de resultados cada vez.