¿Qué es la Yoast SEO REST API y por qué importa?
La Yoast SEO REST API es un conjunto de puntos finales (endpoints) que expone la funcionalidad de Yoast SEO a través de la API REST estándar de WordPress. Permite que aplicaciones externas, herramientas de terceros y flujos de trabajo personalizados accedan, consulten y manipulen datos relacionados con SEO sin necesidad de interactuar directamente con la interfaz de administración de WordPress.
Yoast SEO es un complemento de WordPress que proporciona análisis de optimización en la página, sugerencias de palabras clave, gestión de sitemaps XML, y control sobre metadatos. Históricamente, estos datos estaban disponibles solo a través de la base de datos de WordPress o mediante la interfaz de usuario del complemento. La REST API cambia esto al permitir acceso programático estructurado.
Por qué importa la REST API de Yoast SEO
La disponibilidad de una REST API para Yoast SEO resuelve varios problemas operacionales:
- Automatización de flujos de trabajo: Los equipos pueden automatizar tareas como la actualización de metadescripciones, títulos SEO, o palabras clave enfocadas en múltiples publicaciones sin intervención manual.
- Integración con sistemas externos: Herramientas de gestión de contenido, plataformas de análisis, sistemas de publicación multicanal y dashboards personalizados pueden conectarse directamente a los datos de Yoast.
- Desarrollo de aplicaciones móviles y headless: Las aplicaciones que no utilizan WordPress como frontend pueden acceder a metadatos SEO y análisis de Yoast de manera nativa.
- Sincronización de datos: Es posible sincronizar información de SEO entre WordPress y otras plataformas, como sistemas de gestión de activos digitales (DAM) o herramientas de planificación editorial.
- Auditorías y reportes programáticos: Se pueden construir herramientas personalizadas que analicen el estado SEO de un sitio completo extrayendo datos directamente de la API.
¿Cómo funciona la REST API de Yoast SEO?
La REST API de Yoast SEO se construye sobre la infraestructura estándar de la REST API de WordPress, que utiliza JSON para serializar datos y HTTP para transportarlos. Cuando Yoast SEO está activado en un sitio WordPress, registra automáticamente nuevos endpoints que exponen información sobre optimización SEO.
Estructura básica de las solicitudes
Las solicitudes a la Yoast SEO REST API siguen el patrón estándar de WordPress REST API:
Formato de URL:
https://tudominio.com/wp-json/yoast/v1/[recurso]
O en algunas versiones:
https://tudominio.com/wp-json/wp/v2/[tipo-post]?[parámetros]
Las solicitudes utilizan métodos HTTP estándar:
- GET: Recuperar información sobre publicaciones, metadatos SEO, o análisis.
- POST: Crear nuevas publicaciones con metadatos SEO incluidos.
- PUT o PATCH: Actualizar metadatos SEO existentes en publicaciones.
- DELETE: Eliminar recursos (menos común en contextos SEO).
Autenticación
La REST API de Yoast SEO requiere autenticación para proteger datos sensibles. Los métodos de autenticación disponibles incluyen:
- Autenticación por cookies: Disponible cuando se accede desde el mismo dominio donde está instalado WordPress.
- Autenticación por token (JWT): Utiliza JSON Web Tokens para acceso desde aplicaciones externas. Requiere configuración adicional o complementos como JWT Authentication for WP REST API.
- Autenticación básica HTTP: Menos segura, utiliza credenciales de usuario de WordPress codificadas en Base64.
- OAuth 2.0: Disponible en algunos entornos empresariales o con complementos específicos.
Campos SEO expuestos por la API
Cuando se consulta una publicación a través de la REST API de WordPress con Yoast SEO activado, la respuesta incluye campos adicionales que contienen metadatos de SEO. Estos campos varían según la versión de Yoast SEO, pero típicamente incluyen:
| Campo | Descripción | Tipo de dato |
|---|---|---|
| yoast_head | HTML renderizado de todas las etiquetas head generadas por Yoast para esta publicación | String |
| yoast_head_json | Versión JSON estructurada de los metadatos head | Objeto JSON |
| meta (yoast_wpseo_title) | Título SEO personalizado | String |
| meta (yoast_wpseo_metadesc) | Metadescripción personalizada | String |
| meta (yoast_wpseo_focuskw) | Palabra clave enfocada principal | String |
| meta (yoast_wpseo_primary_category) | ID de la categoría primaria asignada | Integer |
| meta (yoast_wpseo_canonical) | URL canónica personalizada | String |
| meta (yoast_wpseo_opengraph-*) | Metadatos Open Graph (imagen, título, descripción) | String |
| meta (yoast_wpseo_twitter-*) | Metadatos de tarjeta de Twitter | String |
Endpoints principales
Endpoint de publicaciones con datos SEO:
El endpoint estándar de publicaciones de WordPress expone metadatos de Yoast cuando está activado:
GET /wp-json/wp/v2/posts/{id}
Este endpoint devuelve una publicación específica con todos sus metadatos SEO incluidos en la respuesta JSON.
Endpoint de categoría primaria (en versiones recientes):
Algunas versiones de Yoast SEO exponen un endpoint específico para gestionar la categoría primaria:
GET /wp-json/yoast/v1/primary_category/{post_id}
Este endpoint devuelve información sobre qué categoría está asignada como primaria para una publicación específica.
Consultas con filtros SEO:
Es posible filtrar publicaciones basándose en metadatos de Yoast. Por ejemplo:
GET /wp-json/wp/v2/posts?meta_key=yoast_wpseo_focuskw&meta_value=mi-palabra-clave
Estructura de respuesta típica
Una solicitud GET a una publicación devuelve una respuesta JSON que incluye:
- Campos estándar de WordPress: id, title, content, excerpt, date, author, etc.
- Campo yoast_head: Una cadena HTML completa con todas las etiquetas meta generadas por Yoast.
- Campo yoast_head_json: Un objeto JSON estructurado que desglosa cada elemento meta individualmente.
- Objeto meta: Contiene todos los campos personalizados de Yoast, como yoast_wpseo_title, yoast_wpseo_metadesc, etc.
El campo yoast_head_json es particularmente útil porque permite acceder a metadatos específicos sin necesidad de parsear HTML. Incluye información como:
- Título de la página (title)
- Metadescripción (description)
- URL canónica (canonical)
- Metadatos Open Graph
- Datos estructurados (Schema.org)
- Información de redes sociales
Limitaciones y consideraciones de permisos
La REST API de Yoast SEO respeta el sistema de permisos de WordPress. Por defecto:
- Los usuarios no autenticados pueden leer metadatos de publicaciones públicas.
- Solo usuarios con capacidad de editar publicaciones pueden modificar metadatos SEO.
- Los administradores tienen acceso completo a todos los datos SEO.
- Los editores pueden modificar SEO en publicaciones que tienen permiso de editar.
Algunos metadatos sensibles, como datos de análisis internos o configuraciones a nivel de sitio, pueden no estar disponibles a través de la API REST pública, dependiendo de cómo esté configurado el sitio.
Diferencia entre acceso directo a metadatos y la REST API
Antes de que Yoast SEO expusiera completamente sus datos a través de la REST API, los desarrolladores tenían que acceder a los metadatos directamente desde la base de datos de WordPress usando funciones como get_post_meta(). Esto requería:
- Acceso directo a la base de datos o uso de funciones de WordPress.
- Conocimiento de los nombres exactos de las claves meta (como 'yoast_wpseo_title').
- Manejo manual de serialización y deserialización de datos.
- Validación manual de permisos de usuario.
La REST API simplifica esto al proporcionar:
- Acceso HTTP estándar sin necesidad de funciones de WordPress.
- Documentación clara de campos disponibles.
- Manejo automático de permisos.
- Respuestas JSON consistentes y bien estructuradas.
- Posibilidad de acceso desde cualquier aplicación que pueda hacer solicitudes HTTP.
Casos de uso prácticos
Actualización masiva de metadescripciones: Una agencia puede escribir un script que lea todas las publicaciones de un sitio, evalúe si sus metadescripciones cumplen con ciertos criterios, y actualice automáticamente las que no cumplan.
Dashboard SEO personalizado: Un equipo puede construir un dashboard interno que consulte la API de Yoast para mostrar el estado SEO de todas las publicaciones, palabras clave enfocadas, y puntuaciones de legibilidad en una interfaz personalizada.
Sincronización con herramientas externas: Una plataforma de análisis de contenido puede conectarse a la API de Yoast para extraer datos SEO y correlacionarlos con métricas de tráfico de Google Analytics.
Publicación desde aplicaciones móviles: Una aplicación móvil nativa puede permitir que los editores creen y optimicen publicaciones incluyendo metadatos SEO completos directamente desde sus dispositivos.
Estrategia práctica para implementar Yoast SEO REST API
La implementación efectiva de Yoast SEO REST API requiere una planificación estructurada que va más allá de simplemente conectar endpoints. Esta sección proporciona un enfoque paso a paso que te permite integrar datos SEO de Yoast en aplicaciones externas, sistemas de gestión de contenido personalizados, o flujos de trabajo automatizados.
Paso 1: Verificar la disponibilidad de endpoints y autenticación
Antes de escribir cualquier código, debes confirmar qué endpoints están realmente disponibles en tu instalación de Yoast SEO. No todas las versiones exponen los mismos datos a través de la REST API de WordPress.
Accede a tu sitio WordPress y navega hacia /wp-json/yoast/v1/ o /wp-json/wp/v2/posts para ver qué campos Yoast están disponibles. Los campos más comúnmente expuestos incluyen:
- Metadescripción (meta_description)
- Palabra clave enfocada (focus_keyphrase)
- Categoría primaria (primary_category)
- Análisis SEO (readability_score, seo_score)
- Datos de enlazado interno (internal_links)
Para la autenticación, WordPress REST API utiliza tokens de aplicación (Application Passwords) o autenticación por cookie. Si accedes desde un dominio diferente, necesitarás configurar CORS (Cross-Origin Resource Sharing) correctamente en tu servidor.
Genera una contraseña de aplicación en WordPress navegando a Usuarios > Tu Perfil > Contraseñas de aplicación. Esta contraseña debe incluirse en el encabezado Authorization de tus solicitudes usando autenticación básica (Base64).
Paso 2: Estructura las solicitudes GET para recuperar datos SEO
Una solicitud GET bien estructurada es la base de cualquier integración. Aquí está la anatomía correcta:
Endpoint básico para obtener posts con datos Yoast:
GET /wp-json/wp/v2/posts?_fields=id,title,content,yoast_head_json,meta
El parámetro _fields es crítico porque limita la respuesta solo a los campos que necesitas, reduciendo el tamaño de la respuesta y mejorando el rendimiento. Sin este parámetro, obtendrás toda la información del post, incluyendo datos innecesarios.
El campo yoast_head_json es especialmente valioso porque contiene la salida JSON de todas las etiquetas meta que Yoast genera, incluyendo Open Graph, Twitter Card, y datos estructurados (schema.org).
Parámetros útiles para filtrar:
- per_page=10 - Controla cuántos posts se devuelven (máximo 100)
- page=2 - Navega entre páginas de resultados
- search=keyword - Filtra posts por término de búsqueda
- status=publish - Solo posts publicados (o draft, pending, etc.)
- orderby=modified - Ordena por fecha de modificación
Cuando recuperes datos, siempre incluye manejo de errores. La API devuelve códigos HTTP específicos: 200 para éxito, 401 para autenticación fallida, 403 para permisos insuficientes, y 404 cuando el recurso no existe.
Paso 3: Enviar actualizaciones con solicitudes POST y PUT
Modificar datos SEO a través de la API requiere permisos de edición y una estructura de payload correcta.
Para actualizar la metadescripción de un post existente:
Utiliza una solicitud PUT al endpoint del post específico:
PUT /wp-json/wp/v2/posts/123
El body debe contener el objeto meta con los campos Yoast que deseas actualizar:
{
"meta": {
"_yoast_wpseo_metadesc": "Tu nueva metadescripción aquí",
"_yoast_wpseo_focuskw": "palabra clave principal"
}
}
Es importante notar que los nombres de campo en la meta están prefijados con _yoast_wpseo_. Este prefijo es obligatorio para que Yoast reconozca y procese los datos correctamente.
Para crear un post nuevo con datos SEO desde el inicio:
Usa una solicitud POST a /wp-json/wp/v2/posts con el contenido y metadatos incluidos:
{
"title": "Título del Post",
"content": "Contenido del post",
"status": "publish",
"meta": {
"_yoast_wpseo_metadesc": "Descripción meta",
"_yoast_wpseo_focuskw": "palabra clave",
"_yoast_wpseo_primary_category": 5
}
}
La categoría primaria se especifica como un ID numérico, no como texto. Debes obtener primero los IDs de categoría desde /wp-json/wp/v2/categories.
Paso 4: Implementar paginación eficiente para grandes volúmenes
Si tu sitio tiene cientos o miles de posts, recuperar todos a la vez causará timeouts. La paginación es obligatoria.
WordPress REST API proporciona dos métodos de paginación:
- Paginación por offset: Usa
page=1&per_page=50. Simple pero lenta con grandes datasets porque el servidor debe contar todas las filas. - Paginación por cursor: Usa
after=cursor_value. Más eficiente porque se basa en el ID del último item recuperado.
Los encabezados de respuesta incluyen información de paginación:
- X-WP-Total: Número total de posts
- X-WP-TotalPages: Número total de páginas
- Link: URLs para next, prev, first, last (formato RFC 5988)
Siempre procesa la información del encabezado Link para determinar si hay más páginas, en lugar de asumir basándote en el recuento de resultados.
Paso 5: Gestionar permisos y capacidades de usuario
No todos los usuarios pueden acceder o modificar todos los datos SEO. WordPress REST API respeta las capacidades estándar de WordPress.
Para que un usuario pueda leer datos SEO, necesita:
- read_posts - Para acceder a posts publicados
- read_private_posts - Para acceder a borradores y posts privados
Para modificar datos SEO:
- edit_posts - Para editar posts propios
- edit_others_posts - Para editar posts de otros usuarios
- edit_published_posts - Para editar posts ya publicados
Si tu aplicación externa necesita acceso programático, crea un usuario específico con solo las capacidades necesarias. Nunca uses credenciales de administrador para integraciones automatizadas.
Paso 6: Validar y sanitizar datos antes de enviar
Aunque WordPress REST API valida datos en el servidor, es responsabilidad de tu aplicación cliente validar antes de enviar.
Validaciones críticas para campos Yoast:
- Metadescripción: Máximo 160 caracteres (aunque algunos motores de búsqueda muestran hasta 200). Verifica la longitud antes de enviar.
- Palabra clave enfocada: Debe ser una cadena no vacía. Algunas implementaciones permiten múltiples palabras clave separadas por comas.
- Categoría primaria: Debe ser un ID válido que existe en tu taxonomía. Valida contra la lista de categorías disponibles.
- Contenido: No puede estar vacío si el post se publica. Yoast necesita contenido para calcular puntuaciones de legibilidad.
Implementa también sanitización en el lado del cliente para remover caracteres especiales que podrían causar problemas de codificación.
Paso 7: Monitorear cuotas de rate limiting
WordPress REST API puede tener limitaciones de velocidad configuradas en el servidor. Aunque no hay un estándar universal, es común encontrar límites como 60 solicitudes por minuto por usuario.
Los encabezados de respuesta indican el estado de rate limiting:
- X-RateLimit-Limit: Máximo de solicitudes permitidas
- X-RateLimit-Remaining: Solicitudes restantes
- X-RateLimit-Reset: Timestamp cuando se reinicia el contador
Implementa lógica de reintento exponencial: si recibes un error 429 (Too Many Requests), espera antes de reintentar, aumentando el tiempo de espera con cada intento fallido.
Errores comunes y cómo evitarlos
Error 1: Asumir que todos los campos Yoast están disponibles
No todas las versiones de Yoast SEO exponen todos los datos a través de REST API. Algunos campos como el análisis de enlaces internos o el análisis de legibilidad completo pueden no estar disponibles. Siempre verifica qué campos están realmente presentes en tu instalación antes de escribir código que dependa de ellos.
Solución: Realiza una solicitud GET de prueba y examina la respuesta JSON. Documenta qué campos están disponibles en tu versión específica.
Error 2: No manejar la paginación correctamente
Intentar recuperar todos los posts de una vez causará que la solicitud se agote. Esto es especialmente problemático si tu sitio tiene miles de posts.
Solución: Siempre implementa paginación. Comienza con per_page=50 y ajusta según el rendimiento. Usa loops que respeten los encabezados de paginación.
Error 3: Usar credenciales de administrador para automatización
Exponer credenciales de administrador en código o variables de entorno es un riesgo de seguridad grave. Si alguien accede a tu aplicación, tiene acceso total al sitio.
Solución: Crea un usuario específico con capacidades limitadas. Usa contraseñas de aplicación que pueden revocarse sin afectar la cuenta principal.
Error 4: No validar la autenticación antes de hacer solicitudes en masa
Si tu token de autenticación es inválido, cada solicitud fallará. Hacer 1000 solicitudes fallidas es un desperdicio de recursos.
Solución: Realiza una solicitud de prueba simple antes de iniciar operaciones en masa. Verifica que la respuesta sea 200 OK.
Error 5: Ignorar los códigos de estado HTTP
Algunos desarrolladores solo verifican si la solicitud se completó, sin revisar si fue exitosa. Un error 403 (Forbidden) se ve igual a 200 (OK) si no verificas el código.
Solución: Siempre verifica el código de estado HTTP. Implementa manejo específico para 401, 403, 404, 429, y 500.
Error 6: Modificar campos Yoast sin el prefijo correcto
Los nombres de campo en meta deben incluir el prefijo _yoast_wpseo_. Usar nombres sin prefijo resultará en que los datos se guarden pero Yoast no los reconocerá.
Solución: Mantén una referencia de los nombres de campo correctos. Prueba cada campo individualmente antes de integrar en un flujo de trabajo automatizado.
Error 7: No considerar la carga del servidor
Hacer 10,000 solicitudes a la API en paralelo puede sobrecargar el servidor y afectar el rendimiento del sitio para usuarios reales.
Solución: Implementa colas de procesamiento. Limita el número de solicitudes simultáneas a 3-5. Programa operaciones en masa para horarios de bajo tráfico.
Checklist de implementación
| Tarea | Descripción | Prioridad |
|---|---|---|
| Verificar endpoints disponibles | Confirmar qué campos Yoast están expuestos en tu instalación | Crítica |
| Configurar autenticación | Crear contraseña de aplicación y probar acceso | Crítica |
| Implementar manejo de errores | Códigos HTTP, reintentos, logging | Crítica |
| Programar paginación | Loops que respeten encabezados de paginación | Alta |
| Validar datos | Verificar longitudes, formatos, IDs válidos | Alta |
| Probar permisos | Confirmar que el usuario tiene capacidades correctas | Alta |
| Monitorear rate limiting | Implementar retrasos y reintento exponencial | Media |
| Documentar campos | Registrar qué campos están disponibles y sus formatos | Media |