Comment interroger mes analytics par programmation (Stats API) ?

La Stats API est une interface d'interrogation publique, à débit limité, qui vous permet de récupérer vos analytics Zenovay via HTTP. Utilisez-la pour créer des tableaux de bord personnalisés, intégrer des métriques en direct dans des outils BI, ou migrer des scripts depuis Plausible.

Ce que vous pouvez interroger

Endpoint	Ce qu'il retourne
GET /stats/aggregate	Totaux sur une période (visiteurs, pages vues, taux de rebond, durée moyenne de session).
GET /stats/timeseries	Un point de données par jour, heure ou mois sur la période.
GET /stats/breakdown	Meilleures pages, meilleurs pays, meilleurs navigateurs — toute dimension unique, triée par visiteurs.

Référence complète, tableaux de paramètres et exemples : docs.zenovay.com/api/external-api (cherchez la section « Stats API »).

La spécification OpenAPI 3.1 en direct est disponible à /api/external/v1/openapi.json — importez-la dans Postman, Insomnia, ou utilisez-la avec un générateur de code.

Exigence de plan

La Stats API est disponible sur les plans Pro, Scale et Entreprise. Le plan gratuit ne peut pas créer ni utiliser de clés API — les appels renvoient une erreur 403 API_PAID_PLAN_REQUIRED. Effectuez une mise à niveau dans Paramètres → Facturation.

Limites de débit par niveau

Plan	Limite de débit (par minute, cible)	Quota mensuel de requêtes
Gratuit	10	1 000
Pro	30	10 000
Scale	60	100 000
Entreprise	120	1 000 000

Lorsque vous dépassez la limite de débit de votre niveau, l'API retourne 429 Too Many Requests avec un en-tête Retry-After indiquant le nombre de secondes à attendre.

Comment la limitation de débit est appliquée. La limite par minute est une cible, pas un plafond strict. Nous utilisons la limitation de débit en périphérie de Cloudflare, qui est par centre de données avec une petite tolérance de pic — ainsi un client soutenu peut transitoirement voir 1,5 à 3 fois le nombre indiqué avant d'être limité, surtout si les requêtes se répartissent sur plusieurs régions. Le plafond strict est le quota mensuel de requêtes, qui est appliqué de manière atomique sur votre compte quel que soit l'origine des requêtes. Planifiez les charges de travail sensibles à la capacité en fonction du quota mensuel ; traitez le nombre par minute comme une cible de lissage.

Démarrage rapide

1. Obtenez une clé API (Pro+) — voir Comment obtenir une clé API ?. Les clés commencent par zv_.
2. Trouvez votre UUID de site — ouvrez le site dans votre tableau de bord Zenovay. L'UUID est dans l'URL : app.zenovay.com/domains/<UUID>.
3. Effectuez votre premier appel :

curl -G "https://api.zenovay.com/api/external/v1/stats/aggregate" \
  -H "X-API-Key: zv_YOUR_KEY" \
  --data-urlencode "site_id=YOUR_SITE_UUID" \
  --data-urlencode "period=7d" \
  --data-urlencode "metrics=visitors,pageviews"

Vous devriez recevoir quelque chose comme :

{
  "success": true,
  "data": {
    "results": {
      "visitors":  { "value": 12453 },
      "pageviews": { "value": 38219 }
    },
    "meta": { "period": "7d", "period_start": "...", "period_end": "..." }
  }
}

Cas d'utilisation courants

