REST API

Porti i dati di NowMetrix negli strumenti che il team usa già.

Parta da uno snapshot live, crei una schermata per la redazione oppure invii i risultati storici nel flusso di lavoro per la reportistica. Scelga qui un endpoint, quindi apra il relativo riferimento tecnico completo.

Connettere l’applicazione

È la prima volta che usa l’API? Cominci dalla guida completa alla connessione. La guida spiega come creare e proteggere una chiave API, verificarla con /api/me ed effettuare la stessa richiesta autenticata dai più comuni linguaggi di programmazione.

Apri la guida alla connessione

Cominciare da un unico URL di base

Ogni richiesta autenticata con una chiave API inizia da questo host:

https://api.nowmetrix.com

Inviare la chiave API

Invii la chiave API come token Bearer nell’header Authorization. Gli amministratori dell’account e i membri del team con accesso all’API possono creare e assegnare un nome a un massimo di 10 chiavi attive nella dashboard NowMetrix, in Impostazioni -> API.

Authorization: Bearer nm_YOUR_KEY

È obbligatorio usare HTTPS. Tutte le chiavi utilizzano i permessi dell’utente NowMetrix associato e condividono il limite di frequenza del relativo tracker.

Effettuare la prima richiesta

Il modo più rapido per verificare la configurazione consiste nel richiedere uno snapshot in tempo reale. In questo modo può verificare che la chiave funzioni e che consenta di accedere al tracker.

curl -H "Authorization: Bearer nm_YOUR_KEY" \
  "https://api.nowmetrix.com/v1/realtime?site=TRACKER_ID"

Scegliere i dati necessari

Metodo Percorso Descrizione Riferimento
GET /v1/realtime Snapshot live attuale: lettori live, Pageview, Pagine principali, dispositivi, Paesi, città e Fonti. Visualizza endpoint
GET /v1/sources Fonti di traffico della finestra live attuale, con classificazione e righe secondarie opzionali. Visualizza endpoint
GET /v1/overview Pageview e visite giornalieri delle ultime N righe storiche completate. Visualizza endpoint
GET /v1/recap Dati di Recap, metriche riepilogative e Pagine principali per intervalli predefiniti o un intervallo di date personalizzato. Visualizza endpoint
GET /v1/pulse Pulse di oggi, confronto con ieri e curve intragiornaliere a intervalli di 15 minuti. Visualizza endpoint
GET /v1/proofreading Fino a 100 suggerimenti di Revisione del testo attualmente visibili, ricavati dagli articoli di un tracker verificati più di recente. Visualizza endpoint
GET /v1/responsibilities Responsabilità attuali del team per un tracker, inclusa la persona assegnata a ogni ruolo visibile. Visualizza endpoint
GET /api/me Contesto dell’account associato alla chiave API: tracker corrente e tutti i tracker a cui il token può accedere. Visualizza endpoint

Mantenere le richieste rapide e prevedibili

L’API pubblica consente 20 richieste al minuto per tracker. Più utenti o chiavi che interrogano lo stesso tracker condividono lo stesso contatore.

X-RateLimit-Limit: 20
X-RateLimit-Remaining: 7
X-RateLimit-Reset: 1783612801
Retry-After: 42
Quando possibile, memorizzi nella cache del sistema le risposte dell’API. Come regola generale, conservi brevemente nella cache i dati in tempo reale e per diversi minuti i dati storici della panoramica.

Quando una richiesta non va a buon fine

Non dovrebbe essere necessario analizzare un formato diverso per ogni problema. Gli errori dell’API utilizzano un corpo JSON coerente, con un codice stabile e leggibile dalle applicazioni.

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 Il limite di frequenza è stato superato.
503 redis_unavailable Il backend in tempo reale non è temporaneamente disponibile. 
{
  "error": {
    "code": "invalid_token",
    "message": "Bearer token is invalid or revoked."
  }
}