L’API REST de Vireo renvoie en JSON les mêmes chiffres que votre tableau de bord. Elle est en lecture seule et se trouve sous /wp-json/vireo-analytics/v1. Chaque route est listée dans la référence de l’API.
1. Créer un mot de passe d’application
L’API se connecte comme un utilisateur WordPress, et seuls les utilisateurs qui peuvent ouvrir le tableau de bord de Vireo obtiennent une réponse. Voir Qui peut voir les chiffres.
- Dans WordPress, allez dans Utilisateurs > Profil.
- Sous Mots de passe d’application, saisissez un nom comme « Reports script » et cliquez sur « Ajouter un mot de passe d’application ».
- Copiez le mot de passe. Il ne s’affiche qu’une seule fois.
WordPress ne propose les mots de passe d’application que sur les sites servis en HTTPS, ou déclarés comme environnement de développement local.
2. Faire votre première requête
Envoyez le nom d’utilisateur et le mot de passe d’application avec l’authentification HTTP Basic. Avec curl, c’est l’option -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}
Le temps sur la page et le taux de rebond reviennent à null quand la période n’en a aucun d’enregistré. Sur un site en version 0.13.0, ils contiennent des valeurs, par exemple "avg_time_on_page_seconds":74,"timed_views":512,"bounce_rate_percent":61.4. Voir la liste des champs.
Pour garder le mot de passe hors de l’historique de votre shell, placez-le d’abord dans une variable d’environnement :
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"
Les exemples ci-dessous utilisent ces deux variables.
Dates et limites
startetendsont des dates au formatYYYY-MM-DD, dans le fuseau horaire de votre site. Les deux sont obligatoires sur les routes/stats/....- Les dates sont maintenues dans les deux dernières années : une date plus ancienne devient le premier jour autorisé, et une date future devient aujourd’hui.
- Les routes qui renvoient une liste acceptent
limit. Les valeurs vont de 1 à 100 ; toute valeur hors de cet intervalle y est ramenée. - Il n’y a pas de pagination. Une liste renvoie les
limitpremières lignes, classées. - Les paramètres qu’une route n’utilise pas sont ignorés.
Listes et lignes
Les routes qui renvoient une liste répondent sous l’une de ces deux formes :
/stats/daily,/stats/top-pages,/stats/top-referrers,/stats/countries,/stats/eventset/stats/clicksrenvoient un simple tableau JSON, comme elles l’ont toujours fait. C’est aussi le cas de/stats/goalsavec Vireo Pro.- Toutes les autres listes, comme
/stats/channels,/stats/hourly,/stats/vitalset/stats/annotations, renvoient un objet avec la liste sousrows:{"rows": [...]}. Un résultat vide est{"rows": []}.
Les routes qui renvoient un seul enregistrement, comme /stats/totals ou /stats/post/{id}, renvoient cet objet tel quel. La référence de l’API donne la forme de chaque route.
Pages les plus vues
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 vaut 0 pour les pages qui ne sont pas un article unique, comme la page d’accueil ou une archive.
D’où venaient les visiteurs
Par 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}
]}
Contrairement aux pages les plus vues, cette route enveloppe sa liste dans rows. Listes et lignes explique quelles routes le font.
Par site, puis un site en détail :
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"
Ajoutez post_id=4, ou path=/pricing/, pour obtenir les recherches qui mènent à une page. Les données de Google ont deux à trois jours de retard.
Si Search Console n’est pas connectée, vous obtenez quand même un 200, avec connected à false :
{"connected":false,"message":"Google Search Console is not connected. Connect it under Vireo Analytics, Settings, Search Console & API.","summary":null,"queries":[]}
Les stats d’un article
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}]
}
Un article qui n’existe pas, ou que l’utilisateur ne pourrait pas lire sur le site (un brouillon, par exemple), renvoie 404.
Erreurs
| Statut | Code | Signification |
|---|---|---|
| 400 | rest_missing_callback_param |
Un paramètre obligatoire manque, en général start ou end. |
| 400 | rest_invalid_param |
Une date n’est pas au format YYYY-MM-DD. |
| 400 | vireo_rest_bad_range |
end est antérieur à start. |
| 401 | rest_forbidden |
Pas de connexion, ou WordPress n’a pas accepté le nom d’utilisateur et le mot de passe d’application. |
| 403 | rest_forbidden |
L’utilisateur est connecté mais ne peut pas voir le tableau de bord de Vireo. |
| 404 | vireo_ability_not_found |
L’article n’existe pas ou n’est pas visible. |
Une route Pro sur un site sans licence Pro active renvoie 403, ou 404 pour les routes que Pro n’a pas enregistrées.
Exemple concret : un rapport hebdomadaire
Ce script affiche en texte brut les chiffres de la semaine dernière. Lancez-le depuis cron le lundi matin et envoyez la sortie dans un e-mail ou un message de discussion. Il demande curl et 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'
Enregistrez-le sous vireo-weekly.sh, rendez-le exécutable et lancez-le :
VIREO_SITE=https://example.com VIREO_USER=your-username VIREO_APP_PASSWORD="xxxx xxxx xxxx xxxx xxxx xxxx" ./vireo-weekly.sh
Il rend compte des sept derniers jours complets. Définissez VIREO_START et VIREO_END pour d’autres dates.
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.
Les mêmes requêtes fonctionnent depuis n8n, Zapier ou Make avec une étape de requête HTTP : authentification Basic avec votre nom d’utilisateur et votre mot de passe d’application, et les URL ci-dessus.
Vireo Pro
Avec une licence Pro active, les routes de Pro se trouvent sous le même chemin /stats/ : visiteurs en temps réel, campagnes, engagement, entonnoirs, revenus et plus encore. Elles acceptent les mêmes start, end et limit, mais start et end y sont facultatifs et couvrent par défaut les 30 derniers jours. Voir la référence de l’API.