Docs / Referencia de la API

Referencia de la API

Referencia completa para la REST API de SEOLens.

URL Base

https://seo-lens.site/api/v1

Autenticación

Todas las solicitudes API requieren una clave API. Inicia sesión en tu panel para crear una clave API gratuita. Inclúyela en cada solicitud a través del encabezado Authorization o x-api-key.

Authorization: Bearer YOUR_API_KEY

# or

x-api-key: YOUR_API_KEY

POST

/research

Investiga una o más palabras clave y obtén volumen de búsqueda, dificultad, datos de CPC y sugerencias de palabras clave relacionadas.

Cuerpo de la Solicitud

Parámetro	Tipo	Requerido	Descripción
keyword	string	Yes*	Palabra clave individual para investigar
keywords	string[]	Yes*	Array de palabras clave (máx. 50). Usar en lugar de `keyword`
countryCode	string	No	Código de país (por defecto: "US"). Opciones: US, JP, GB, DE, FR, CA, AU, BR, IN, KR, MX, ES, IT, NL, SE, TW, TH, VN, ID, PH
languageCode	string	No	Código de idioma (por defecto: "en"). Opciones: en, ja, de, fr, es, pt, it, nl, ko, zh, th, vi, id, sv

* Proporciona keyword o keywords, no ambos.

Formato de Respuesta (Palabra Clave Individual)

200 OK

{
  "keyword": "react hooks",
  "metrics": {
    "avgMonthlySearches": 18100,
    "competition": "LOW",
    "cpcLow": 0.15,
    "cpcHigh": 1.85
  },
  "difficulty": "easy",
  "suggestions": [
    {
      "keyword": "react custom hooks",
      "avgMonthlySearches": 6600,
      "competition": "LOW",
      "cpcLow": 0.10,
      "cpcHigh": 0.95
    }
  ]
}

Formato de Respuesta (Lote)

200 OK

{
  "results": [
    {
      "keyword": "react hooks",
      "metrics": { ... },
      "difficulty": "easy",
      "suggestions": [ ... ]
    },
    {
      "keyword": "vue composables",
      "metrics": { ... },
      "difficulty": "medium",
      "suggestions": [ ... ]
    }
  ]
}

Ejemplos de Código

JavaScript / TypeScript

fetch

const response = await fetch("https://seo-lens.site/api/v1/research", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY",
  },
  body: JSON.stringify({
    keywords: ["nextjs seo"],
    countryCode: "US",
    languageCode: "en",
  }),
});

const data = await response.json();
console.log(data.results);

Python

requests

import requests

response = requests.post(
    "https://seo-lens.site/api/v1/research",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "keywords": ["nextjs seo"],
        "countryCode": "US",
        "languageCode": "en",
    },
)

data = response.json()
print(f"Results: {data['results']}")

cURL

bash

# Single keyword
curl -X POST https://seo-lens.site/api/v1/research \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"keywords": ["nextjs seo"], "countryCode": "US"}'

# Batch keywords
curl -X POST https://seo-lens.site/api/v1/research \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"keywords": ["react hooks", "vue composables"], "countryCode": "US"}'

Códigos de Error

Estado	Descripción
200	Éxito - datos de palabra clave devueltos
401	No autorizado - clave API faltante o inválida
400	Solicitud Incorrecta - parámetros faltantes o inválidos
429	Límite de Frecuencia Excedido - demasiadas solicitudes
500	Error Interno del Servidor - por favor intenta de nuevo más tarde

Límites de Frecuencia

El nivel gratuito tiene límites de frecuencia para garantizar un uso justo para todos los usuarios.

100 solicitudes por día por dirección IP
50 palabras clave por solicitud por lotes
Los resultados en caché no cuentan contra el límite de frecuencia