Endpoint de la REST API

GET /v1/sources-history

Répartition du trafic au fil du temps : nombre moyen de lecteurs simultanés par catégorie de source sur la dernière heure, les dernières 24 heures, aujourd’hui, hier, les 7 derniers jours ou une plage de dates personnalisée.

Requête

Historique disponible depuis le 16 novembre 2026

L’historique des sources est enregistré depuis le 16 novembre 2026 et s’enrichit chaque jour. L’enregistrement a commencé vers 16 h UTC : le 16 novembre ne contient donc que les heures de la soirée et sa valeur journalière n’est pas comparable à celles de journées complètes. Si une plage remonte avant le 16 novembre 2026, le paramètre from est ajusté à cette date et la réponse contient un avis ; une plage qui se termine avant cette date ne renvoie aucun point. Les périodes antérieures ne sont jamais renvoyées avec une valeur égale à zéro.

GET https://api.nowmetrix.com/v1/sources-history?site=TRACKER_ID&range=today

Utilisez cet endpoint pour suivre l’évolution de la répartition du trafic, par exemple pour savoir quand le trafic de Google Discover a commencé ou si le trafic issu de la recherche organique est plus faible qu’hier. Chaque point indique le nombre moyen de lecteurs simultanés par catégorie de source à l’heure correspondante. Il ne s’agit ni de visites ni de pages vues, et les valeurs ne doivent pas être additionnées au fil du temps ; pour obtenir des totaux, utilisez /v1/recap ou /v1/overview. Pour consulter les sources en temps réel individuellement, comme un réseau social ou une newsletter en particulier, utilisez /v1/sources.

Essayer dans l’API Playground

Authentification

Une clé API doit être transmise dans l’en-tête Authorization, sous la forme suivante : Authorization: Bearer nm_YOUR_KEY.

Paramètres de requête

Nom Type Obligatoire Description
site string obligatoire Identifiant du tracker. La clé API doit donner accès à ce tracker.
range string facultatif Plage temporelle. Valeurs possibles : 1h (60 dernières minutes, points toutes les 2 minutes), 24h (24 heures glissantes, points toutes les 10 minutes), today et yesterday (journée calendaire dans le fuseau horaire du tracker, points toutes les 10 minutes), 7d (aujourd’hui et les 6 jours précédents, points horaires) ou custom (nécessite start et end). Valeur par défaut : today.
start string facultatif Premier jour calendaire d’une plage personnalisée, au format YYYY-MM-DD et dans le fuseau horaire du tracker. Requis avec range=custom et interdit avec les autres plages. La date ne doit pas se situer dans le futur.
end string facultatif Dernier jour calendaire d’une plage personnalisée, au format YYYY-MM-DD, inclus. Requis avec range=custom. La plage ne peut pas dépasser 366 jours ; si la date de fin se situe dans le futur, elle est limitée à l’heure actuelle. La résolution dépend du nombre de jours pour lesquels des données ont été enregistrées : points toutes les 10 minutes jusqu’à 2 jours, points horaires jusqu’à 31 jours, puis points quotidiens pour les plages plus longues.

Exemple cURL

curl -H "Authorization: Bearer nm_YOUR_KEY" \
  "https://api.nowmetrix.com/v1/sources-history?site=TRACKER_ID&range=today"

Exemple de réponse

{
  "site": "TRACKER_ID",
  "range": "today",
  "start": null,
  "end": null,
  "timezone": "Europe/Zurich",
  "unit": "avg_concurrent_readers",
  "resolution_minutes": 10,
  "from": "2026-11-18T00:00:00+01:00",
  "to": "2026-11-18T09:24:00+01:00",
  "data_available_from": "2026-11-16",
  "notice": null,
  "updated_at": "2026-11-18T08:24:30+00:00",
  "stale": false,
  "categories": [
    "organic",
    "discover",
    "direct",
    "internal",
    "social",
    "referral",
    "email",
    "ai"
  ],
  "points": [
    {
      "t": "2026-11-18T09:00:00+01:00",
      "total": 412.6,
      "unattributed": 6.4,
      "values": {
        "organic": 96.2,
        "discover": 131.5,
        "direct": 88.1,
        "internal": 41.3,
        "social": 27.9,
        "referral": 12.6,
        "email": 7.2,
        "ai": 1.4
      }
    },
    {
      "t": "2026-11-18T09:10:00+01:00",
      "total": 428.3,
      "unattributed": 5.9,
      "values": {
        "organic": 98.7,
        "discover": 144,
        "direct": 86.4,
        "internal": 42.8,
        "social": 28.5,
        "referral": 12.1,
        "email": 8.6,
        "ai": 1.3
      }
    }
  ]
}

