GET /v1/recap | Documentazione REST API di NowMetrix

Richiesta

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

Usare Recap quando l’integrazione deve analizzare dati storici: report, esportazioni delle Pagine principali, intervalli di date personalizzati o risultati filtrati in base alla ricerca.

Autenticazione

È richiesta una chiave API nell’header Authorization: Authorization: Bearer nm_YOUR_KEY.

Parametri della query

Nome	Tipo	Obbligatorio	Descrizione
`site`	`string`	obbligatorio	ID del tracker. La chiave API deve avere accesso a questo tracker.
`preset`	`string`	facoltativo	Preset per l’intervallo di date. Uno tra `today`, `yesterday`, `last7`, `last14`, `last30`, `last90`, `this_month`, `last_month`, `all_time`, `custom`. Valore predefinito: `last30`.
`start`	`date`	facoltativo	Data di inizio per `preset=custom`. Formato: `YYYY-MM-DD`.
`end`	`date`	facoltativo	Data di fine per `preset=custom`. Formato: `YYYY-MM-DD`.
`limit`	`integer`	facoltativo	Numero massimo di pagine principali per risposta, anche con paginazione. I valori sono limitati a 1–100. Predefinito: 100.
`q`	`string`	facoltativo	Termine di ricerca per le Pagine principali. Corrisponde all’URL, al titolo o all’autore. Alias: `search`.
`search`	`string`	facoltativo	Alias di `q`.
`offset`	`integer`	facoltativo	Avvii la paginazione con `offset=0`. Numero intero da 0 a 2000. Le pagine successive richiedono `snapshot`. Senza offset o snapshot, la risposta esistente rimane invariata.
`snapshot`	`string`	facoltativo	Utilizzi `pagination.snapshot_id` dalla prima risposta. Ripeta i parametri originali site, preset, start, end e il filtro di ricerca. La dimensione della pagina può cambiare. Ometta snapshot per iniziare una nuova sequenza.

Esempio cURL

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

Esempio di risposta

{
  "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

Aggiunga offset=0 per attivare la paginazione. Ogni risposta contiene al massimo 100 articoli; la snapshot ne contiene al massimo 2000. Senza offset o snapshot, il formato e il limite esistenti restano invariati.

Per ogni pagina successiva, invii pagination.next_offset come offset e pagination.snapshot_id come snapshot. Ripeta i parametri originali site, preset, start, end e il filtro di ricerca, comprese le date personalizzate. Si fermi quando next_offset è null. Un offset pari o superiore al numero disponibile restituisce un array top_pages vuoto.

L’ordine degli articoli, le Pageviews, i valori giornalieri, il riepilogo e generated_at restano invariati tra le pagine, anche per periodi che includono oggi. Il riepilogo copre l’intero periodo selezionato; pagination.total conta solo gli articoli nella snapshot limitata. Ogni richiesta richiede comunque un’autorizzazione valida e rientra nel limite di richieste del tracker.

Le snapshot scadono dopo 10 minuti; le letture non ne prolungano la validità. In caso di HTTP 410, scarti la sequenza incompleta e ricominci con offset=0 senza snapshot. Gli esempi mostrano la prima richiesta, una richiesta successiva e l’oggetto pagination aggiuntivo.

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"
  }
}

Campi della risposta

