Documentacion API de TrueRanker

a API de TrueRanker te permite recuperar de forma programática tus proyectos, palabras clave y datos de posicionamiento. Esta funcionalidad está disponible para usuarios a partir del Plan Agencia.

Autenticación #

Para utilizar la API, necesitas tu API Key (Clave API).

• Puedes encontrar tu API Key en tu cuenta de TrueRanker, en Configuración de la cuenta > API.
• Alternativamente, si utilizas el plugin de WordPress, se encuentra en la sección del menú del plugin.

Todas las peticiones deben incluir el parámetro key en la URL.

Endpoints de la API #

URL Base: https://app.trueranker.com/data

1. Obtener lista de proyectos #

Recupera todos los proyectos asociados a tu cuenta.

Petición (Request):

GET /project/list

Parámetros:

Ejemplo:

Estructura de la Respuesta:

• ok (boolean): Estado de la petición.
• data.projects: Array de objetos de proyecto.
  • id: Identificador del proyecto.
  • name: Nombre del proyecto.
  • domain: Dominio del proyecto.
  • type: Tipo de proyecto (1: Dominio único, 2: Dominio+Subdominios, 3: Directorio, 4: URL única, 5: Extensión de Chrome).
  • num_keywords: Número total de palabras clave en el proyecto.
  • created_at: Fecha de creación.

2. Obtener palabras clave de un proyecto (Rankings Actuales) #

Recupera todas las palabras clave de un proyecto específico con sus datos de posicionamiento actuales.

Petición (Request):

GET /project/keyword/list

Parámetros:

Ejemplo:

Estructura de la Respuesta:

• data.keywords: Array de objetos de palabra clave.
  • id: Identificador de la palabra clave.
  • keyword: El término exacto que se está rastreando.
  • location: Ciudad, provincia o país rastreado.
  • country: Código del país (ej: ES, US).
  • device: Tipo de dispositivo (desktop/mobile).
  • rank: Posición actual.
  • previous_rank: Posición en la comprobación anterior.
  • best_rank_ever: Mejor posición alcanzada históricamente.
  • url: La URL específica que está posicionando.
  • volume: Volumen de búsqueda mensual.
  • cpc: Coste por Clic.
  • date: Fecha de la última actualización.

3. Obtener palabras clave y rankings por rango de fechas #

Recupera datos de palabras clave y su historial de posicionamiento entre dos fechas específicas.

Petición (Request):

GET /project/keyword/list (con parámetros de fecha)

Parámetros:

Ejemplo:

Respuesta:

Devuelve los datos de la palabra clave (igual que en el punto anterior) más un array/objeto que contiene las posiciones diarias y las URLs para el rango de fechas especificado.

4. Obtener historial de una palabra clave (Palabra clave única) #

Recupera el historial detallado de posiciones para una única palabra clave específica.

Petición (Request):

GET /project/keyword/get

Parámetros:

Ejemplo:

Estructura de la Respuesta:

• data.keyword: Información básica de la palabra clave (id, término, ubicación, dispositivo).
• data.history: Array de puntos de datos diarios.
  • date: Fecha del registro.
  • rank: Posición en ese día.
  • url: URL posicionada.
  • cannibalization: Array de URLs y posiciones si existen múltiples páginas compitiendo por esta palabra clave.

Gestión de Errores #

Todas las peticiones devuelven un objeto JSON. Comprueba el campo booleano ok.

• Si ok: true, la petición fue exitosa.
• Si ok: false, revisa el campo error para ver una descripción del problema (ej: «Invalid API Key», «Project not found»).