Endpoint REST API

GET /v1/sources-history

Andamento del mix di traffico nel tempo: media dei lettori simultanei per categoria di fonte nell’ultima ora, nelle ultime 24 ore, oggi, ieri, negli ultimi 7 giorni o in un intervallo di date personalizzato.

Richiesta

Dati storici disponibili dal 16 novembre 2026

La cronologia delle fonti viene registrata dal 16 novembre 2026 e si arricchisce ogni giorno. La registrazione è iniziata intorno alle 16:00 UTC, quindi il 16 novembre include solo le ore serali e il relativo valore giornaliero non è confrontabile con quello di giornate intere. Se un intervallo richiesto risale a prima del 16 novembre 2026, il parametro from viene impostato su quella data e la risposta include una notifica; un intervallo che termina prima di quella data non restituisce punti. I periodi precedenti non vengono mai indicati come zero.

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

Usi questo endpoint per osservare l’evoluzione del mix di traffico, ad esempio per capire quando è iniziato il traffico da Google Discover o se la ricerca organica è più debole rispetto a ieri. Ogni punto indica il numero medio di lettori simultanei per categoria di fonte in quel momento. I valori non rappresentano visite o Pageview e non vanno sommati nel tempo; per i totali, usi /v1/recap o /v1/overview. Per le singole fonti live, ad esempio uno specifico social network o una newsletter, usi /v1/sources.

Provare nel playground API

Autenticazione

È necessaria una chiave API nell’header Authorization, nel formato: 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.
range string facoltativo Intervallo di tempo. Uno tra 1h (ultimi 60 minuti, punti ogni 2 minuti), 24h (ultime 24 ore, punti ogni 10 minuti), today e yesterday (giorno di calendario nel fuso orario del tracker, punti ogni 10 minuti), 7d (oggi e i 6 giorni precedenti, punti orari) oppure custom (richiede start e end). Valore predefinito: today.
start string facoltativo Primo giorno di calendario di un intervallo personalizzato, nel formato YYYY-MM-DD e nel fuso orario del tracker. Obbligatorio con range=custom e non ammesso con gli altri intervalli. Non può essere una data futura.
end string facoltativo Ultimo giorno di calendario di un intervallo personalizzato, nel formato YYYY-MM-DD, estremi inclusi. Obbligatorio con range=custom. L’intervallo può coprire al massimo 366 giorni; una data finale futura viene limitata all’ora corrente. La risoluzione dipende dal numero di giorni con dati registrati: punti ogni 10 minuti per intervalli fino a 2 giorni, orari fino a 31 giorni e giornalieri per intervalli più lunghi.

Esempio cURL

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

Esempio di risposta

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

Campi della risposta

Campo Tipo Descrizione
site string ID del tracker usato per la richiesta.
range string Intervallo di tempo richiesto.
start string|null Primo giorno richiesto per range=custom; altrimenti null.
end string|null Ultimo giorno richiesto per range=custom; altrimenti null.
timezone string Fuso orario del tracker usato per i giorni di calendario e i timestamp, ad esempio Europe/Zurich.
unit string È sempre avg_concurrent_readers: numero medio di lettori attivi contemporaneamente in ciascun punto.
resolution_minutes integer Durata di ciascun punto in minuti: 2, 10, 60 o 1440 (un giorno di calendario).
from string Inizio dell’intervallo come timestamp ISO 8601 con offset del fuso orario del tracker. Se l’intervallo richiesto inizia prima di data_available_from, il valore viene spostato a tale data.
to string Fine dell’intervallo come timestamp ISO 8601 con offset. Per gli intervalli in corso, corrisponde all’ora corrente.
data_available_from string Primo giorno con dati storici delle fonti registrati: 2026-11-16. La registrazione è iniziata intorno alle 16:00 UTC di quel giorno, che è quindi incompleto.
notice object|null Impostato se l’intervallo richiesto risale a prima di data_available_from; altrimenti è null. La richiesta va comunque a buon fine con HTTP 200.
notice.code string partial_history: l’intervallo inizia prima, quindi from è stato spostato e non sono disponibili punti per i giorni precedenti. no_history: l’intervallo termina prima dell’inizio della registrazione dei dati, quindi points è vuoto.
notice.message string Breve spiegazione in inglese, da usare nei log o da visualizzare.
updated_at string Timestamp UTC che indica quando è stata calcolata la cronologia.
stale boolean true se questo è l’ultimo risultato valido restituito perché il backend della cronologia è temporaneamente indisponibile.
categories[] array<string> Tutte le categorie di fonte, sempre nello stesso ordine: organic, discover, direct, internal, social, referral, email, ai. L’elenco è sempre completo, anche se una categoria non ha avuto lettori.
points[] array<object> Punti in ordine cronologico. Gli intervalli temporali senza dati raccolti vengono omessi, quindi possono esserci dei vuoti.
points[].t string Inizio del punto come timestamp ISO 8601 con offset. Quando, al termine dell’ora legale, gli orologi vengono spostati indietro, l’ora ripetuta viene accorpata in un unico punto.
points[].total number Media dei lettori simultanei per tutte le fonti, arrotondata a una cifra decimale.
points[].unattributed number Lettori inclusi in total a cui non è possibile assegnare una categoria. Attualmente il valore è di solito 0, quindi la somma delle categorie corrisponde a total. Calcoli sempre le quote dividendo il valore della categoria per total, così il risultato rimane corretto anche in presenza di lettori non assegnati.
points[].values object Media dei lettori simultanei per categoria, con le chiavi corrispondenti ai nomi elencati in categories. Le categorie senza lettori hanno valore 0.

Aggiornamento e cache

Le risposte vengono memorizzate nella cache per tracker e intervallo: 60 secondi per 1h, 24h e today, 5 minuti per 7d e 30 minuti per yesterday. Gli intervalli personalizzati vengono memorizzati nella cache in base alle date di inizio e fine: per 30 minuti se l’intervallo è terminato; altrimenti, per 60 secondi se i punti sono ogni 10 minuti e per 5 minuti se sono orari o giornalieri. Se il backend della cronologia è temporaneamente indisponibile, viene restituito l’ultimo risultato valido con stale: true e un header Warning. La risposta include anche X-NowMetrix-Microcache con HIT, MISS o STALE.

Errori

HTTP Codice Descrizione
400 site_required Manca il parametro site obbligatorio.
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 in tempo reale è temporaneamente indisponibile.
400 invalid_range Il parametro range deve essere 1h, 24h, today, yesterday, 7d o custom.
400 invalid_date_range start o end non è specificato o non è una data valida nel formato YYYY-MM-DD; start è successivo a end o è nel futuro; l’intervallo supera i 366 giorni; oppure start ed end sono stati inviati senza range=custom.
503 source_history_unavailable La cronologia delle fonti è temporaneamente indisponibile e non è presente alcun risultato recente nella cache. Riprovi dopo l’intervallo indicato nell’header Retry-After.
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}