Campo	Tipo	Descrizione
`site`	`string`	ID del tracker utilizzato per la richiesta.
`preset`	`string`	Preset effettivamente utilizzato per la risposta.
`timezone`	`string`	Fuso orario del tracker utilizzato per determinare le date locali.
`range`	`object`	Intervallo di date determinato, con data iniziale, data finale, etichetta e numero di giorni.
`limits`	`object`	Limiti dello storico disponibile per il tracker.
`search.query`	`string`	Query di ricerca normalizzata utilizzata per filtrare le Pagine principali.
`daily[]`	`array<object>`	Pageview e visite giornalieri per l’intervallo determinato.
`summary.total_pageviews`	`integer`	Totale dei Pageview nell’intervallo determinato.
`summary.total_visits`	`integer`	Totale delle visite nell’intervallo determinato.
`summary.pages_per_visitor`	`number`	Pageview diviso per il numero di visite, arrotondato a una cifra decimale.
`top_pages[]`	`array<object>`	Pagine principali ordinate per Pageview.
`top_pages[].rank`	`integer`	Con la paginazione, posizione nella snapshot completa; la numerazione prosegue tra le pagine.
`top_pages[].title`	`string`	Titolo della pagina.
`top_pages[].author`	`string`	Autore, se disponibile.
`top_pages[].pubdate`	`string`	Data di pubblicazione, se disponibile.
`top_pages[].url`	`string`	Percorso o URL abbreviato.
`top_pages[].url_full`	`string`	URL assoluto, se disponibile.
`top_pages[].url_id`	`string`	Identificatore stabile dell’URL.
`top_pages[].thumbnail`	`string`	URL della miniatura, se disponibile.
`top_pages[].pageviews`	`integer`	Pageview nell’intervallo determinato.
`generated_at`	`string`	Timestamp UTC di generazione del payload.
`pagination`	`object`	Presente solo in modalità paginazione. Sono disponibili al massimo 2000 articoli complessivi.
`pagination.limit`	`integer`	Dimensione effettiva della pagina, da 1 a 100.
`pagination.offset`	`integer`	Posizione della pagina richiesta, con indice iniziale 0.
`pagination.total`	`integer`	Numero di articoli nella snapshot, limitato a 2000. Non indica il numero totale illimitato di URL corrispondenti.
`pagination.max_results`	`integer`	Numero massimo di articoli per snapshot: 2000.
`pagination.has_more`	`boolean`	Indica se è disponibile un’altra pagina nella snapshot.
`pagination.next_offset`	`integer\|null`	Utilizzi questo valore come offset per la pagina successiva. Null indica che è stata raggiunta la fine.
`pagination.snapshot_id`	`string`	ID opaco per le richieste successive tramite il parametro snapshot. Associato all’utente autenticato e al tracker.
`pagination.expires_at`	`string`	Scadenza fissa in UTC, 10 minuti dopo la memorizzazione. La lettura delle pagine non la prolunga.

Aggiornamento e caching

Le richieste senza paginazione usano la microcache esistente di 60 secondi e il fallback storico. La paginazione conserva una snapshot immutabile per 600 secondi nello Stats Redis locale, con scadenza automatica senza rinnovo alla lettura. Avvii identici dello stesso utente entro 60 secondi possono riutilizzare una snapshot; faccia quindi riferimento a expires_at. Le pagine successive non ricostruiscono mai i dati e non usano un’altra snapshot come fallback.

Errori

HTTP	Codice	Descrizione
400	`site_required`	Manca il parametro obbligatorio site.
401	`missing_token`	Manca l’header Authorization.
401	`invalid_token`	Il token non è valido o è stato revocato.
403	`site_not_authorized`	La chiave API non ha accesso a questo tracker.
429	`rate_limit_exceeded`	È stato superato il limite di richieste.
503	`redis_unavailable`	Il backend realtime non è temporaneamente disponibile.
503	`clickhouse_unavailable`	I dati storici non sono temporaneamente disponibili.
500	`encoding_failed`	Non è stato possibile codificare la risposta di Recap.
400	`invalid_pagination`	I parametri di paginazione devono essere valori scalari.
400	`invalid_offset`	Offset deve essere un numero intero da 0 a 2000.
400	`invalid_snapshot`	Il formato dell’ID della snapshot non è valido.
400	`snapshot_required`	Un offset maggiore di zero richiede un ID della snapshot. Inizi con offset=0.
400	`snapshot_mismatch`	La preimpostazione, le date o il filtro di ricerca differiscono dalla richiesta originale.
410	`snapshot_expired`	La snapshot è scaduta o non è più disponibile per questo utente/tracker. Ricominci con offset=0 e senza snapshot.
503	`snapshot_storage_unavailable`	Non è possibile leggere o scrivere la snapshot. Riprovi mantenendo invariato un eventuale ID già ricevuto.
503	`recap_unavailable`	Al momento non è possibile creare una nuova snapshot completa. Riprovi tra poco.

{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}