Cosa legge l'API

L'API legge gli stessi dati delle schermate di Gloriads. Non cambia mai il tuo account né i tuoi annunci.

Endpoint

Ogni parametro e ogni campo sono nel riferimento dell'API, con un pulsante Try it.

Periodi

/summary, /timeline e /reports/products coprono un periodo. Invia uno di:

• Se non invii nulla: last_30_days, come la dashboard.
• Un range copre giorni completi, quelli che somma la dashboard: last_30_days sono i 30 giorni che finiscono ieri, e this_month e this_year si fermano a ieri. Amazon attribuisce una vendita al suo clic giorni dopo, quindi oggi non è mai completo.
• today è oggi, e lo è anche this_month il 1° del mese (non ha ancora un giorno completo).
• all_time parte dal giorno più vecchio che Gloriads conserva e arriva fino a oggi, come Tutto lo storico nella dashboard.
• Per includere oggi, invia start_date e end_date con end_date = oggi.
• timezone (Europe/Paris, America/New_York…) decide quale giorno sia «oggi». UTC per impostazione predefinita.
• Ogni risposta ripete in period i giorni che copre.

Confronta due periodi

Aggiungi compare a /summary, /timeline o /reports/products, come Confronta con nella dashboard:

La risposta aggiunge un comparison con i dati del periodo confrontato e, per spesa, vendite, ACOS, impressioni, clic, CPC e acquisti, come è cambiato ciascuno:

"changes": {
  "spend": { "kind": "change", "percent": 18.2, "direction": "up", "tone": "neutral" },
  "acos": { "kind": "change", "percent": -6.5, "direction": "down", "tone": "good" }
}

• Entrambi i periodi finiscono ieri, come nella dashboard: le date che arrivano a oggi perdono oggi, e period lo dice.
• kind: "new" significa che il dato era zero prima; kind: "none" significa che non c'è nulla da confrontare (ACOS senza vendite).
• tone dice se è una buona notizia, come i colori della dashboard. La spesa è sempre neutral.
• all_time non ha nulla prima, e today non ha un giorno completo: comparison ne spiega allora il motivo in unavailable.
• Quando Gloriads non conserva storico per il periodo confrontato, i suoi dati sono null e history_covered è false.

Filtri

Un valore sconosciuto viene rifiutato con un 400 che lo nomina, mai con una risposta di zeri.

Totali di un periodo

curl "https://gloriads.com/api/v1/summary?range=last_month&marketplaces=US" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "period": { "start_date": "2026-09-01", "end_date": "2026-09-30", "range": "last_month", "timezone": "UTC" },
  "currency": "USD",
  "spend": 13140.53,
  "sales": 46562.2,
  "acos": 28.22,
  "roas": 3.54,
  "impressions": 3945723,
  "clicks": 13973,
  "ctr": 0.35,
  "average_cpc": 0.94,
  "purchases": 1479,
  "conversion_rate": 10.58,
  "by_marketplace": [ … ],
  "by_ad_product": [ … ],
  "meta": { "data_last_date": "2026-10-09", "history_covered": true, "truncated": false }
}

• acos, ctr e conversion_rate sono percentuali: 28.22 significa 28,22%.
• purchases conta gli ordini, come Acquisti della console, non le unità.
• Un rapporto senza la sua base (ACOS senza vendite) è null, mai 0.

Giorno per giorno o mese per mese

/timeline accetta lo stesso periodo e gli stessi filtri e restituisce in data un punto per giorno o per mese.

• granularity=auto (il valore predefinito) sceglie i giorni fino a 92 giorni, i mesi oltre, come il grafico della dashboard.
• granularity=day viene rifiutato su un periodo più lungo di 92 giorni.
• Un giorno senza alcun dato viene omesso.

Per prodotto

/reports/products restituisce una riga per prodotto pubblicizzato (ASIN), ordinata per sort (spend per impostazione predefinita) e order (desc per impostazione predefinita).

• product_id: null raccoglie ciò che Amazon non lega a nessun prodotto, per lo più Sponsored Brands.
• title è il nome del prodotto come lo dà il report prodotti di Amazon, sul marketplace in cui ha speso di più nel periodo. È null per product_id: null, e finché Gloriads non ha ricevuto da Amazon i titoli dei prodotti dell'account.
• Le righe arrivano in pagine: vedi Limiti ed errori.

TV in streaming

Gli altri report lasciano fuori la TV in streaming (gli annunci TV su Prime Video e sulle app di streaming), come la dashboard: Amazon non la include nel report da cui derivano. /reports/streaming-tv la legge da un report Amazon separato, per un solo marketplace.

curl "https://gloriads.com/api/v1/reports/streaming-tv?marketplace_id=3478512345678901&range=last_30_days" \
  -H "Authorization: Bearer YOUR_API_KEY"

