API de zstats

Toutes les données du tableau de bord sont disponibles en JSON (ou en CSV pour les exports). Créez un accès Lecture seule dans Paramètres › Accès : son jeton (zst_…) s’envoie dans l’en-tête Authorization: Bearer …, jamais dans l’adresse. Dans les exemples, remplacez exemple.fr par votre site et gardez le jeton dans une variable d’environnement :

export ZSTATS_TOKEN=zst_…

Jours au format AAAA-MM-JJ, heure de Paris. Réponses : 200 (JSON), 400 (paramètre invalide, avec error), 401 (jeton absent ou invalide), 403 (droits insuffisants), 429 (trop de requêtes). Les modifications (objectifs, alertes, paramètres…) sont réservées au jeton administrateur et notées dans le journal d’activité.

Lecture (accès « Lecture seule » ou administrateur)

GET /api/sites

Liste des sites suivis, avec les visiteurs des 5 dernières et 30 dernières minutes.

curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/sites"

GET /api/stats

Toutes les statistiques d’un site sur une période : totaux, pages, provenances, campagnes, pays, appareils, objectifs, parcours, groupes de contenus (groups), classement des contenus (ranking)…

  • site (obligatoire)
  • from, to : jours AAAA-MM-JJ (30 derniers jours par défaut, 400 jours au plus)
  • compare : previous (défaut), year ou custom (avec cmpFrom, cmpTo)
  • section : rubrique, ex. /blog
  • filter : dimension:valeur (3 au plus ; referrer, utm_source, utm_campaign, country, region, city, lang, device, os, browser, grp, hosting, page ; hosting:none = sans hébergeurs ; page:/adresse = visiteurs ayant vu cette page)
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/stats?site=exemple.fr&from=2026-09-01&to=2026-09-30"

GET /api/overview

Vue d’ensemble de tous les sites sur une période (totaux et période comparée).

  • from, to, compare
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/overview?from=2026-09-01&to=2026-09-30"

GET /api/overview-daily

Visiteurs par jour des 8 sites les plus visités.

  • from, to
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/overview-daily?from=2026-09-01&to=2026-09-30"

GET /api/realtime

Visiteurs en ce moment, pages ouvertes, provenances, dernières actions.

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/realtime?site=exemple.fr"

GET /api/export

Export CSV d’un tableau (ou de toutes les actions, table=events).

  • site, from, to, section, filter
  • table : overview, events, pages, ranking, referrers, campaigns, countries…
  • detail=1 : colonnes de la période comparée
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/export?site=exemple.fr&table=pages&from=2026-09-01&to=2026-09-30"

GET /api/explain

« Pourquoi ? » : ce qui explique l’écart de visiteurs avec la période comparée.

  • site, from, to, compare
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/explain?site=exemple.fr"

GET /api/forecast

Projection du mois en cours.

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/forecast?site=exemple.fr"

GET /api/year-over-year

12 derniers mois face aux mêmes mois de l’année précédente.

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/year-over-year?site=exemple.fr"

GET /api/years

Années superposées : visiteurs et pages vues de chaque mois, par année civile (les 5 dernières au plus) ; null avant le premier mois mesuré et pour les mois à venir.

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/years?site=exemple.fr"

GET /api/targets

Caps du mois du site : pour chacun, la mesure (visitors, pageviews ou goal:<id>), le chiffre visé, le chiffre actuel, la part atteinte et la projection à la fin du mois. PUT {metric, value} (administrateur) fixe un cap, value: null le retire.

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/targets?site=exemple.fr"

GET /api/page-effect

Effet d’un changement sur une page : visiteurs, rebond, défilement, lecture en entier, temps moyen et clics par visiteur, sur les jours d’avant et à partir de la date.

  • site, path (/…)
  • day : date du changement (AAAA-MM-JJ)
  • days : 1 à 60 (14 par défaut)
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/page-effect?site=exemple.fr&path=/blog/article&day=2026-09-15"

GET /api/declining

Contenus en perte de vitesse : pages qui ont perdu au moins 30 % de leurs visiteurs (4 dernières semaines contre les 4 précédentes).

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/declining?site=exemple.fr"

GET /api/changes

Changements suivis d’un site, avec le jour du bilan (dueDay) et, une fois fait, sa phrase (result). POST {path, day, note?} et DELETE /api/changes/<id> : administrateur.

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/changes?site=exemple.fr"

GET /api/page

Fiche d’une page sur une période : mesures, visiteurs par jour, provenances, appareils et pays de ses visiteurs, problèmes, changements suivis, objectifs atteints par ses visiteurs (goals : personnes, part, taux de tout le site), période précédente de même durée (previous : visiteurs, vues), navigation interne (flow : pages vues juste avant et juste après ; null = arrivée ou départ).

  • site, path (/…)
  • from, to : AAAA-MM-JJ
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/page?site=exemple.fr&path=/blog/article&from=2026-09-01&to=2026-09-30"

GET /api/segment

