Menu de la documentationRéférence des abilities et de l'API REST

Référence des abilities et de l'API REST

Chaque ability et chaque route REST de Vireo, gratuites et Pro, avec leurs entrées, valeurs par défaut et retours. Les outils MCP portent les mêmes noms.

Sur cette page

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 /run de 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 : un site non nul renvoie vireo_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 site non nul renvoie vireo_site_pro (403), et un utilisateur qui ne peut pas lire les chiffres de ce site obtient vireo_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.