API di misurazione in sola lettura

Porta i tuoi dati di visibilità AI nelle tue dashboard, nei fogli di calcolo o nei report di agenzia. JSON o CSV, una chiave per integrazione, solo i dati del tuo spazio di lavoro.

Autenticazione

Crea una chiave in Account, Chiavi API (solo proprietari dello spazio di lavoro). Inviala come token Bearer. La chiave completa viene mostrata una sola volta; conserviamo solo un hash. Le chiavi revocate smettono di funzionare alla richiesta successiva.

curl -H "Authorization: Bearer aeo_YOUR_KEY" \
  "https://YOUR-AEODA-DOMAIN/api/v1/brands/BRAND_ID/scores?from=2026-09-01&limit=50"

# CSV
curl -H "Authorization: Bearer aeo_YOUR_KEY" -o scores.csv \
  "https://YOUR-AEODA-DOMAIN/api/v1/brands/BRAND_ID/scores?format=csv&delimiter=semicolon"

Piani

L’API è inclusa in Pro e Agency; l’esportazione CSV da Starter. Con un downgrade, le chiavi esistenti rispondono 403 finché lo spazio di lavoro non fa di nuovo l’upgrade.

Con un downgrade le chiavi vengono sospese e rispondono 403; tornano a funzionare non appena lo spazio di lavoro fa l’upgrade. Le chiavi non vengono eliminate.

Endpoint

Tutti gli endpoint sono GET e in sola lettura. URL di base: il tuo dominio aeoda.

Endpoint	Restituisce
GET /api/v1/brands	I tuoi marchi (id, nome, dominio, mercato).
GET /api/v1/brands/{brandId}/scores	Storico dei punteggi: data, motore, punteggio, intervallo di confidenza, tasso di menzione.
GET /api/v1/brands/{brandId}/answers	Risposte: prompt, motore, citato o no, posizione, sentiment, concorrenti, testo.
GET /api/v1/brands/{brandId}/sources	Fonti citate: dominio, URL, numero di risposte, propria o concorrente.
GET /api/v1/brands/{brandId}/competitors	Confronto con i concorrenti: marchio, punteggio, share of voice.
GET /api/v1/brands/{brandId}/recommendations	Piano d’azione: titolo, priorità, impegno, stato.

Parametri di query

from e to: date come YYYY-MM-DD (predefinito ultimi 30 giorni, limitati dallo storico del tuo piano). limit: da 1 a 1000 (predefinito 100). cursor: il valore nextCursor della pagina precedente. format: json (predefinito) o csv. delimiter: comma o semicolon (CSV). lang: lingua dei titoli delle raccomandazioni. I parametri sconosciuti restituiscono 400.

Esempio

{
  "data": [
    {
      "brand": "Northwind Coffee",
      "date": "2026-10-01T09:00:00.000Z",
      "engine": "all",
      "score": 55,
      "ci_low": 40,
      "ci_high": 70,
      "mention_rate": 25,
      "sov": 31.5,
      "avg_position": 2.4
    }
  ],
  "nextCursor": "eyJ0IjoiMjAyNi0xMC0wMSAwOTowMDowMCswMCIsImlkIjoiLi4uIn0",
  "range": { "from": "2026-09-01", "to": "2026-10-18" }
}

Formato CSV

Il CSV è UTF-8 con indicatore dell’ordine dei byte, così Excel apre correttamente gli accenti. Le celle di testo che iniziano con = + - @ ricevono un apostrofo per evitare l’iniezione di formule. Le risposte CSV sono in streaming e limitate a 100.000 righe: se raggiungi il limite (413), riduci l’intervallo di date.

Limiti di frequenza e paginazione

Ogni chiave consente 60 richieste al minuto. Le risposte includono x-ratelimit-limit e x-ratelimit-remaining; un 429 include retry-after. Le liste JSON sono paginate con nextCursor (null nell’ultima pagina).

format=csv ha un limite proprio, più basso: 6 download all’ora per chiave, e una risposta è limitata a 50 MB (un’ultima riga "# truncated" segnala un file troncato).

Errori

401Chiave mancante, malformata o revocata.
403Il piano dello spazio di lavoro non include l’API.
404Il marchio non esiste nel tuo spazio di lavoro.
413Limite di righe CSV superato: usa un intervallo di date più breve.
429Limite di frequenza raggiunto: attendi i secondi indicati da retry-after.