Menú de la documentaciónConsulta tus estadísticas con la API REST

Consulta tus estadísticas con la API REST

Autentícate con una contraseña de aplicación, obtén con curl totales, páginas principales, fuentes y datos de Search Console, y monta un script de informe semanal.

En esta página

La API REST de Vireo devuelve en JSON las mismas cifras que tu panel. Es de solo lectura y vive bajo /wp-json/vireo-analytics/v1. Todas las rutas están en la referencia de la API.

1. Crea una contraseña de aplicación

La API inicia sesión como un usuario de WordPress, y solo responde a los usuarios que pueden abrir el panel de Vireo. Consulta Quién puede ver los números.

  1. En WordPress, ve a Usuarios, Perfil.
  2. En Contraseñas de aplicación, escribe un nombre como «Reports script» y haz clic en «Añadir nueva contraseña de aplicación».
  3. Copia la contraseña. Solo se muestra una vez.

WordPress solo ofrece contraseñas de aplicación en sitios servidos por HTTPS, o marcados como entorno de desarrollo local.

2. Haz tu primera petición

Envía el nombre de usuario y la contraseña de aplicación con autenticación HTTP Basic. Con curl, es -u:

curl -u "your-username:xxxx xxxx xxxx xxxx xxxx xxxx" \
  "https://example.com/wp-json/vireo-analytics/v1/stats/totals?start=2026-09-12&end=2026-10-11"
{"pageviews":15,"visitors":15,"days":30,"avg_daily":1,"avg_time_on_page_seconds":null,"timed_views":0,"bounce_rate_percent":null}

El tiempo en la página y la tasa de rebote vienen como null cuando el rango no tiene ninguno registrado. En un sitio con la 0.13.0 llevan números, como "avg_time_on_page_seconds":74,"timed_views":512,"bounce_rate_percent":61.4. Consulta la lista de campos.

Para que la contraseña no quede en el historial de tu shell, guárdala antes en una variable de entorno:

export VIREO_AUTH="your-username:xxxx xxxx xxxx xxxx xxxx xxxx"
export VIREO_API="https://example.com/wp-json/vireo-analytics/v1"
curl -u "$VIREO_AUTH" "$VIREO_API/stats/totals?start=2026-09-12&end=2026-10-11"

Los ejemplos siguientes usan esas dos variables.

Fechas y límites

  • start y end son fechas con el formato YYYY-MM-DD, en la zona horaria de tu sitio. Las dos son obligatorias en las rutas /stats/....
  • Las fechas se mantienen dentro de los últimos dos años: una fecha anterior pasa a ser el primer día permitido, y una fecha futura pasa a ser hoy.
  • Las rutas que devuelven una lista admiten limit. Los valores van de 1 a 100; lo que quede fuera se ajusta a ese rango.
  • No hay paginación. Una lista devuelve las limit primeras filas, ordenadas.
  • Los parámetros que una ruta no usa se ignoran.

Listas y filas

Las rutas que devuelven una lista responden con una de estas dos formas:

  • /stats/daily, /stats/top-pages, /stats/top-referrers, /stats/countries, /stats/events y /stats/clicks devuelven un array JSON plano, como siempre. También /stats/goals con Vireo Pro.
  • Cualquier otra lista, como /stats/channels, /stats/hourly, /stats/vitals y /stats/annotations, devuelve un objeto con la lista bajo rows: {"rows": [...]}. Un resultado vacío es {"rows": []}.

Las rutas que devuelven un solo registro, como /stats/totals o /stats/post/{id}, devuelven ese objeto tal cual. La referencia de la API indica la forma de cada ruta.

Páginas principales

curl -u "$VIREO_AUTH" "$VIREO_API/stats/top-pages?start=2026-09-12&end=2026-10-11&limit=3"
[
  {"post_id":4,"path":"/2026/10/11/how-to-pack-for-a-month/","title":"How to pack for a month","pageviews":6,"visitors":6,"avg_time_on_page_seconds":null},
  {"post_id":6,"path":"/2026/10/11/pricing/","title":"Pricing","pageviews":3,"visitors":3,"avg_time_on_page_seconds":null},
  {"post_id":5,"path":"/2026/10/11/a-week-in-porto-on-foot/","title":"A week in Porto on foot","pageviews":3,"visitors":3,"avg_time_on_page_seconds":null}
]

post_id es 0 en las páginas que no son una entrada individual, como la página de inicio o un archivo.

De dónde vinieron los visitantes

Por canal:

curl -u "$VIREO_AUTH" "$VIREO_API/stats/channels?start=2026-09-12&end=2026-10-11"
{"rows":[
  {"source":"direct","label":"Direct","pageviews":3,"visitors":3,"share_pct":20},
  {"source":"search","label":"Search","pageviews":3,"visitors":3,"share_pct":20},
  {"source":"ai","label":"AI assistants","pageviews":3,"visitors":3,"share_pct":20},
  {"source":"social","label":"Social","pageviews":6,"visitors":6,"share_pct":40},
  {"source":"email","label":"Email","pageviews":0,"visitors":0,"share_pct":0},
  {"source":"referral","label":"Referral","pageviews":0,"visitors":0,"share_pct":0}
]}

A diferencia de Páginas principales, esta ruta envuelve su lista en rows. Listas y filas explica qué rutas lo hacen.

Por sitio, y después un sitio al detalle:

