Point de terminaison de l’API REST

GET /v1/recap

Données Recap, indicateurs récapitulatifs et pages principales pour des périodes prédéfinies ou une période personnalisée.

Requête

GET https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=25

Utilisez Recap lorsque votre intégration doit consulter l’historique : rapports historiques, exportations des pages principales, périodes personnalisées ou résultats filtrés par recherche.

Authentification

Une clé API est requise dans l’en-tête Authorization : Authorization: Bearer nm_YOUR_KEY.

Paramètres de requête

Nom Type Obligatoire Description
site string obligatoire Identifiant du tracker. La clé API doit disposer d’un accès à ce tracker.
preset string facultatif Période prédéfinie. Valeur parmi today, yesterday, last7, last14, last30, last90, this_month, last_month, all_time, custom. Valeur par défaut : last30.
start date facultatif Date de début pour preset=custom. Format : YYYY-MM-DD.
end date facultatif Date de fin pour preset=custom. Format : YYYY-MM-DD.
limit integer facultatif Nombre maximal de pages principales par réponse, y compris les réponses paginées. Les valeurs sont limitées à 1–100. Valeur par défaut : 100.
q string facultatif Terme de recherche pour les pages principales. Recherche dans l’URL, le titre ou l’auteur. Alias : search.
search string facultatif Alias de q.
offset integer facultatif Commencez la pagination avec offset=0. Entier compris entre 0 et 2000. Les pages suivantes nécessitent snapshot. Sans offset ni snapshot, la réponse existante reste inchangée.
snapshot string facultatif Utilisez pagination.snapshot_id de la première réponse. Répétez les paramètres site, preset, start, end et search d’origine. La taille de page peut changer. Omettez snapshot pour commencer un nouveau parcours.

Exemple cURL

curl -H "Authorization: Bearer nm_YOUR_KEY" \
  "https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=25"

Exemple de réponse

{
  "site": "TRACKER_ID",
  "preset": "last30",
  "timezone": "Europe/Zurich",
  "range": {
    "from": "2026-05-28",
    "to": "2026-06-26",
    "label": "Last 30 Days",
    "days": 30
  },
  "limits": {
    "min_date": "2025-03-17",
    "max_date": "2026-06-26",
    "max_days": null
  },
  "search": {
    "query": ""
  },
  "daily": [
    {
      "date": "2026-06-25",
      "pageviews": 102400,
      "visits": 12800
    },
    {
      "date": "2026-06-26",
      "pageviews": 98450,
      "visits": 12130
    }
  ],
  "summary": {
    "total_pageviews": 3158127,
    "total_visits": 388450,
    "pages_per_visitor": 8.1
  },
  "top_pages": [
    {
      "rank": 1,
      "title": "Home page",
      "author": "",
      "pubdate": "",
      "url": "/",
      "url_full": "https://example-media.test/",
      "url_id": "5dc0a5883395e2a126e5239650d9268e",
      "thumbnail": "https://realtimemetadata.fra1.cdn.digitaloceanspaces.com/thumbnails/example.jpg",
      "pageviews": 159280
    },
    {
      "rank": 2,
      "title": "Culture desk live notes",
      "author": "Alex Morgan",
      "pubdate": "2026-06-24",
      "url": "/culture/live-notes",
      "url_full": "https://example-media.test/culture/live-notes",
      "url_id": "b35c1a5f2fd0cbb7f3c13b853c2a9d2c",
      "thumbnail": "https://realtimemetadata.fra1.cdn.digitaloceanspaces.com/thumbnails/example-2.jpg",
      "pageviews": 85632
    }
  ],
  "generated_at": "2026-06-26T12:30:00Z"
}

Pagination

Ajoutez offset=0 pour activer la pagination. Chaque réponse contient au maximum 100 articles ; le snapshot en contient au maximum 2000. Sans offset ni snapshot, le format de réponse et la limite existants restent inchangés.

Pour chaque page suivante, envoyez pagination.next_offset comme offset et pagination.snapshot_id comme snapshot. Répétez les paramètres site, preset, start, end et search d’origine, y compris les dates personnalisées. Arrêtez-vous lorsque next_offset vaut null. Un offset supérieur ou égal au nombre disponible renvoie un tableau top_pages vide.

L’ordre des articles, les pages vues, les valeurs quotidiennes, le récapitulatif et generated_at restent fixes d’une page à l’autre, y compris pour les périodes comprenant aujourd’hui. Les indicateurs récapitulatifs couvrent toute la période sélectionnée ; pagination.total ne compte que les articles du snapshot plafonné. Chaque requête nécessite toujours une autorisation valide et est comptabilisée dans la limite de requêtes du tracker.

Les snapshots expirent après 10 minutes. La lecture des pages ne prolonge pas ce délai. En cas de réponse HTTP 410, abandonnez le parcours partiel et recommencez avec offset=0, sans snapshot. Les exemples ci-dessous présentent la première requête, une continuation et l’objet de pagination supplémentaire.