Fiche d’un segment : visiteurs d’un pays, d’un appareil ou venus d’une provenance ou d’une campagne — pages d’arrivée et pages vues, engagement, objectifs atteints, appareils et pays.

  • site
  • dim : referrer, country, device, utm_source, utm_campaign
  • value
  • from, to : AAAA-MM-JJ
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/segment?site=exemple.fr&dim=country&value=FR&from=2026-09-01&to=2026-09-30"

GET /api/referrer

Fiche d’une provenance : visiteurs venus de ce site, leurs pages d’arrivée et pages vues, engagement, objectifs atteints, appareils et pays.

  • site, referrer
  • from, to : AAAA-MM-JJ
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/referrer?site=exemple.fr&referrer=google.com&from=2026-09-01&to=2026-09-30"

GET /api/goals/<id>/paths

Ce qui mène à un objectif : personnes qui l’ont atteint, pages vues avant en moyenne, pages vues avant (personnes, visiteurs de la page, part qui atteint l’objectif), pages qui y mènent le mieux (best, 20 visiteurs au moins), pages d’arrivée et provenances de ces personnes, personnes par jour (daily).

  • site
  • from, to : AAAA-MM-JJ
  • filter : filtres par visiteur, comme /api/stats
  • format=csv : export CSV (Excel en français)
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/goals/1/paths?site=exemple.fr&from=2026-09-01&to=2026-09-30"

GET /api/goals/suggest

Objectifs suggérés : actions fréquentes des 30 derniers jours (clics, formulaires, téléchargements, événements, pages) qui ne sont pas encore des objectifs, prêtes à envoyer à POST /api/goals.

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/goals/suggest?site=exemple.fr"

GET /api/new-pages

Nouveaux contenus (pages vues pour la première fois depuis 30 jours) et meilleur moment pour publier (timing).

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/new-pages?site=exemple.fr"

GET /api/views

Vues enregistrées du tableau de bord (nom et paramètres de l’adresse). POST {name, query} et DELETE /api/views/<id> : administrateur.

curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/views"

GET /api/suspicious

Trafic suspect de la période : réseaux sans lecture ni clic qui pèsent lourd dans les pages vues.

  • site, from, to
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/suspicious?site=exemple.fr&from=2026-09-01&to=2026-09-30"

GET /api/campaigns

Liens de campagne créés et leurs résultats.

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/campaigns?site=exemple.fr"

GET /api/annotations

Annotations d’un site (et celles communes à tous, site=*).

  • site
  • from, to (facultatifs)
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/annotations?site=exemple.fr"

GET /api/goals

Objectifs d’un site.

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/goals?site=exemple.fr"

GET /api/funnels

Parcours de conversion d’un site.

  • site
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/funnels?site=exemple.fr"

GET /api/me

Rôle de l’accès utilisé (admin, read, annotate), son nom, et news : numéro de la dernière nouveauté.

curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/me"

GET /api/news

« Quoi de neuf ? » : nouveautés des dernières mises à jour (numéro, jour, titre, points), les plus récentes d’abord.

curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/news"

Annotation (accès « Annotations automatiques » ou administrateur)

POST /api/annotations

Ajoute une annotation (◆ sur le graphique), par exemple à chaque mise en ligne.

  • site (dans l’adresse ; * pour tous les projets)
  • corps JSON : {"text": "…", "day": "AAAA-MM-JJ"} (jour facultatif : aujourd’hui)
curl -s -X POST -H "Authorization: Bearer $ZSTATS_TOKEN" \
  -d '{"text": "Version 2.3 en ligne"}' \
  "https://www.zstats.fr/api/annotations?site=exemple.fr"

Administration (jeton administrateur)

GET /api/reports/preview

Bilan de l’année d’un site (HTML du rapport annuel et son objet), l’année en cours arrêtée à aujourd’hui.

  • site
  • frequency=yearly
  • year : 2000 à l’année en cours (année précédente par défaut)
curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/reports/preview?frequency=yearly&site=exemple.fr&year=2025"

GET /api/push

Notifications sur un appareil : clé publique VAPID et appareils abonnés. POST {endpoint, keys: {p256dh, auth}, name} abonne un navigateur (services de notification connus seulement), DELETE {endpoint} le retire, POST /api/push/test envoie un essai.

curl -s -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/push"

DELETE /api/tokens/phones

Déconnecte tous les téléphones connectés par QR code (révoque leurs accès) ; renvoie {revoked}.

curl -s -X DELETE -H "Authorization: Bearer $ZSTATS_TOKEN" \
  "https://www.zstats.fr/api/tokens/phones"

Lien de partage (sans jeton)

GET /api/share/<jeton>/year

Bilan de l’année du site d’un lien de partage (Paramètres › Partage), sans la ligne « À surveiller » ; refusé (403) pour un lien limité à une rubrique. Le lien /share/<jeton>?bilan=AAAA ouvre le tableau de bord sur ce bilan.

  • year
curl -s "https://www.zstats.fr/api/share/$ZSTATS_SHARE/year?year=2025"