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
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.
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 APIAutenticazione
È 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."
}
}