• Un periodo di 31 giorni al massimo, entro gli ultimi 95 giorni: sono i limiti di Amazon per questo report.
• La prima chiamata per un periodo può rispondere "status": "pending" mentre Amazon prepara il report, di solito qualche minuto. Richiama dopo meta.retry_after_seconds. Il report viene poi conservato 3 ore.
• Ogni campagna arriva con spesa, impressioni, cpm (costo per 1000 impressioni), clic, vendite, acquisti e units_sold.
• Gli importi sono nella valuta del marketplace, non in USD.
• "status": "unavailable": Amazon non offre la TV in streaming a questo account, per esempio quello di un autore KDP.

Campagne e gruppi di annunci

Entrambi richiedono marketplace_id: un id da /marketplaces.

curl "https://gloriads.com/api/v1/campaigns?marketplace_id=3478512345678901&states=ENABLED" \
  -H "Authorization: Bearer YOUR_API_KEY"

• Elencano le campagne attive e in pausa di Sponsored Products, Sponsored Brands e Display. Quelle archiviate non vengono mai elencate.
• Budget e offerte sono nella valuta del marketplace (currency_code in /marketplaces).
• provenance dice se Gloriads ha creato la campagna, l'ha modificata o non l'ha mai toccata.
• /ad-groups?campaign_id=… tiene i gruppi di annunci di una sola campagna.
• Fino a 1000 righe per pagina (100 per impostazione predefinita).

Parole chiave, target e annunci

/targets e /ads elencano ciò che c'è dentro una campagna. Entrambi richiedono marketplace_id e campaign_id; ad_group_id tiene uno dei suoi gruppi di annunci.

curl "https://gloriads.com/api/v1/targets?marketplace_id=3478512345678901&campaign_id=28430987654321" \
  -H "Authorization: Bearer YOUR_API_KEY"

• /targets elenca ogni parola chiave con il suo match_type (EXACT, PHRASE, BROAD), i target di prodotto (ASIN), le categorie, i gruppi di targeting automatico e i negativi, con la loro bid e il loro stato. bid: null significa che usa l'offerta predefinita del gruppo di annunci.
• /ads elenca ogni annuncio con i prodotti che pubblicizza (product_ids).
• Vengono letti da Amazon nel momento in cui chiedi e non portano dati di prestazione.
• Sponsored Products, Sponsored Brands e Display. Quelli archiviati non vengono mai elencati.
• Fino a 1000 righe per pagina (100 per impostazione predefinita).

Regole e attività

• /rules elenca ogni regola, dalla modificata più di recente.
• /rules/{rule_id}/runs mostra cosa ha guardato e cambiato ogni esecuzione recente. I test non sono elencati.
• /activity elenca ogni operazione che Gloriads ha eseguito su Amazon: una campagna creata o copiata, prodotti aggiunti, le modifiche di una regola, un annullamento. L'esecuzione di una regola compare una volta per marketplace, con lo stesso rule_run_id. Una modifica di più di 5000 righe (una copia grande, una modifica in blocco, una modifica di dayparting…) compare come le sue parti da al massimo 5000 righe: ogni parte successiva nomina la prima in part_of, e Attività le mostra come una sola riga. tool=rule tiene solo quelle delle regole.
• /activity/{operation_id} legge una singola operazione: interrogala a intervalli per seguirne una ancora in corso.
• /activity/{operation_id}/lines elenca ciò che l'operazione ha fatto, riga per riga: la campagna, il gruppo di annunci, l'annuncio o il target, se è stato creato, cambiato o archiviato, ogni valore prima e dopo, e l'errore di Amazon quando una riga è fallita. Fino a 500 righe per pagina (100 per impostazione predefinita): un'operazione può contenerne 5000.

Quanto sono aggiornati i dati

• Sono i dati della tua dashboard, letti dagli stessi dati con lo stesso codice.
• Gli importi delle prestazioni sono in USD. Amazon converte i dati di ogni marketplace.
• Amazon attribuisce le vendite diversi giorni dopo il clic, quindi gli ultimi giorni di un periodo crescono ancora per un po'. meta.data_last_date dice fino a che giorno arrivano i dati.
• Le campagne vengono lette da Amazon al massimo ogni 30 minuti per marketplace. meta.synced_at dice quando. Alla primissima chiamata per un marketplace l'elenco può essere vuoto con meta.syncing: true: richiama dopo un minuto.
• I dati dei prodotti si aggiornano una volta al giorno. Un periodo che parte prima dello storico che Gloriads conserva restituisce meta.history_covered: false.
• Parole chiave, target e annunci vengono letti in diretta da Amazon, a ogni chiamata: meta.read_at dice quando.
• I dati della TV in streaming vengono conservati 3 ore dopo che Amazon ha preparato il loro report: meta.report_ready_at dice quando.