Chaque rapport existe de trois façons, et toutes renvoient les mêmes données :
- une ability, comme
vireo-analytics/get-top-pages, pour PHP et l’Abilities API - un outil MCP, comme
vireo-analytics-get-top-pages, pour les assistants IA - une route REST, comme
GET /wp-json/vireo-analytics/v1/stats/top-pages, pour les scripts
Chacune est en lecture seule et demande un utilisateur avec la capability view_vireo_analytics. Celles de Pro demandent aussi une licence Vireo Pro active.
Entrées communes
| Entrée | Type | Remarques |
|---|---|---|
start |
date, YYYY-MM-DD |
Par défaut, 30 jours avant end. Obligatoire sur les routes REST gratuites. |
end |
date, YYYY-MM-DD |
Par défaut, aujourd’hui. Obligatoire sur les routes REST gratuites. |
limit |
entier, 1 à 100 | Valeur par défaut indiquée pour chaque entrée. Pas de pagination. |
Les dates sont dans le fuseau horaire de votre site et maintenues dans les deux dernières années. Sur les routes REST gratuites, une date mal formée renvoie 400 ; ailleurs, la valeur par défaut est utilisée.
Les abilities, et donc les outils MCP, n’acceptent que les entrées listées pour elles. Toute autre clé est refusée avec ability_invalid_input. Les routes REST ignorent les paramètres de requête qu’elles n’utilisent pas.
Formes des réponses
Chaque ability renvoie un objet JSON. Quand les données forment une liste, elle se trouve sous rows : {"rows": [...]}, ou {"rows": []} quand il n’y a rien à signaler. Le même objet revient depuis PHP, depuis la route /run de l’Abilities API, depuis MCP et depuis les routes REST, sauf les routes marquées † ci-dessous, qui renvoient un simple tableau.
Abilities
Les abilities du plugin gratuit :
| Ability | Route REST | Entrée supplémentaire | Renvoie |
|---|---|---|---|
get-totals |
/stats/totals |
pageviews, visitors, days, avg_daily, avg_time_on_page_seconds, timed_views, bounce_rate_percent |
|
get-daily-stats |
/stats/daily † |
rows, une par jour : date, pageviews, visitors |
|
get-hourly-stats |
/stats/hourly |
rows, une par heure : date, hour, pageviews, visitors. Au plus les deux derniers jours de la période ; aujourd’hui par défaut. |
|
get-changes |
/stats/changes |
limit (3) |
La période comparée à la précédente : pageviews, visitors, change_pct, prior, une phrase summary, headline, detail, mix, les pages et sources qui ont gained et lost, et les avertissements health |
get-highlights |
/stats/highlights |
limit (3) |
start, end et highlights : chacun avec un kind et un text prêt à citer. Par défaut, les sept derniers jours complets. |
get-top-pages |
/stats/top-pages † |
limit (10) |
rows : post_id, path, title, pageviews, visitors, avg_time_on_page_seconds |
get-top-referrers |
/stats/top-referrers † |
limit (10) |
rows : url (l’hôte référent), pageviews, visitors |
get-traffic-sources |
/stats/channels |
rows, une par canal (direct, search, ai, social, referral) : source, label, pageviews, visitors, share_pct |
|
get-referrer-detail |
/stats/referrer |
host (obligatoire), limit (10) |
host, label, source, les totaux period, la série daily, et les pages vers lesquelles il a envoyé des visiteurs |
get-ai-referrals |
/stats/ai-referrals |
start, end, since (le premier jour où les robots ont été comptés, quand il est postérieur à start), referred_visitors, crawler_requests, crawler_requests_per_reader, et by_source par assistant |
|
get-search-console |
/stats/search-console |
limit (10), post_id ou path |
connected ; puis, pour l’ensemble du site, summary (clicks, impressions, position, ctr) et les queries principales, ou, avec post_id ou path, les queries de cette page |
get-countries |
/stats/countries † |
limit (20) |
rows : code, name, pageviews, visitors |
get-devices |
/stats/devices |
browsers, os et device_types, chacun avec des lignes label, visitors, pct |
|
get-events |
/stats/events † |
name, limit (10) |
rows des principaux événements : name, count, unique_count. Avec name, les valeurs de cet événement. |
get-event-detail |
/stats/event/{name} |
name (obligatoire), limit (20) |
Les totaux period, la série daily, value_count et les values principales |
get-post-stats |
/stats/post/{id} |
post_id (obligatoire) |
post_id, title, url, lifetime, period, daily, referrers |
get-clicks |
/stats/clicks |
limit (20) |
rows : kind, label, target, page, clicks, previous_clicks. Les liens vers vos propres pages et les boutons les plus cliqués, avec la page où chacun se trouvait. |
get-404s |
/stats/404s |
limit (20) |
rows (path, hits, top_referrer), broken_links (path, hits, linked_from, linking_pages) et probes |
get-bot-stats |
/stats/bots |
filtered_requests, counted_pageviews, share_of_all_requests_pct, ai_crawler_requests, et by_category (category, label, hits) |
|
get-vitals |
/stats/vitals |
rows, une par métrique (lcp, inp, cls) : metric, label, p75, display, rating, samples |
|
get-annotations |
/stats/annotations |
rows des notes de graphique : id, date, label |
|
get-year-review |
/stats/year-review |
year (année en cours) |
Le Bilan de l’année pour une année civile. N’accepte ni start ni end. |
get-goals |
/stats/goals † |
Demande Pro. rows, une par objectif : id, name, type, pattern, value, active, completions, unique_completions, total_value |
Les noms d’abilities commencent par vireo-analytics/ ; le tableau l’omet. /stats/goals/{id} renvoie le détail d’un objectif.
† Via REST, ces routes renvoient la liste sous forme de simple tableau au lieu de {"rows": [...]}. Partout ailleurs, et sur toutes les autres routes, la forme est celle indiquée.
Les chemins, les requêtes, les référents et les valeurs d’événements viennent des visiteurs. Chaque ability en retire les caractères de contrôle, les retours à la ligne et les crochets avant de les renvoyer.
Temps sur la page et taux de rebond, à partir de Vireo Analytics 0.13.0 :
| Champ | Type | Signification |
|---|---|---|
avg_time_on_page_seconds |
entier ou null |
Nombre moyen de secondes actives par vue chronométrée. Sur get-totals pour l’ensemble du site, sur chaque ligne de get-top-pages pour cette page. null quand aucune vue de la période n’a rapporté de durée. |
timed_views |
entier | Sur get-totals : le nombre de vues que couvre la moyenne. 0 s’il n’y en a aucune. |
bounce_rate_percent |
nombre ou null |
Sur get-totals : la part des visiteurs qui ont vu une seule page, à une décimale. null quand le comptage des rebonds ne couvre aucun jour de la période, ou qu’aucun visiteur n’a été compté. |
Ce qui est compté donne les définitions exactes. Aucun de ces deux chiffres ne peut être ventilé par pays, appareil ou source.
Abilities Pro
Toutes demandent une licence Vireo Pro active. Via REST, start et end sont facultatifs ici et couvrent par défaut les 30 derniers jours.
| Ability | Route REST | Entrée supplémentaire | Renvoie |
|---|---|---|---|
get-realtime |
/stats/realtime |
aucune, pas même de dates | active_last_5_minutes, window_minutes, les pages, referrers et countries principaux des 15 dernières minutes avec leurs visitors et leur change par rapport aux 15 précédentes, et arrived_via par canal |
get-campaigns |
/stats/campaigns |
limit (20) |
campaigns : source, medium, campaign, visitors, pageviews |
get-site-searches |
/stats/site-searches |
limit (20), view (top, zero_results ou no_click ; top par défaut), engine (wp, woocommerce, searchwp, relevanssi, fibosearch, elasticpress ou live ; tous par défaut) |
start, end, engine, un summary avec l’évolution par rapport à la période précédente, engines, et les termes : query, searches, results, clicks, click_through_rate, average_click_position, searches_with_no_click, left_after_search |
get-search-journeys |
/stats/search-journeys |
limit (20), engine |
refinements (searched, then_searched, visits) et after_search : visitors_who_searched, orders, revenue et goal_completions (goal, completions) |
get-leads-by-source |
/stats/leads-by-source |
limit (20) |
leads : source, medium, campaign, leads, people, previous_leads, visitors, conversion_rate et les forms par lesquels ils sont arrivés (form, leads) |
get-outbound-clicks |
/stats/outbound |
limit (10) |
external_sites (host, clicks) et affiliate_links (path, clicks) |
get-downloads |
/stats/downloads |
limit (10) |
downloads : host, path, clicks |
get-engagement |
/stats/engagement |
limit (10) |
site et les pages page par page : samples, avg_seconds, avg_scroll_pct. À partir de Pro 1.4.2 avec Vireo Analytics 0.13.0 ou plus récent, avg_seconds est le temps sur la page du plugin gratuit, et vaut null quand il n’y en a pas pour la période. |
get-entry-exit-pages |
/stats/entry-exit |
limit (10) |
entry_pages et exit_pages : path, entries, exits, exit_ratio |
get-page-paths |
/stats/page-paths |
path, limit (20) |
Sans path, les pairs principales (from, to, visits). Avec, là où les gens sont allés ensuite, next (to, visits, share_pct). |
get-authors |
/stats/authors |
limit (10) |
authors : author_id, name, posts_read, pageviews, visitors, avg_per_post |
get-post-types |
/stats/post-types |
post_types : chaque type avec son nombre d’articles lus, ses pages vues, ses visiteurs et sa part |
|
get-taxonomy-terms |
/stats/taxonomy-terms |
taxonomy (category), limit (10) |
taxonomy, tracked_taxonomies, et terms : term_id, name, slug, pageviews, visitors, url |
get-page-vitals |
/stats/page-vitals |
metric (lcp, inp ou cls ; lcp par défaut), limit (10) |
metric, unit, et les pages les pires en premier : path, p75, samples, rating. Les pages avec moins de 10 échantillons sont écartées. |
get-cities |
/stats/cities |
limit (10) |
database_ready, et cities : pays, région et ville avec pages vues et visiteurs |
get-funnels |
/stats/funnels |
funnels : id, name, et steps (step, goal_id, goal, visitors, pct_from_previous, pct_from_first) |
Pro : sites connectés
Ajoutées dans Pro 1.2.0, pour les agences qui lisent plusieurs sites via une seule installation. Le site 0 est l’installation que vous appelez ; les sites connectés sont numérotés à partir de 1.
| Ability | Route REST | Entrée supplémentaire | Renvoie |
|---|---|---|---|
get-sites |
/stats/sites |
limit (100) |
count de sites connectés, la limit de la formule, accepts_site (les outils qui acceptent site), et sites : id, name, url, this_site, last_data |
get-sites-overview |
/stats/sites-overview |
start, end, prior_start, prior_end, et sites, les plus actifs en premier : les champs de get-sites plus pageviews, visitors, prior_pageviews, prior_visitors, pageviews_change_pct, visitors_change_pct |
L’entrée site
Avec Pro 1.2.0 actif, ces abilities gratuites acceptent une entrée supplémentaire site (entier, 0 par défaut) pour lire un site connecté au lieu de celui-ci : get-totals, get-daily-stats, get-hourly-stats, get-changes, get-highlights, get-top-pages, get-top-referrers, get-traffic-sources, get-referrer-detail, get-ai-referrals, get-countries, get-devices, get-events, get-event-detail, get-404s, get-bot-stats, get-vitals, get-annotations.
- Elle fonctionne via les abilities, MCP et la route
/runde l’Abilities API. Les routes REST gratuites/stats/...ne l’acceptent pas et répondent pour cette installation. - Un ID qui ne correspond à aucun site connecté renvoie
vireo_site_unknown(404 via REST). - Les abilities propres à Pro n’acceptent pas
site: unsitenon nul renvoievireo_site_unsupported(400). Les abilities gratuites absentes de la liste ci-dessus la refusent comme entrée inconnue (ability_invalid_input, 400). - Sans licence Pro active, tout
sitenon nul renvoievireo_site_pro(403), et un utilisateur qui ne peut pas lire les chiffres de ce site obtientvireo_site_forbidden(403). - Les réponses pour un site connecté sont aplaties de la même façon que celles de ce site.
Pro : abilities de boutique
Enregistrées uniquement tant qu’une boutique compatible est active : WooCommerce, Easy Digital Downloads, FluentCart, Freemius, Paid Memberships Pro, Restrict Content, MemberPress, LifterLMS, GiveWP ou SureCart. Chacune accepte store (woo, edd, fluentcart, freemius, pmpro, rcp, memberpress, lifterlms, give ou surecart) pour se limiter à une boutique ; omettez-le pour les prendre toutes.
| Ability | Route REST | Entrée supplémentaire | Renvoie |
|---|---|---|---|
get-revenue |
/stats/revenue (forme propre, ci-dessous) |
store |
revenue net, orders, conversions, items, visitors, revenue_per_visitor, currency |
get-daily-revenue |
store |
days : date, revenue, orders |
|
get-revenue-forecast |
/stats/revenue-forecast |
store ; n’accepte pas de période |
available, reason, history_days, min_history_days, store, currency. Quand available : month (start, end, so_far, days_left, expected, low, high), next_30 (start, end, expected, low, high), et les days et month_days projetés (date, revenue). Avec moins de 28 jours de commandes, ou aucun revenu sur les 8 dernières semaines, renvoie available: false avec un reason et un message. |
get-revenue-by-source |
/stats/sources (forme propre, ci-dessous) |
store, limit (10) |
sources par source, medium et campagne, avec commandes et panier moyen |
get-revenue-by-landing-page |
/stats/landing-pages |
store, limit (10) |
pages : path, orders, revenue, aov, entries, conversion |
get-top-products |
/stats/products (forme propre, ci-dessous) |
store, limit (10) |
products : product_id, name, views, add_to_cart, purchases, revenue, conv_rate |
get-store-funnel |
/stats/store-funnel |
store |
stages de la vue du produit à l’achat : stage, count, la part de l’étape précédente, et si la boutique la rapporte |
get-subscriptions |
/stats/subscriptions |
store, limit (10) |
mrr, subscribers, currency, other_currencies, period (start_mrr, end_mrr, net, new, expansion, reactivation, contraction, churn, nombres d’abonnés, active_at_start, active_at_end, logo_churn_rate), une trend sur 12 mois, et le MRR by_source et by_landing_page |
get-stores |
Quelles boutiques sont connected et lesquelles ont des commandes sur la période (with_orders) |
/stats/revenue, /stats/products et /stats/sources sont antérieures aux abilities et gardent leur propre forme de réponse. /stats/revenue renvoie range, store, totals, daily, revenue_per_visitor et currency ; /stats/products et /stats/sources renvoient leurs lignes sous forme de simple liste. Les trois exigent start et end.
Trois autres rapports sont des routes REST uniquement, sans ability ni outil MCP. Ils acceptent start, end, limit et store comme /stats/revenue, et renvoient les champs de synthèse avec une liste à côté :
| Route REST | Renvoie |
|---|---|
/stats/abandonment |
abandoned, value, valued, checkouts, rate, carts, et sources : source, medium, campaign, abandoned, value |
/stats/coupons |
orders, with_coupon, discount, share, et coupons : code, orders, revenue, discount, aov |
/stats/refunds |
orders, full, partial, amount, placed, rate, et refunds : store, order_id, date, refunded_date, total, refunded, full, is_renewal, source, medium, campaign, url |
Chacune renvoie aussi currency. Les revenus sont nets des remboursements. Les totaux sont dans la devise de la boutique, sans conversion.
Routes REST
Toutes sont en GET sous /wp-json/vireo-analytics/v1, et s’authentifient comme décrit dans Récupérer vos statistiques avec l’API REST. La route de chaque rapport figure dans les tableaux ci-dessus.
GET /stats/last-hour renvoie pageviews pour les 60 dernières minutes, une series de douze comptages de cinq minutes et as_of (un temps Unix), pour la carte Dernière heure ; elle n’a ni ability ni outil MCP.
Une autre route ne sert pas à lire des données : avec Pro et Freemius, POST /freemius/webhook reçoit les événements de paiement de Freemius. Voir Suivi des revenus.
Routes de l’Abilities API
| Route | Usage |
|---|---|
GET /wp-json/wp-abilities/v1/abilities?category=vireo-analytics |
Lister les abilities de Vireo, avec leurs schémas d’entrée et de sortie |
GET /wp-json/wp-abilities/v1/abilities/{name}/run?input[key]=value |
En exécuter une. Le nom garde son slash, par exemple vireo-analytics/get-totals. |
MCP
/wp-json/vireo-analytics/mcp expose chaque ability ci-dessus comme un outil, nommé avec un tiret à la place du slash : vireo-analytics-get-top-pages. Un développeur peut modifier la liste avec le filtre vireo_mcp_tools.