Champs de réponse

Champ Type Description
site string Identifiant du tracker utilisé pour la requête.
range string Plage temporelle demandée.
start string|null Premier jour demandé pour range=custom ; sinon, null.
end string|null Dernier jour demandé pour range=custom ; sinon, null.
timezone string Fuseau horaire du tracker, utilisé pour les jours calendaires et les horodatages, par exemple Europe/Zurich.
unit string Toujours avg_concurrent_readers : nombre moyen de lecteurs actifs simultanément pour chaque point.
resolution_minutes integer Durée de chaque point en minutes : 2, 10, 60 ou 1440 (une journée calendaire).
from string Début de la plage sous forme d’horodatage ISO 8601 avec le décalage du fuseau horaire du tracker. Si la plage demandée commence avant data_available_from, cette valeur est ajustée à cette date.
to string Fin de la plage sous forme d’horodatage ISO 8601 avec décalage. Pour les plages en cours, il s’agit de l’heure actuelle.
data_available_from string Premier jour pour lequel l’historique des sources a été enregistré : 2026-11-16. L’enregistrement a commencé vers 16 h UTC ce jour-là, qui est donc incomplet.
notice object|null Renseigné si la plage remonte avant data_available_from ; sinon, null. La requête aboutit tout de même avec HTTP 200.
notice.code string partial_history : la plage commence plus tôt, le paramètre from a donc été ajusté et aucun point n’est disponible pour les jours antérieurs. no_history : la plage se termine avant le début de l’enregistrement des données, le tableau points est donc vide.
notice.message string Brève explication en anglais destinée aux journaux ou à l’affichage.
updated_at string Horodatage UTC du calcul de l’historique.
stale boolean true si le résultat renvoyé est le dernier résultat valide, car le système de stockage de l’historique est temporairement indisponible.
categories[] array<string> Toutes les catégories de source, dans un ordre fixe : organic, discover, direct, internal, social, referral, email, ai. La liste est toujours complète, même si une catégorie ne compte aucun lecteur.
points[] array<object> Points classés par ordre chronologique. Les périodes sans données collectées sont omises ; des écarts sont donc possibles.
points[].t string Début du point sous forme d’horodatage ISO 8601 avec décalage. Lorsque l’heure recule à la fin de l’heure d’été, l’heure répétée est regroupée en un seul point.
points[].total number Nombre moyen de lecteurs simultanés pour toutes les sources, arrondi à une décimale.
points[].unattributed number Lecteurs inclus dans total auxquels aucune catégorie ne peut être attribuée. Cette valeur est généralement égale à 0 actuellement, et la somme des catégories correspond donc à total. Calculez toujours les proportions en divisant la valeur d’une catégorie par total, afin d’obtenir un résultat correct si des lecteurs ne sont pas attribués.
points[].values object Nombre moyen de lecteurs simultanés par catégorie, indexé par les noms figurant dans categories. Les catégories sans lecteurs ont la valeur 0.

Actualisation des données et mise en cache

Les réponses sont mises en cache par tracker et par plage : 60 secondes pour 1h, 24h et today, 5 minutes pour 7d et 30 minutes pour yesterday. Les plages personnalisées sont mises en cache en fonction des dates de début et de fin : 30 minutes si la plage est terminée, sinon 60 secondes avec des points toutes les 10 minutes et 5 minutes avec des points horaires ou quotidiens. Si le système de stockage de l’historique est temporairement indisponible, le dernier résultat valide est renvoyé avec stale: true et un en-tête Warning. La réponse inclut également X-NowMetrix-Microcache, dont la valeur est HIT, MISS ou STALE.

Erreurs

HTTP Code Description
400 site_required Le paramètre site requis est manquant.
401 missing_token L’en-tête Authorization est manquant.
401 invalid_token Le jeton est invalide ou a été révoqué.
403 site_not_authorized La clé API ne donne pas accès à ce tracker.
429 rate_limit_exceeded La limite de requêtes a été dépassée.
503 redis_unavailable Le système de traitement des données en temps réel est temporairement indisponible.
400 invalid_range Le paramètre range doit être égal à 1h, 24h, today, yesterday, 7d ou custom.
400 invalid_date_range start ou end est manquant ou ne correspond pas à une date YYYY-MM-DD valide ; start est postérieur à end ou se situe dans le futur ; la plage dépasse 366 jours ; ou start et end ont été transmis sans range=custom.
503 source_history_unavailable L’historique des sources est temporairement indisponible et aucun résultat récent n’est en cache. Réessayez après le délai indiqué dans l’en-tête Retry-After.
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}