curl -u "$VIREO_AUTH" "$VIREO_API/stats/top-referrers?start=2026-09-12&end=2026-10-11&limit=10"
curl -u "$VIREO_AUTH" "$VIREO_API/stats/referrer?host=news.ycombinator.com&start=2026-09-12&end=2026-10-11"

Search Console

curl -u "$VIREO_AUTH" "$VIREO_API/stats/search-console?start=2026-09-12&end=2026-10-11&limit=10"

Añade post_id=4, o path=/pricing/, para ver las búsquedas que llevan a una página. Los datos de Google van entre dos y tres días por detrás.

Si Search Console no está conectado, sigues recibiendo un 200, con connected en false:

{"connected":false,"message":"Google Search Console is not connected. Connect it under Vireo Analytics, Settings, Search Console & API.","summary":null,"queries":[]}

Las estadísticas de una entrada

curl -u "$VIREO_AUTH" "$VIREO_API/stats/post/4?start=2026-09-12&end=2026-10-11"
{
  "post_id": 4,
  "title": "How to pack for a month",
  "url": "https://example.com/2026/10/11/how-to-pack-for-a-month/",
  "lifetime": {"pageviews":6,"visitors":6,"first_seen":"2026-10-11","best_day":{"date":"2026-10-11","pageviews":6}},
  "period": {"pageviews":6,"visitors":6},
  "daily": [{"date":"2026-09-12","pageviews":0,"visitors":0}, "…one row per day…"],
  "referrers": [{"host":"google.com","pageviews":3,"visitors":3},{"host":"chatgpt.com","pageviews":3,"visitors":3}]
}

Una entrada que no existe, o que el usuario no podría leer en el sitio (un borrador, por ejemplo), devuelve 404.

Errores

Estado Código Significado
400 rest_missing_callback_param Falta un parámetro obligatorio, normalmente start o end.
400 rest_invalid_param Una fecha no tiene el formato YYYY-MM-DD.
400 vireo_rest_bad_range end es anterior a start.
401 rest_forbidden No hay sesión, o WordPress no aceptó el nombre de usuario y la contraseña de aplicación.
403 rest_forbidden El usuario tiene la sesión iniciada pero no puede ver el panel de Vireo.
404 vireo_ability_not_found La entrada no existe o no es visible.

Una ruta de Pro en un sitio sin licencia de Pro activa devuelve 403, o 404 en las rutas que Pro no ha registrado.

Ejemplo práctico: un informe semanal

Este script imprime en texto plano las cifras de la semana pasada. Ejecútalo desde cron los lunes por la mañana y pasa la salida a un correo o a un mensaje de chat. Necesita curl y jq.

#!/usr/bin/env bash
# The last seven days' numbers from Vireo, as plain text.
set -euo pipefail

SITE="${VIREO_SITE:?Set VIREO_SITE, e.g. https://example.com}"
AUTH="${VIREO_USER:?Set VIREO_USER}:${VIREO_APP_PASSWORD:?Set VIREO_APP_PASSWORD}"
API="$SITE/wp-json/vireo-analytics/v1/stats"

# The last seven full days. GNU date uses -d, macOS date uses -v.
if date -v-1d >/dev/null 2>&1; then
  END=$(date -v-1d +%F); START=$(date -v-7d +%F)
else
  END=$(date -d yesterday +%F); START=$(date -d '7 days ago' +%F)
fi
RANGE="start=${VIREO_START:-$START}&end=${VIREO_END:-$END}"

get() { curl -fsS -u "$AUTH" "$API/$1"; }

totals=$(get "totals?$RANGE")
echo "Vireo report for ${VIREO_START:-$START} to ${VIREO_END:-$END}"
echo "Pageviews: $(jq .pageviews <<<"$totals")  Visitors: $(jq .visitors <<<"$totals")"
echo
echo "Top pages:"
get "top-pages?$RANGE&limit=5" | jq -r '.[] | "  \(.pageviews)  \(.title // .path)"'
echo
echo "How people arrived:"
get "channels?$RANGE" | jq -r '.rows[] | select(.pageviews > 0) | "  \(.label): \(.pageviews) (\(.share_pct)%)"'
echo
echo "What changed:"
get "changes?$RANGE" | jq -r '"  " + .summary'

Guárdalo como vireo-weekly.sh, hazlo ejecutable y lánzalo:

VIREO_SITE=https://example.com VIREO_USER=your-username VIREO_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" ./vireo-weekly.sh

Informa de los últimos siete días completos. Define VIREO_START y VIREO_END para informar de otras fechas.

Vireo report for 2026-10-05 to 2026-10-11
Pageviews: 15  Visitors: 15

Top pages:
  6  How to pack for a month
  3  Pricing
  3  A week in Porto on foot
  3  /

How people arrived:
  Direct: 3 (20%)
  Search: 3 (20%)
  AI assistants: 3 (20%)
  Social: 6 (40%)

What changed:
  Collecting data, 15 views so far. Trends appear once there is a prior day to compare against.

Las mismas peticiones funcionan desde n8n, Zapier o Make con un paso de petición HTTP: autenticación Basic con tu nombre de usuario y tu contraseña de aplicación, y las URL de arriba.

Vireo Pro

Con una licencia de Pro activa, las rutas de Pro están bajo la misma ruta /stats/: visitantes en tiempo real, campañas, interacción, embudos, ingresos y más. Admiten los mismos start, end y limit, pero aquí start y end son opcionales y por defecto son los últimos 30 días. Consulta la referencia de la API.