GET https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=100&offset=0
GET https://api.nowmetrix.com/v1/recap?site=TRACKER_ID&preset=last30&limit=100&offset=100&snapshot=0123456789abcdef0123456789abcdef0123456789abcdef
{
  "pagination": {
    "limit": 100,
    "offset": 0,
    "total": 2000,
    "max_results": 2000,
    "has_more": true,
    "next_offset": 100,
    "snapshot_id": "0123456789abcdef0123456789abcdef0123456789abcdef",
    "expires_at": "2026-06-26T12:40:00Z"
  }
}

Champs de réponse

Champ Type Description
site string Identifiant du tracker utilisé pour la requête.
preset string Période prédéfinie résolue utilisée pour la réponse.
timezone string Fuseau horaire du tracker utilisé pour déterminer les dates locales.
range object Période déterminée avec les champs from, to et label, ainsi que le nombre de jours.
limits object Limites de l’historique disponible pour le tracker.
search.query string Requête de recherche normalisée utilisée pour filtrer les pages principales.
daily[] array<object> Pages vues et visites quotidiennes pour la période résolue.
summary.total_pageviews integer Nombre total de pages vues sur la période résolue.
summary.total_visits integer Nombre total de visites sur la période résolue.
summary.pages_per_visitor number Nombre de pages vues divisé par le nombre de visites, arrondi à une décimale.
top_pages[] array<object> Pages principales classées selon le nombre de pages vues.
top_pages[].rank integer Rang dans le snapshot complet lors de la pagination ; les rangs se poursuivent d’une page à l’autre.
top_pages[].title string Titre de la page.
top_pages[].author string Auteur, s’il est disponible.
top_pages[].pubdate string Date de publication, si elle est disponible.
top_pages[].url string Chemin ou URL abrégée.
top_pages[].url_full string URL absolue, si elle est disponible.
top_pages[].url_id string Identifiant stable de l’URL.
top_pages[].thumbnail string URL de la miniature, si elle est disponible.
top_pages[].pageviews integer Nombre de pages vues pour la période résolue.
generated_at string Horodatage UTC de génération de la charge utile.
pagination object Présent uniquement en mode pagination. Au maximum 2000 articles sont disponibles sur l’ensemble des pages.
pagination.limit integer Taille de page effective, comprise entre 1 et 100.
pagination.offset integer Position de base zéro de la page demandée.
pagination.total integer Nombre d’articles dans ce snapshot, plafonné à 2000. Il ne s’agit pas du nombre non plafonné d’URL correspondantes.
pagination.max_results integer Nombre maximal d’articles par snapshot : 2000.
pagination.has_more boolean Indique si une autre page est disponible dans ce snapshot.
pagination.next_offset integer|null Transmettez cette valeur comme offset pour la page suivante. La valeur null indique que la fin a été atteinte.
pagination.snapshot_id string Identifiant opaque pour les requêtes suivantes utilisant le paramètre snapshot. Lié à l’utilisateur authentifié et au tracker.
pagination.expires_at string Date d’expiration fixe en UTC, 10 minutes après le stockage. La lecture des pages ne la prolonge pas.

Actualisation et mise en cache

Les requêtes sans pagination utilisent le microcache existant de 60 secondes et le mécanisme de repli historique. La pagination stocke un snapshot immuable dans le Stats Redis local pendant 600 secondes, avec expiration automatique et sans renouvellement glissant. Des démarrages identiques effectués par le même utilisateur dans un délai de 60 secondes peuvent réutiliser un snapshot ; utilisez donc expires_at comme échéance. Les continuations ne reconstruisent jamais les données et n’utilisent pas un autre snapshot comme solution de repli.

Erreurs

HTTP Code Description
400 site_required Le paramètre site obligatoire 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 n’a pas accès à ce tracker.
429 rate_limit_exceeded La limite de requêtes a été dépassée.
503 redis_unavailable Le backend temps réel est temporairement indisponible.
503 clickhouse_unavailable Les données historiques sont temporairement indisponibles.
500 encoding_failed La réponse Recap n’a pas pu être encodée.
400 invalid_pagination Les paramètres de requête de pagination doivent être des valeurs scalaires.
400 invalid_offset offset doit être un entier compris entre 0 et 2000.
400 invalid_snapshot Le format de l’identifiant du snapshot est invalide.
400 snapshot_required Les offsets supérieurs à zéro nécessitent un identifiant de snapshot. Commencez avec offset=0.
400 snapshot_mismatch La période prédéfinie, les dates ou la recherche diffèrent de la requête d’origine.
410 snapshot_expired Le snapshot a expiré ou n’est plus disponible dans ce contexte utilisateur/tracker. Recommencez avec offset=0 et sans snapshot.
503 snapshot_storage_unavailable Le stockage du snapshot ne peut pas être lu ou écrit. Réessayez ; un identifiant de snapshot existant doit rester inchangé.
503 recap_unavailable Un nouveau snapshot complet ne peut pas être créé pour le moment. Réessayez dans quelques instants. 
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}