• Tableaux de bord personnalisés — récupérez des métriques agrégées dans Notion, Coda, Retool ou un outil BI interne toutes les heures.
• Migration depuis Plausible — la forme des paramètres (site_id, period, date, metrics, filters, property) est intentionnellement compatible avec Plausible. La plupart des scripts de migration fonctionnent après avoir remplacé l'URL de base et remappé site_id d'un domaine vers votre UUID Zenovay.
• Intégrations — affichez le nombre de visiteurs en direct sur votre page de statut ou votre site marketing (utilisez un proxy côté serveur ; n'exposez jamais votre clé API dans du code côté client).
• Rapports planifiés — récupérez les données de répartition une fois par jour et publiez-les sur Slack ou par e-mail.

Filtres

Vous pouvez limiter n'importe quelle requête à un sous-ensemble de visiteurs avec des filtres au style Plausible :

# Visiteurs américains uniquement
--data-urlencode "filters=country==US"

# Visiteurs américains + canadiens utilisant Chrome
--data-urlencode "filters=country==US,CA;browser==Chrome"

# Tout le monde sauf les pages /admin
--data-urlencode "filters=page!=/admin"

Clés de filtre autorisées : country, browser, device, os, source, utm_source, utm_medium, utm_campaign, page.

Limitation V1 : Lorsque vous fournissez des filters, seule la métrique visitors est calculée en V1 ; les autres métriques retournent null avec un indicateur meta.note. La prise en charge complète des filtres sur toutes les métriques sera disponible en V2. Les requêtes sans filtre prennent en charge toutes les métriques aujourd'hui.

Dépannage

Symptôme	Cause	Correction
401 UNAUTHORIZED "Missing API key"	Pas d'en-tête X-API-Key ou Authorization: Bearer	Ajoutez l'en-tête. Générez une clé dans Paramètres → Compte → Sécurité & accès si vous n'en avez pas.
401 UNAUTHORIZED "Invalid API key"	La clé a été révoquée, contient une faute de frappe, ou ne commence pas par zv_	Recopiez depuis Paramètres → Compte → Sécurité & accès.
403 FORBIDDEN "requires a Pro plan"	Votre équipe est sur le plan Gratuit	Effectuez une mise à niveau dans Paramètres → Facturation.
403 FORBIDDEN "does not have access"	La clé API était limitée à un seul site, mais le site_id ne correspond pas	Créez une clé à accès complet, ou appelez avec le bon site_id.
404 NOT_FOUND "Website not found"	UUID site_id incorrect	Vérifiez dans l'URL du tableau de bord.
400 MISSING_*	Paramètre de requête requis manquant	Ajoutez site_id, period et metrics (toujours requis).
400 INVALID_METRIC	Nom de métrique inconnu	Utilisez visitors, pageviews, visit_duration, bounce_rate ou events.
400 INTERVAL_PERIOD_MISMATCH	interval=hour avec un period autre que day	Utilisez period=day avec interval=hour, ou interval=day pour des périodes plus longues.
429 Too Many Requests	Limite de débit par niveau atteinte	Respectez l'en-tête Retry-After. Passez à un niveau supérieur si vous atteignez régulièrement cette limite.

Migration depuis Plausible

La forme des paramètres est intentionnellement proche de la Stats API v1 de Plausible. Différences :

Plausible	Zenovay	Notes
site_id=mysite.com	site_id=<UUID>	Plausible utilise une chaîne de domaine ; Zenovay utilise un UUID. Mappez une fois via GET /websites.
period, date	period, date	Même liste autorisée + custom:YYYY-MM-DD,YYYY-MM-DD.
metrics	metrics	visitors, pageviews, bounce_rate, visit_duration se mappent 1:1.
filters (format chaîne v1)	filters	Même forme key==value;key!=value.
filters (tableau JSON v2)	(V2 de la Stats API Zenovay)	Disponible ultérieurement.

Prochaines étapes

• Référence complète de la Stats API (docs) — chaque paramètre, chaque endpoint, chaque code d'erreur.
• Spécification OpenAPI 3.1 — pour la génération de code et les outils de test d'API.
• Authentification — en-têtes Bearer vs X-API-Key, rotation des clés.
• Présentation de l'API — tous les autres endpoints publics Zenovay (insights, anomalies, rétention, LTV, requête en langage naturel).