Vai al contenuto principale

​
Panoramica

Enterprise Questa è un’API Enterprise disponibile esclusivamente nei nostri livelli di accesso gestiti. Per utilizzare questa API, devi prima configurare un account con il nostro team vendite Enterprise. Scopri di più L’Engagement API fornisce accesso alle metriche di impression e di coinvolgimento dei Post. Sebbene la maggior parte delle metriche e degli endpoint richieda l’autenticazione tramite Contesto utente OAuth 1.0a, puoi accedere alle metriche pubbliche di Preferiti, Retweet, Risposte e Visualizzazioni video utilizzando OAuth 2.0 Bearer Token e l’endpoint /totals.   Nota: Potresti riscontrare differenze tra i dati riportati su alcune dashboard web di X e quelli riportati nell’Engagement API. Queste differenze si verificano perché le dashboard web in genere mostrano solo gli engagement e/o le impression avvenuti nell’intervallo di tempo selezionato. Ad esempio, una dashboard web può mostrare l’engagement sui Post nell’arco di un mese di calendario, mentre l’Engagement API può mostrare engagement che ricadono oltre l’arco di quel mese, ma all’interno dell’intervallo di tempo richiesto. In questi casi, l’Engagement API deve essere considerata la fonte di riferimento.  

​
Endpoint delle richieste

L’Engagement API dispone di tre endpoint:

​
Totali correnti: [/totals]

  • Le richieste restituiscono una metrica totale per le impression e una metrica totale per le interazioni per i Post desiderati
  • Limitato alle seguenti metriche: Impression, Interazioni, Preferiti, Risposte, Retweet, Quote Tweets e Visualizzazioni video
  • Consente di recuperare le metriche Impression e Interazioni per i Post creati negli ultimi 90 giorni utilizzando Contesto utente OAuth 1.0a
  • Consente di recuperare le metriche Preferiti, Retweet, Quote Tweets, Risposte e Visualizzazioni video per qualsiasi Post utilizzando OAuth 2.0 Bearer Token
  • I risultati si basano sul totale corrente di impression e interazioni al momento dell’esecuzione della richiesta
  • Ideale per alimentare una dashboard e per calcolare i tassi di coinvolgimento su una varietà di @handle
  • Supporta la richiesta di metriche per un massimo di 250 Post per richiesta  

​
Ultime 28 ore: [/28hr]

  • Le richieste possono restituire una metrica totale per le impression, una metrica totale per le interazioni e un dettaglio delle singole metriche di engagement avvenute nelle ultime 28 ore
  • I dati possono essere raggruppati per ID del Post e, come serie temporali, in aggregato per giorno o per ora
  • Ideale per monitorare le prestazioni dei contenuti creati di recente
  • Supporta tutte le metriche disponibili
  • Consente di richiedere metriche per un massimo di 25 Post per richiesta  

​
Storico: [/historical]

  • Le richieste possono restituire impression, engagement e un dettaglio delle singole metriche di engagement per l’ultimo anno, in base al momento dell’engagement (non al momento di creazione del Post).
  • Le richieste supportano i parametri di data di inizio e data di fine, offrendo flessibilità per restringere l’intervallo temporale fino a 4 settimane.
  • I dati di engagement del Post sono limitati agli ultimi 365 giorni.
  • I dati possono essere raggruppati per ID del Post e, nelle serie temporali aggregate, per giorno o per ora.
  • Ideale per valutare le prestazioni recenti rispetto a un benchmark storico o per sviluppare una visione storica delle prestazioni di un @handle.
  • Supporta tutte le metriche disponibili.
  • Supporta la richiesta di metriche per un massimo di 25 Post per richiesta.

​
Metriche disponibili

La tabella seguente descrive i tipi di metriche accessibili tramite l’Engagement API. Consulta la nostra pagina Interpretare le metriche per approfondire le metriche riportate di seguito.
MetricaDisponibilità EndpointContesto Utente RichiestoDescrizione
impressionsTuttiSìConteggio delle visualizzazioni del Post. Questa metrica è disponibile solo per i Post pubblicati negli ultimi 90 giorni.
engagementsTuttiSìConteggio delle interazioni degli utenti con il Post. Questa metrica è disponibile solo per i Post pubblicati negli ultimi 90 giorni.
favoritesTuttiSì - /28hrs & /Historical

No - /totals		Conteggio dei “Mi piace” ricevuti dal Post.
retweetsTuttiSì - /28hrs & /Historical

No - /totals		Conteggio dei Retweet del Post.
quote_tweets/totalsNo - /totalsConteggio dei Retweet con commento (noti anche come Quote Tweet) del Post.
repliesTuttiSì - /28hrs & /Historical

No - /totals		Conteggio delle risposte al Post.
video_viewsTuttiSì - /28hrs & /Historical

No - /totals		Conteggio delle visualizzazioni di un video nel Post quando è visibile al 50% per almeno due secondi.

Le visualizzazioni video sono disponibili solo per i Post con meno di 1800 giorni. Se richiedi le visualizzazioni video per Post più vecchi di 1800 giorni, riceverai il seguente oggetto nella risposta, insieme a un oggetto separato contenente le altre metriche richieste:

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

Nota: Potresti notare una discrepanza tra la metrica delle visualizzazioni video mostrata nelle piattaforme di proprietà di X (app mobile e sito web) e il numero ricevuto tramite gli endpoint /28hr e /historical.

_ Le visualizzazioni video mostrate nell’interfaccia utente di X e con l’endpoint /totals rappresentano le visualizzazioni aggregate di tutti i Post in cui il video è stato pubblicato. Ciò significa che la metrica nell’interfaccia utente include le visualizzazioni combinate di ogni istanza in cui il video è stato condiviso tramite Retweet o ripubblicato in Post separati. Questa metrica non include le visualizzazioni di gif.
_ Le visualizzazioni video fornite dagli endpoint /28hr e /historical includono solo le visualizzazioni generate dal Post specifico per cui stai recuperando le metriche. Questa metrica non include le visualizzazioni di gif.
media_views/28hr /historicalSìConteggio di tutte le visualizzazioni (riproduzione automatica e clic) dei media, inclusi video, gif e immagini.
media_engagements

(precedentemente Media Clicks)		/28hr /historicalSìConteggio dei clic sui media (immagini o video) nel Post.
url_clicks/28hr /historicalSìConteggio dei clic sui link nel Post.
hashtag_clicks/28hr /historicalSìConteggio dei clic sugli hashtag nel Post.
detail_expands/28hr /historicalSìConteggio dei clic sul Post per visualizzare maggiori dettagli.
permalink_clicks/28hr /historicalSìConteggio dei clic sul permalink del Post (la pagina web dedicata a questo Post).
app_install_attempts/28hr /historicalSìConteggio degli eventi di installazione App generati dal Post.
app_opens/28hr /historicalSìConteggio degli eventi di apertura App generati dal Post.
email_tweet/28hr /historicalSìConteggio delle condivisioni del Post via email.
user_follows/28hr /historicalSìConteggio dei nuovi follower dell’autore del Post generati da questo Post.
user_profile_clicks/28hr /historicalSìConteggio dei clic sul profilo dell’autore del Post generati da questo Post.

​
Raggruppamenti di engagement

I raggruppamenti consentono di organizzare in modo personalizzato le metriche di engagement restituite. Puoi includere al massimo 3 raggruppamenti per richiesta. Puoi scegliere di raggruppare le metriche in base a uno o più dei seguenti valori: Tutti e tre gli endpoint supportano:
  • tweet.id
  • engagement.type  
Gli endpoint /28hr e /historical possono fornire metriche in serie temporale e quindi supportano:
  • engagement.day
  • engagement.hour
Per ulteriori informazioni sul raggruppamento, visita la pagina Engagement API Grouping nella sezione Guide.

​
Guide

​
Guida introduttiva per sviluppatori

​
Introduzione

Questa documentazione ha lo scopo di offrire agli sviluppatori un’introduzione all’integrazione con la Engagement API. Inizieremo parlando dei “perché” dell’integrazione, quindi passeremo ad approfondire i dettagli tecnici del “come”.
Cosa offre l’Engagement API?
  • L’Engagement API fornisce dati su impression e coinvolgimento per i Post di proprietà di qualsiasi account X negli ultimi 90 giorni, a condizione che tale account abbia autorizzato la tua App a richiedere metriche per suo conto utilizzando il flusso OAuth a 3 passaggi. Questa soluzione potente ma facile da implementare offre accesso immediato alle impression e a interazioni approfondite come clic su URL, clic su #hashtag e molto altro.
  • L’Engagement API fornisce metriche aggregate totali per preferiti, Retweet, Quote Tweets, risposte e visualizzazioni video per qualsiasi Post. Può essere utilizzata come un modo efficace per ottenere dati di coinvolgimento di base su qualsiasi Post o raccolta di Post.
  • L’Engagement API apporta nuovo valore alle piattaforme di social listening, marketing e publishing consentendo ai clienti di misurare il ROI su X valutando efficacemente le prestazioni dei contenuti con oltre 15 metriche di performance.
  • L’Engagement API è un’API request/response che consente agli sviluppatori di App di inviare richieste con ID del Post, metriche desiderate e un intervallo temporale, per cui l’API restituisce immediatamente i data.  
Perché integrare? Esempi di casi d’uso
  • Comprendere la portata complessiva dei contenuti per vedere quante persone li visualizzano. Scoprire quante persone guardano i video, fanno clic sui link, sugli hashtag o installano le mie App.
  • Generare metriche di coinvolgimento sia totali sia in serie temporali.
  • Comprendere le metriche di coinvolgimento di base (preferiti, Retweet, Quote Tweet, risposte) relative a qualsiasi Post pubblico.
  • Usare queste metriche per determinare quali tipi di Post funzionano, così posso pubblicarli più spesso e ottenere più impression e più interazioni per i miei contenuti.
  • Automatizzare le attività di marketing (ad esempio fare Retweet di contenuti da un altro account di mia proprietà) ogni volta che uno dei miei Post raggiunge 100 like o un’altra soglia.
  • Effettuare benchmark e confrontare tra loro le mie campagne come strumento per i test A/B.
  • Analizzare quali contenuti risuonano per il mio reparto di assistenza clienti per stabilire come e quando rispondere.
  • Mostrare le analytics dei contenuti pubblicati dalla mia piattaforma.  
L’Engagement API è stata lanciata nel 2016 ed è stata la prima X API a fornire metriche di coinvolgimento così approfondite su larga scala. L’Engagement API è facile da usare e consente ai clienti di automatizzare il processo. Ecco un caso di studio che descrive un’integrazione di esempio: Ora che abbiamo esplorato i “perché” dell’Engagement API, iniziamo ad approfondire i dettagli tecnici.

​
Integrazione dell’Engagement API

Introduzione all’API
La Engagement API è una semplice API RESTful che riceve richieste in JSON e risponde con metriche di engagement in JSON. Le richieste sono composte da tre parti principali (seguire i link per ulteriore documentazione):
  • Array di ID del Post.
  • Array che specifica i tipi di metriche di interesse. I tipi includono elementi come “impressions”, “retweets”, “hashtag_clicks” e “user_follows”.
  • Raggruppamenti di engagement, ovvero una struttura JSON che indica come si desidera che i dati di engagement siano organizzati nella risposta dell’API.
In molte situazioni, i tipi di Engagement e i raggruppamenti rimarranno relativamente costanti da una richiesta all’altra, con solo gli ID del Post aggiornati. La Engagement API fornisce tre endpoint:
  • Totals - Fornisce i totali complessivi delle interazioni per i Post. Alcune metriche sono disponibili per tutti i Post, mentre altre solo per gli ultimi 90 giorni.
  • 28 hour - Fornisce metriche di engagement in serie temporale delle ultime 28 ore.
  • Historical - Fornisce metriche di engagement in serie temporale fino a quattro settimane consecutive per i Post pubblicati dal 1º settembre 2014.
L’endpoint /totals supporta la richiesta di metriche per un massimo di 250 Post per richiesta. Gli endpoint /28hour e /historical supportano 25 per richiesta. Dopo aver descritto come ottenere l’accesso alla Engagement API, illustreremo come effettuare una richiesta all’API, forniremo una panoramica di OAuth e linkeremo ad altre risorse tecniche.
Ottenere l’accesso all’API
Se stai leggendo questo documento, molto probabilmente hai già ottenuto l’accesso all’Engagement API. In caso contrario, contatta il tuo Enterprise account manager oppure richiedi l’accesso Enterprise qui. Il primo passo è creare una X App utilizzando un account sviluppatore approvato tramite il developer portal. Il tuo account manager avrà bisogno dell’id numerico dell’App associata a questa applicazione per poter abilitare l’accesso. Se devi richiedere un account sviluppatore, puoi farlo qui.
Effettuare una richiesta
La buona notizia è che inviare richieste alla Engagement API è semplice. Nella nostra richiesta, chiederemo il totale di Retweet, Quote Tweet, like e risposte per i due seguenti Post di @XDevelopers:
1/ Oggi condividiamo la nostra visione per il futuro della piattaforma X API
https://t.co/XweGngmxlP
 — Twitter Dev (@TwitterDev) 6 aprile 2017
Non perderti i Post sul tuo Post. Ora su iOS puoi vedere i Retweet con commenti tutti in un unico posto. pic.x.com/oanjZfzC6y — X (@X) 12 maggio 2020
Il primo passo è costruire la richiesta all’API in JSON, composta da questi due ID del Post inseriti in un array, da un array dei tipi di engagement di interesse e da un oggetto JSON denominato “groupings” che indica come vogliamo che le metriche siano organizzate nella risposta. Ecco come si presenta la nostra richiesta: 
{
  "tweet_ids": [
    1260294888811347969, 850006245121695744
  ],
  "engagement_types": [
    "retweets", "quote_tweets", "favorites", "replies"
  ],
  "groupings": {
    "engagement-types-by-id": {
      "group_by": [
        "Tweet.id", "engagement.type"
      ]
    }
  }
}
Per ottenere queste metriche totali, inviamo questa richiesta JSON con metodo POST all’endpoint https://data-api.x.com/insights/engagement/totals. Includeremo le seguenti intestazioni per indicare che la richiesta è in formato JSON e che è compressa con Gzip (i body delle richieste possono diventare molto grandi):
  • Content-Type: application/json
  • Accept-Encoding: gzip  
Quando inviamo richieste, effettuiamo l’autenticazione tramite OAuth, di cui parleremo più dettagliatamente nella prossima sezione. L’API restituisce il seguente payload: 
{
  "grouping name": {
    "1260294888811347969": {
      "favorites": "17111",
      "quote_tweets": "3254",
      "replies": "1828",
      "retweets": "5218"
    },
    "850006245121695744": {
      "favorites": "492",
      "quote_tweets": "66",
      "replies": "42",
      "retweets": "324"
    }
  }
}
Nota che la risposta include le metriche richieste nella struttura descritta dalle definizioni di “groupings”, con le metriche elencate prima per ID del Post e poi, al livello successivo, per tipo di engagement. È stato piuttosto semplice. Se sei alle prime armi con l’autenticazione OAuth, consulta la prossima sezione.

​
Autenticazione con OAuth

OAuth è uno standard di autenticazione molto diffuso nel settore tecnologico. Se stai già usando OAuth (magari con altre X API), è probabile che tu stia utilizzando un pacchetto OAuth specifico per il linguaggio che astrae tutti i dettagli complessi. Se sei alle prime armi con OAuth, visita la nostra pagina OAuth with the X API oppure vai direttamente su https://oauth.net per saperne di più. Ti consigliamo quindi di individuare un pacchetto OAuth per il linguaggio d’integrazione che preferisci e partire da lì. Con questi pacchetti, il percorso di autenticazione in genere prevede la configurazione delle tue chiavi e token, la creazione di un oggetto HTTP e quindi l’invio di richieste con quell’oggetto. Ad esempio, nel mondo Ruby, il seguente pseudocodice rappresenta una procedura per creare un’App abilitata a OAuth utilizzando la gem Ruby ‘oauth’ ed effettuando una richiesta POST: 
require 'oauth'

#Assembla la richiesta JSON (come sopra).
request = make_json_request()

#Costruisci un oggetto consumer dell'app con la chiave consumer e il segreto della mia app.
consumer = OAuth::Consumer.new(keys['consumer_key'], keys['consumer_secret'], {:site => 'https://data-api.x.com'})
#Costruisci un token utente con i token forniti dall'account che concede il permesso. Se si effettua una richiesta solo app (controllando Tweet che non richiedono permesso con l'endpoint /totals), questo passaggio può essere saltato.
token = {:oauth_token => keys['access_token'], :oauth_token_secret => keys['access_token_secret']}

#Crea un oggetto app abilitato oauth.
app = OAuth::AccessToken.from_hash(consumer, token)
#Effettua una richiesta POST.
result = app.post("/insights/engagement/totals", request, {"content-type" => "application/json", "Accept-Encoding" => "gzip"})
L’Engagement API supporta sia l’autenticazione solo applicazione sia quella con contesto utente. Se stai raccogliendo metriche di engagement per Post pubblici non di tua proprietà con l’endpoint /totals, non è richiesta alcuna autorizzazione dell’utente e puoi utilizzare l’autenticazione solo applicazione. In questo caso, utilizzerai soltanto la tua app key e secret per autenticarti. OAuth consente anche a un’App di effettuare richieste API “per conto di un altro utente”, utilizzando token associati all’utente. Se stai generando metriche di engagement per Post di tua proprietà, cioè Post pubblicati da un utente per il quale possiedi token utente, effettuerai richieste con contesto utente, ovvero autenticandoti sia con le chiavi della tua App sia con access token specifici dell’utente. Questi access token utente sono in genere forniti tramite il processo “Sign-in with X” o acquisiti direttamente dall’utente (nota che devi usare twurl se acquisisci i token direttamente dall’utente). Una volta che l’utente fornisce i propri token, questi non scadono e possono essere utilizzati con l’Engagement API per effettuare richieste per suo conto, purché l’utente non reimposti i token o cambi la password; in tal caso dovrà fornirti i nuovi token. Puoi verificare quali metriche richiedono quale autenticazione tramite questa tabella.

​
Selezione di un endpoint dell’Engagement API

L’Engagement API fornisce tre endpoint distinti:
  • Totals - fornisce il totale complessivo di alcune metriche per Post “owned” o “unowned”. Alcune metriche sono disponibili per tutti i Post, mentre altre solo per i Post pubblicati negli ultimi 90 giorni. Supporta 250 Post per richiesta.
  • 28 hour - fornisce metriche di engagement in serie temporale per i Post “owned” delle ultime 28 ore. Supporta 25 Post per richiesta.
  • Historical - fornisce metriche di engagement in serie temporale fino a quattro settimane consecutive per i Post “owned” pubblicati a partire dal 1° settembre 2014. Supporta 25 Post per richiesta.  
Ogni endpoint ha caratteristiche specifiche. Che tu intenda utilizzare tutti e tre o stia cercando di decidere quale si adatti meglio al tuo caso d’uso, è importante comprenderne le differenze. Di seguito introduciamo alcuni concetti chiave, approfondiamo i tre endpoint e presentiamo casi d’uso di esempio che generalmente corrispondono a un endpoint specifico. L’auspicio è che queste informazioni ti aiutino a integrarli più efficacemente tutti e tre o a decidere quale singolo endpoint si adatta meglio al tuo obiettivo.  

​
Concetti chiave

Esistono diversi concetti chiave che aiutano a illustrare le varie funzionalità e i dati forniti dai tre endpoint della Engagement API.  
Impression e metriche di coinvolgimento
Le impression rappresentano il numero di volte in cui un determinato Post è stato visualizzato sulla piattaforma X in un contesto organico. Le impression generate da Post visualizzati in un contesto Promoted o Paid non sono incluse. Prima della Engagement API, le impression dei Post rappresentavano solo una misura delle visualizzazioni potenziali. Erano basate sul conteggio dei follower dell’account dell’autore e di quelli di qualsiasi account che effettuava Retweet del contenuto, senza considerare la situazione comune in cui un determinato utente non vede effettivamente il Post. Le metriche sulle impression generate dalla Engagement API costituiscono una misura effettiva del numero di volte in cui un Post è stato renderizzato a schermo. Se un follower del tuo account non vede il tuo Post, non viene conteggiato come impression. La Engagement API fornisce metriche su 14 tipologie di metriche di coinvolgimento, ognuna delle quali rappresenta un’azione distinta che un utente può intraprendere quando gli viene mostrato un Post. Queste includono effettuare Retweet, mettere like, rispondere, fare clic su entità come #hashtag, link e contenuti multimediali, seguire l’autore e visualizzare il profilo dell’autore. Tutte queste singole azioni confluiscono in un’unica metrica Engagements.
Contenuti X di proprietà e non di proprietà
Engagement distingue chiaramente tra Post di proprietà e non di proprietà. I Post di proprietà sono Post pubblicati dal tuo account o Post per i quali hai ottenuto l’autorizzazione a richiedere i dati di Engagement. Come per altre X API, ottieni l’autorizzazione quando altri utenti/account di X condividono access token che ti consentono di effettuare richieste API per loro conto. Un modo comune per ottenere questi token è tramite il processo “Accedi con X”. L’endpoint /totals fornisce dati di engagement sia per Post di proprietà sia per Post non di proprietà. Per i Post non di proprietà, puoi richiedere le metriche di engagement pubblicamente visibili nell’interfaccia di un Post: Like, Retweet e Risposta. Per queste metriche, ciò che l’Engagement API offre è la possibilità di recuperarne i valori in modo automatizzato e su larga scala. Per i Post di proprietà, l’endpoint /totals fornisce anche le metriche Impression e Engagement (totale). Gli endpoint /28hr e /historical forniscono metriche solo per i Post di proprietà, il che significa che devi includere il contesto utente quando invii la richiesta a questi endpoint.
Dati di engagement totali e in serie temporale
L’endpoint /totals fornisce, come suggerisce il nome, solo i totali complessivi per i tipi di engagement. I relativi valori rappresentano i totali aggiornati a partire dalla pubblicazione del Post. Se un Post è stato appena pubblicato e richiedi ripetutamente le sue metriche, questi totali cambieranno spesso a ogni richiesta. Gli endpoint /28hr e /historical possono fornire sia totali complessivi sia dati in serie temporale. Quando si richiedono dati in serie temporale, le metriche di engagement possono essere aggregate su base giornaliera o oraria.    Consulta la nostra documentazione sui raggruppamenti di engagement per sapere come richiedere dati in serie temporale con gli endpoint /28hr e /historical.

​
Endpoint e casi d’uso di esempio

Date le caratteristiche e le differenze discusse sopra, ciascun endpoint in genere si applica a tipi di casi d’uso diversi. Per aiutarvi a decidere quale endpoint risponde meglio al vostro caso d’uso specifico, di seguito sono riportate alcune affermazioni esemplificative degli utenti e l’endpoint che le soddisfa al meglio.
/totals
  • Ho bisogno di accedere solo ad alcuni tipi di metriche (Impressions, Engagements, Favorites, Retweets, Quote Tweets, Replies e Video Views).
  • Ho bisogno di accedere ai dati di engagement di base per qualsiasi Post, non solo per i Post di cui siamo proprietari.
  • Voglio confrontare le prestazioni con un concorrente.
  • Voglio monitorare le statistiche di engagement di base per un hashtag o una campagna che includa Post che non possiedo.
  • Non ho bisogno di dati suddivisi per giorno o ora; mi serve solo il totale corrente quando effettuo una richiesta.
  • Mi serve una singola metrica da mostrare in un report o in una dashboard e non voglio archiviare alcun dato.
  • Voglio mostrare i dati al momento del caricamento della pagina e mi basta effettuare una richiesta e ottenere una risposta.
  • Ho bisogno di accedere ai dati per centinaia di migliaia o milioni di Post al giorno.  
/28hr
  • Ho bisogno di accedere a tutti i 17 tipi di metriche.
  • Voglio mostrare i data per Post molto recenti pubblicati nelle ultime 28 ore.
  • Ho un job che viene eseguito una volta al giorno per ottenere i data che mi interessano e mi serve solo ottenere i data dell’ultimo giorno.
  • Ho bisogno che le metriche siano suddivise per giorno o per ora.
  • Voglio mostrare, in una dashboard, suddivisioni in serie temporali dell’attività per ora.
  • Ho bisogno di un livello di accesso elevato per centinaia di migliaia di Post al giorno.
  • Ho capacità di archiviazione e posso aggiornare i data una volta al giorno mantenendo un conteggio cumulativo.  
/historical
  • Ho bisogno di accedere a tutti i 17 tipi di metriche.
  • Ho bisogno di ottenere dati storici per i Post creati risalendo fino a settembre 2014.
  • Voglio presentare un’analisi storica dettagliata che metta a confronto le campagne.
  • Ho bisogno che le metriche siano suddivise per giorno o per ora.
  • Non mi serve un livello di accesso elevato all’Engagement API e mi basta ottenere dati per alcune centinaia o migliaia di Post al giorno.

​
Caratteristiche chiave dell’Engagement API

  • API RESTful che fornisce dati JSON e supporta richieste POST con body JSON.
  • Tipi di richieste: Le app client possono effettuare i seguenti tipi di richieste:
    • Interazioni totali — richiesta HTTP POST all’endpoint /totals
    • Interazioni nelle ultime 28 ore — richiesta HTTP POST all’endpoint /28hr
    • Interazioni storiche — richiesta HTTP POST all’endpoint /historical
  • Autenticazione OAuth:
    • OAuth 1.0 User Context: Tutte le metriche disponibili sono accessibili per i Post di proprietà di un utente che ha autorizzato la tua App tramite OAuth a 3 passaggi. Devi utilizzare gli Access Tokens di quell’utente quando effettui la richiesta.
    • OAuth 2.0 Bearer Token: Alcune metriche (Retweet, Quote Tweets, Replies, Favorites e Video Views) sono disponibili per qualsiasi Post pubblico.
  • Metadati e struttura della richiesta: I dati della richiesta sono un oggetto JSON composto da un array di ID del Post, un array di tipi di interazione e una struttura di raggruppamento delle interazioni.
  • Post per richiesta:
    • endpoint /totals: 250 ID del Post
    • endpoint /28hr: 25 ID del Post
    • endpoint /historical: 25 ID del Post
  • Disponibilità delle metriche di interazione:
    • /totals — Totali delle metriche a partire dalla pubblicazione del Post. Impressions e Engagements sono disponibili per i Post pubblicati negli ultimi 90 giorni, mentre Retweets, Quote Tweets, Replies, Favorites e Video Views sono disponibili per tutti i Post.
    • /28hr — Ultime 28 ore dal momento della richiesta.
    • /historical — Qualsiasi periodo di 28 giorni a partire dal 1° settembre 2014.
  • Tipi di metriche: Ogni richiesta include un array di Tipi di metriche. La disponibilità dipende dall’endpoint e, se si richiede dall’endpoint /totals, dal fatto che i Post siano autorizzati dall’utente.
    • endpoint /totals:
      • Tutti i Post: Favorites, Retweets, Quote Tweets, Replies e Video Views
      • Richiede Contesto utente OAuth 1.0a: Impressions, Engagements, Favorites, Replies e Retweets
    • endpoint /28hr e /historical (richiede Contesto utente OAuth 1.0a con l’Access Token del proprietario del Post): Impressions, Engagements, Favorites, Replies, Retweets, URL Clicks, Hashtag Clicks, Detail Click, Permalink Clicks, Media Clicks, App Install Attempts, App Opens, Post Emails, Video Views e Media Views
  • Raggruppamenti di interazioni: Ogni richiesta include un array di Raggruppamenti di interazioni. Con questi raggruppamenti puoi personalizzare come vengono organizzate le metriche restituite. È possibile includere fino a tre raggruppamenti per ciascuna richiesta. Le metriche possono essere organizzate in base ai seguenti valori:
    • Tutti gli endpoint: ID del Post, Tipo di interazione
    • endpoint /28hr e /historical: Questi endpoint forniscono serie temporali se vengono specificati questi raggruppamenti aggiuntivi: Giorno dell’interazione, Ora dell’interazione
  • Aspettative di integrazione: Il tuo team sarà responsabile di quanto segue.
    • Creare e mantenere un’app client in grado di inviare richieste HTTP all’Engagement API che restituiscano le metriche di interazione per l’ID del Post incluso nella richiesta.
  • Limitazioni
  • Le visualizzazioni video sono disponibili solo per i Post che hanno 1800 giorni o meno.

​
Autenticazione con l’Engagement API

Nota bene:  X deve abilitare l’accesso all’Engagement API per la tua App sviluppatore prima che tu possa iniziare a utilizzare l’API. A tal fine, assicurati di condividere l’App ID che intendi usare per l’autenticazione con il tuo account manager o con il team di supporto tecnico.
Sono disponibili due metodi di autenticazione con l’Engagement API: OAuth 1.0a e OAuth 2.0 Bearer Token.  OAuth 2.0 Bearer Token (anche detto “application-only”) consente di accedere alle metriche di engagement pubblicamente disponibili. Questo metodo di autenticazione può essere utilizzato per ottenere i conteggi totali di Favorites (alias Likes), Retweets, Quote Tweets, Replies e visualizzazioni video per qualsiasi Post disponibile pubblicamente quando si inviano richieste al /totals endpoint.  OAuth 1.0a (anche detto “contesto utente”) consente di effettuare richieste per conto di un utente e di accedere alle metriche di engagement private appartenenti all’utente in questione.  Questo metodo di autenticazione è richiesto per:
  • Tutte le richieste inviate al /28hr endpoint e al /historical endpoint
  • L’accesso a una qualsiasi delle seguenti metriche private: Impressions, Engagements, Media Views, Media Engagements, URL Clicks, Hashtag Clicks, Detail Expands, Permalink Clicks, App Install Attempts, App Opens, Email Post, User Follows e User Profile Clicks
Quando invii una richiesta con OAuth 1.0a, devi includere gli Access Tokens (Access Token e Secret) dell’utente proprietario del Post o della risorsa protetta di interesse. Se non fornisci i corretti Access Tokens dell’utente quando richiedi dati utente protetti, l’Engagement API restituirà un errore 403 Forbidden. L’Engagement API non consente di recuperare i dati di engagement per i Post protetti, anche se stai effettuando l’autenticazione per conto dell’utente proprietario di tali Post. Un tentativo in tal senso restituirà un errore 400 Bad Request, con il messaggio "Tweet ID(s) are unavailable". Se stai inviando una richiesta per conto del tuo account X (in altre parole, l’account che possiede la App sviluppatore), puoi generare gli Access Tokens richiesti direttamente dal developer portal, nella scheda “Keys and tokens” della App sviluppatore. Se stai effettuando una richiesta per conto di un altro utente, dovrai utilizzare il flusso OAuth a 3 vie per ottenere gli Access Tokens necessari. La seguente documentazione contiene ulteriori informazioni su come procedere: OAuth 1.0a: how to obtain a user’s access tokens. Per ulteriori esempi, inclusa l’autenticazione tramite OAuth 1.0a, consulta il codice di esempio Python di XDevelopers per l’Engagement API.

​
Modifiche recenti all’Engagement API

L’Engagement API fornisce metriche preziose su impression e coinvolgimento che consentono di monitorare le prestazioni della tua attività su X. Nel nostro continuo impegno a favorire decisioni di marketing basate sui dati, siamo lieti di condividere modifiche recenti all’Engagement API che offrono maggiore coerenza delle metriche in tutta X.   Abbiamo recentemente implementato modifiche per modernizzare l’Engagement API affinché utilizzi la stessa metodologia di aggregazione delle metriche impiegata dalla dashboard di X analytics (analytics.x.com). Abbiamo adottato un approccio mirato per ridurre al minimo le modifiche con impatto sui client API durante il rilascio di queste nuove metriche e abbiamo distribuito il primo set di modifiche il 9 ottobre 2017. Queste modifiche migliorano la coerenza tra tutti i punti in cui tu o i tuoi clienti monitorate le prestazioni su X. Di seguito trovi il riepilogo dettagliato delle modifiche:
MetricaModifica
engagementsAbbiamo aggiornato le metriche che confluiscono negli engagements complessivi per allinearle con la dashboard Post analytics. Engagements misura “quante volte le persone hanno interagito con questo Post”.

Per i Post che includono media come video o GIF, la metrica engagements non includerà più le visualizzazioni dei media. Le visualizzazioni dei media sono ora disponibili in una nuova metrica, media_views.
media_clicks*Questa metrica è stata sostituita da una nuova metrica chiamata “media_engagements”.
video_viewsDal 6 luglio 2018, questa metrica è disponibile per i Post non di proprietà tramite l’endpoint /totals. Ciò significa che puoi accedere alle visualizzazioni video per tutti i Post utilizzando l’autenticazione app-only. 

Puoi richiedere solo visualizzazioni video più recenti di 1800 giorni. Se provi a richiedere visualizzazioni video per un Post più vecchio di 1800 giorni, riceverai quanto segue:

“unsupported_for_video_views_tweet_ids”: [“TWEET_ID”]

Nota bene: differisce da media_views in quanto video_views si basa sullo standard MRC del 50% del video visibile per almeno due secondi.

Inoltre, potresti riscontrare una discrepanza tra la metrica delle visualizzazioni video mostrata sulle piattaforme di proprietà e gestite da X (app mobile e sito web) e il numero che ricevi tramite gli endpoint /28hr e /historical.

* Le visualizzazioni video mostrate nell’interfaccia utente di X e fornite tramite l’endpoint /totals rappresentano le visualizzazioni video aggregate su tutti i Post in cui è stato pubblicato il video in questione. Ciò significa che la metrica mostrata nell’interfaccia include le visualizzazioni combinate di qualsiasi istanza in cui il video è stato Retweetato o ripubblicato in Post separati.
* Le visualizzazioni video fornite dagli endpoint /28hr e /historical includeranno solo quelle generate dallo specifico Post per il quale stai recuperando le metriche.
media_viewsInclude tutte le visualizzazioni (autoplay e click) dei tuoi media conteggiate su video, Vine, GIF e immagini.

Nota bene: i Post con immagini non mostrano la metrica media_views nella dashboard analytics, ma verrà restituita nell’Engagement API.
media_engagements*Include il numero di clic sui tuoi media tra video, Vine, GIF e immagini. Questa metrica sostituisce media_clicks.
quote_tweetsDal 7 luglio 2020, questa metrica è disponibile per i Post non di proprietà tramite l’endpoint /totals. Ciò significa che puoi accedere al conteggio dei Quote Post per tutti i Post utilizzando l’autenticazione app-only.

​
Interpretare le metriche

Nota: Potresti riscontrare differenze tra i dati mostrati in alcune dashboard web di X e quelli riportati nell’Engagement API. Queste differenze si verificano perché le dashboard web in genere mostrano solo le interazioni e/o le impression avvenute nell’intervallo di tempo selezionato. Ad esempio, una dashboard web può mostrare le interazioni sui Post nell’arco di un mese di calendario, mentre l’Engagement API può includere interazioni che ricadono oltre tale mese ma comunque all’interno dell’intervallo temporale richiesto. In questi casi, l’Engagement API deve essere considerata la fonte di riferimento.  

​
Dati su impression e coinvolgimento

L’Engagement API fornisce dati su impression e coinvolgimento organici. Le impression rappresentano il numero di volte in cui un determinato Post è stato visualizzato sulla piattaforma X in un contesto organico. Le impression generate da Post visualizzati in un contesto Promoted o Paid non sono incluse. Il coinvolgimento rappresenta il numero di volte in cui un determinato Post ha ricevuto interazioni da parte di un utente, sia in un contesto organico sia promoted. Le interazioni includono, a titolo esemplificativo ma non esaustivo, Retweet, Preferiti, Risposte, clic su URL, clic su hashtag, clic su menzioni e visualizzazioni di contenuti multimediali. Per l’elenco completo delle azioni di coinvolgimento incluse, consultare la sezione Engagement Data.  Per calcolare un tasso di coinvolgimento di base, utilizzare il numero totale di interazioni diviso per il numero totale di impression per un determinato Post nel periodo di tempo analizzato. I dati su impression e coinvolgimento possono essere recuperati solo per i Post di @handle di proprietà o di @handle che hanno autorizzato la tua App a visualizzare i dettagli sui loro Post. Internamente, l’Engagement API terrà traccia del numero di @handle univoci richiesti rispetto al limite di @handle contrattuale. Si consiglia inoltre di monitorare, lato client, l’utilizzo delle richieste di @handle durante tutto il mese.  

​
Metriche video

Esistono diverse metriche che rappresentano le impression dei contenuti multimediali su X. La prima è la metrica delle visualizzazioni video, basata sullo standard MRC del 50% del video visibile per almeno due secondi. La seconda è Media Views, che include tutte le visualizzazioni (riproduzione automatica e clic) dei contenuti multimediali, conteggiate su video, Vine, GIF e immagini. La metrica delle visualizzazioni video è disponibile per i Post di proprietà tramite gli endpoint /28hour e /historical, nonché per tutti i Post non di proprietà tramite l’endpoint /totals.  Sebbene la metrica delle visualizzazioni video nell’interfaccia utente di X utilizzi lo stesso standard MRC, tieni presente che potresti riscontrare discrepanze tra la metrica delle visualizzazioni video mostrata sulle piattaforme di proprietà e gestite da X (app mobile e sito web) e il valore che ricevi tramite i diversi endpoint dell’Engagement API.
  • Le visualizzazioni video fornite dall’endpoint /totals e dall’interfaccia utente di X mostrano il totale aggregato delle visualizzazioni su tutti i Post in cui è stato pubblicato il video in questione. Ciò significa che la metrica fornita tramite /totals e visualizzata nella UI di X include le visualizzazioni combinate di qualsiasi istanza in cui il video sia stato oggetto di Retweet o ripubblicato in Post separati.
  • Le visualizzazioni video fornite dagli endpoint /28hour e /historical dell’Engagement API includono solo le visualizzazioni generate dallo specifico Post per il quale stai estraendo le metriche.   
Tieni presente che non forniamo visualizzazioni video per Post più vecchi di 1800 giorni. Invece, forniamo un oggetto che elenca i Post più vecchi di 1800 giorni. Riceverai comunque tutte le altre metriche per i Post richiesti in un oggetto separato. Ecco un esempio di risposta: 
{
  "unsupported_for_video_views_tweet_ids": [
    "479311209565413376",
    "477139122520219648"
  ],
  "grouping name": {
    "479311209565413376": {
      "favorites": "69",
      "impressions": "1692",
      "retweets": "142",
      "video_views": "0"
    },
    "477139122520219648": {
      "favorites": "10",
      "impressions": "1023",
      "retweets": "6",
      "video_views": "0"
    },
    "1397568983931392004": {
      "favorites": "268",
      "impressions": "26803",
      "retweets": "56",
      "video_views": "17902"
    }
  }
}
La metrica Media Views è disponibile solo per i Post di proprietà con gli endpoint /28hour e /historical.

​
Raggruppamenti dell’Engagement API

I raggruppamenti consentono di organizzare in modo personalizzato le metriche di engagement restituite. È possibile includere al massimo 3 raggruppamenti per richiesta. È possibile scegliere di raggruppare le metriche in base a uno o più dei seguenti valori: Tutti e tre gli endpoint supportano:
  • tweet.id
  • engagement.type  
Gli endpoint /28hr e /historical possono fornire metriche in serie temporale e quindi supportano:
  • engagement.day
  • engagement.hour
I raggruppamenti vengono applicati in ordine, quindi è possibile modificare il formato del risultato desiderato cambiando l’ordine dei valori group_by. I raggruppamenti che contengono quattro valori group_by saranno supportati solo in uno dei due formati seguenti: 
"group_by": [
    "tweet.id",
    "engagement.type",
    "engagement.day",
    "engagement.hour"
  ]
Oppure 
"group_by": [
    "engagement.type",
    "tweet.id",
    "engagement.day",
    "engagement.hour"
]
Ad esempio, se vuoi generare i totali complessivi dei tipi di metrica, includi la seguente specifica di “groupings” nella tua richiesta (e consulta la pagina API Reference per ulteriori informazioni su come comporre le richieste): 
{
  "engagement_types": [
    "favorites",
    "replies",
    "retweets"
  ],
  "groupings": {
    "Totali Complessivi": {
      "group_by": [
        "engagement.type"
      ]
    }
  }
}
Con questo raggruppamento, la risposta JSON della Engagement API includerà un attributo al livello radice “Grand Totals” che contiene i totali complessivi per tipo di metriche: 
{
  "Totali Complessivi": {
    "favorites": "12",
    "replies": "2",
    "retweets": "2"
  }
}
Per generare una serie temporale di metriche su 4 ore per un singolo Post, raggruppata per ID del Post, la seguente specifica di raggruppamento farebbe parte della richiesta: 
{
  "start": "2016-02-10T17:00:00Z",
  "end": "2016-02-10T21:00:00Z",
  "tweet_ids": [
    "697506383516729344"
  ],
  "engagement_types": [
    "impressions",
    "engagements"
  ],
  "groupings": {
    "Tweets_MetricType_TimeSeries": {
      "group_by": [
        "tweet.id",
        "engagement.type",
        "engagement.hour"
      ]
    }
  }
}
Con questo raggruppamento, la risposta JSON della Engagement API includerà un attributo a livello di root “Tweets_MetricType_TimeSeries” che contiene le metriche suddivise per ID del Post, quindi per tipo di metrica, e la corrispondente serie temporale oraria: 
{
  "Tweets_MetricType_TimeSeries": {
    "697506383516729344": {
      "impressions": {
        "2016-02-10": {
          "17": "551",
          "18": "412",
          "19": "371",
          "20": "280"
        }
      },
      "engagements": {
        "2016-02-10": {
          "17": "8",
          "18": "6",
          "19": "3",
          "20": "0"
        }
      }
    }
  }
}

​
Domande frequenti

Enterprise

​
API di Engagement

L’accesso all’API di Engagement è previsto tramite un abbonamento Enterprise. Compila questo modulo per metterti in contatto con il nostro team commerciale.
Se il tuo contratto include un limite al numero di handle univoci utilizzabili con l’API di Engagement, il sistema interno di X terrà traccia del numero di utenti autenticati proprietari di Post oggetto di query con l’API di Engagement. I clienti dovrebbero anche monitorare questo numero univoco lato client. Attualmente non esiste un’API o un’interfaccia utente per verificare l’utilizzo degli @handle per l’API di Engagement. Il sistema non bloccherà gli sforamenti se vengono richiesti più @handle rispetto a quanto previsto dal contratto. Alla fine del mese di fatturazione, il numero di @handle unici interrogati viene confrontato con l’importo contrattuale e verrà addebitato l’eventuale sforamento in conformità ai termini contrattuali.
Attualmente non esiste un’API o un’interfaccia utente per verificare l’utilizzo degli @handle per l’API di Engagement. Il sistema non bloccherà gli sforamenti se vengono richiesti più @handle rispetto a quanto previsto dal contratto. Alla fine del mese di fatturazione, il numero di @handle unici interrogati viene confrontato con l’importo contrattuale e verrà addebitato l’eventuale sforamento in conformità ai termini contrattuali.Il campo di metadata engagements restituito nel payload non corrisponde alla somma di tutti i vari totali delle metriche di engagement. Perché?È previsto. Il campo di metadata engagements potrebbe non sempre corrispondere alla somma di tutte le singole metriche di engagement restituite dall’API. Questo perché il campo di metadata engagements può includere ulteriori interazioni che non hanno metriche specifiche riportate separatamente nel payload. In altre parole, sommare tutti i vari totali delle metriche di engagement potrebbe non eguagliare il valore visualizzato nel campo di metrica engagements restituito nel payload.Puoi considerare il campo di metadata engagements come qualsiasi clic o interazione effettuata sul Post.  Il campo url_clicks nella risposta del payload restituisce un numero, quando in realtà il Post non contiene un URL. Com’è possibile?Potrebbe essere perché un Post che contiene, ad esempio, un hashtag (che crea un collegamento a un’altra pagina) verrà conteggiato come clic su URL se un utente ci clicca.  
Ci sono vari motivi per cui potresti non riuscire a recuperare i dati di engagement per un Post specifico, tra cui:
  • L’ID del Post o gli ID del Post richiesti non sono disponibili in base al token di autenticazione che stai usando per recuperare dati per conto di terzi.
  • L’ID del Post o gli ID del Post richiesti, specifici per l’endpoint /totals, non risalgono a 90 giorni o meno e quindi non sono disponibili per restituire le impression o le metriche di engagement.
  • L’ID del Post o gli ID del Post richiesti non sono più disponibili, di solito perché sono stati eliminati o non sono più pubblicamente accessibili per un altro motivo.
Consulta i diversi messaggi di errore che probabilmente riceverai in uno qualsiasi dei casi sopra.
Puoi utilizzare le informazioni x-per-minute-limit e x-per-minute-remaining restituite dall’header della risposta quando invii una richiesta all’API di Engagement per monitorare i tuoi consumi.x-per-minute-limit indica la tua disponibilità e x-per-minute-remaining indica quante chiamate ti restano.

​
Guida alla risoluzione degli errori

Assicurati di consultare le nostre linee guida sull’autenticazione per la Engagement API.
[
    Your account could not be authenticated. Reason: Unknown Authorization Type;
]
Assicurati di non utilizzare alcun access token o secret quando provi ad autenticarti con l’endpoint /totals. Questo perché, se includi questi token e stai tentando di recuperare contenuti da un Post non associato a tali token, è probabile che tu riceva un errore come:
[
    Forbidden to access tweets: 1054424731825229824;
]

​
Non riesci ancora a trovare ciò che cerchi?

Contatta l’assistenza tecnica e ti risponderemo al più presto.

​
Riferimento all’API

​
POST insights/engagement

​
Metodi

MetodoDescrizione
POST /insights/engagement/totalsRecupera il totale delle impression e delle interazioni per una raccolta di Tweet.
POST /insights/engagement/historicalRecupera impression e interazioni per una raccolta di Tweet per un periodo fino a 4 settimane, a ritroso fino al 1° settembre 2014.
POST /insights/engagement/28hrRecupera impression e interazioni per una raccolta di Tweet nelle ultime 28 ore.

​
Autenticazione

L’Engagement API richiede l’uso di HTTPS e supporta sia lo User Context sia l’Application-Only OAuth. La maggior parte delle richieste all’Engagement API richiede l’uso del 3‑Legged OAuth (una versione specifica dello User Context), il che significa che si utilizzano la consumer key e la consumer secret dell’App registrata e approvata per l’accesso all’Engagement API dal tuo account manager di Twitter, oltre all’access token e all’access token secret dei proprietari dei Tweet per chiamare l’endpoint. Le seguenti richieste richiedono questo tipo di OAuth:
  • Qualsiasi richiesta a /totals per ottenere i tipi di metrica Impressions ed Engagements, limitati ai Tweet di proprietà
  • Qualsiasi richiesta a /28hr
  • Qualsiasi richiesta a /historical
Alcune richieste all’Engagement API possono essere eseguite utilizzando l’Application-Only OAuth, il che significa che è sufficiente fornire la consumer key e la consumer secret, oppure un Bearer Token. La seguente richiesta può essere eseguita con questo tipo di OAuth:
  • Qualsiasi richiesta a /totals per ottenere i tipi di metrica Favorites, Replies, Retweets o Video Views, che possono essere recuperati per qualsiasi Tweet
Per qualsiasi richiesta, sarà necessario configurare un’App di Twitter e la corrispondente API Key utilizzando la console di gestione dell’App disponibile su developer.x.com. Nota: puoi visualizzare e modificare le Twitter apps esistenti tramite la Twitter app dashboard se hai effettuato l’accesso al tuo account Twitter su developer.x.com. Una volta configurata la tua App, l’id dell’App dovrà essere approvato dal tuo account representative affinché l’App possa effettuare richieste all’Engagement API. Gli Access Tokens devono essere utilizzati per rappresentare l’“utente corrente” e le richieste effettuate per conto di un utente diverso devono essere firmate con un token valido. Assicurati di codificare i caratteri riservati in modo appropriato all’interno degli URL e dei corpi delle richieste POST prima di preparare le base string per la firma OAuth. Per ulteriori informazioni su come iniziare con OAuth, visita i seguenti link:

​
POST /insights/engagement/totals

L’endpoint totals consente di ottenere le impression e le interazioni totali correnti per un insieme di massimo 250 Tweet alla volta.
Metodo di RichiestaHTTP POST
URLhttps://data-api.x.com/insights/engagement/totals
Tipo di Contenutoapplication/json
CompressioneGzip. Per effettuare una richiesta utilizzando la compressione Gzip, inviare un header Accept-Encoding nella richiesta di connessione.
L’header deve essere nel seguente formato:

Accept-Encoding: gzip
Formato POSTLe richieste possono essere inviate come richiesta POST in cui il corpo è un oggetto JSON contenente una raccolta di ID Tweet e un raggruppamento desiderato. Il POST è formattato come un array con un oggetto tweets, engagements e groupings. Ogni richiesta può contenere un massimo di 250 ID Tweet.

Un esempio di corpo POST è il seguente:


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“favorites”,
“quote_tweets”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}
ID TweetUn array che include gli ID Tweet per i Tweet da interrogare per i dati di coinvolgimento. Si noti che è possibile richiedere dati solo per Tweet creati dall’@handle autenticato. Fino a 250 Tweet possono essere inclusi per richiesta e gli ID Tweet devono essere rappresentati come stringhe.
Tipi di CoinvolgimentoUn array che include i tipi di metriche di coinvolgimento da interrogare. L’endpoint Totals supporta solo i seguenti tipi di coinvolgimento: impressions, engagements, favorites, retweets, quote_tweets, replies, video_views.
L’endpoint /totals supporta la possibilità di recuperare impressions e engagements per Tweet creati negli ultimi 90 giorni, e favorites, retweets, quote_tweets, replies e video_views per qualsiasi Tweet.
RaggruppamentiI risultati dall’API di Coinvolgimento possono essere restituiti in diversi gruppi per adattarsi al meglio alle proprie esigenze. È possibile includere un massimo di 3 raggruppamenti per richiesta.

Per ogni raggruppamento, è possibile definire un nome di raggruppamento personalizzato per facilitare il riferimento a questo tipo di raggruppamento nella propria applicazione.

Una volta definito un nome di raggruppamento, è possibile scegliere di raggruppare tweet.id e/o engagement.type.

I raggruppamenti sono rispettati in sequenza, quindi è possibile modificare il formato del risultato desiderato cambiando l’ordine dei valori group_by. Un esempio di raggruppamento che mostrerà le metriche separate per ID Tweet e tipo di metrica è il seguente:


“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
Limite Dimensione POSTLe richieste possono essere effettuate per un massimo di 250 ID Tweet alla volta.
Formato di RispostaJSON. L’header della richiesta deve specificare il formato JSON per la risposta.
Limite di VelocitàSi sarà soggetti a limite di velocità per minuto, come specificato nel contratto in base al proprio livello di accesso.
Richiesta di Esempio (metriche pubbliche)curl —request POST
—url https://data-api.x.com/insights/engagement/totals
—header ‘accept-encoding: gzip’
—header ‘authorization: Bearer ’
—header ‘content-type: application/json’
—data ’{
“tweet_ids”: [
“1070059276213702656”,“1021817816134156288”,“1067094924124872705”
],
“engagement_types”: [
“favorites”,“retweets”,“replies”,“quote_tweets”,“video_views”
],
“groupings”: {
“perTweetMetricsUnowned”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}
—verbose
—compressed
Richiesta di Esempiocurl —request POST
—url https://data-api.x.com/insights/engagement/totals
—header ‘accept-encoding: gzip’
—header ‘authorization: OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
—header ‘content-type: application/json’
—data ’{
“tweet_ids”: [
“1060976163948904448”,“1045709644067471360”
],
“engagement_types”: [
“favorites”,“replies”,“retweets”,“video_views”,“impressions”,“engagements”
],
“groupings”: {
“perTweetMetricsOwned”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}’
—verbose
—compressed
Risposta di Esempio (metriche pubbliche){
“perTweetMetricsUnowned”: {
“1021817816134156288”: {
“favorites”: “530”,
“quote_tweets”: “79”,
“replies”: “147”,
“retweets”: “323”,
“video_views”: “0”
},
“1067094924124872705”: {
“favorites”: “1360”,
“quote_tweets”: “29”,
“replies”: “56”,
“retweets”: “178”,
“video_views”: “5754512”
},
“1070059276213702656”: {
“favorites”: “69”,
“quote_tweets”: “5”,
“replies”: “7”,
“retweets”: “26”,
“video_views”: “0”
}
}
}
Esempio di Risposta{
“perTweetMetricsOwned”: {
“1045709644067471360”: {
“engagements”: “2”,
“favorites”: “0”,
“impressions”: “47”,
“replies”: “0”,
“retweets”: “8”,
“quote_tweets”: “5”,
“video_views”: “0”
},
“1060976163948904448”: {
“engagements”: “4”,
“favorites”: “0”,
“impressions”: “148”,
“replies”: “1”,
“retweets”: “9”,
“quote_tweets”: “2”,
“video_views”: “0”
}
}
}
ID Tweet Non DisponibiliPer le query che includono ID Tweet che sono stati resi non disponibili (ad esempio, sono stati eliminati), verranno restituiti i dati appropriati per tutti gli ID Tweet disponibili, mentre gli ID Tweet non disponibili saranno referenziati in un array chiamato unavailable_tweet_ids. Ad esempio:

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:00:00Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: “26”,
“quote_tweets”: “2”
}
}
}

​
POST /insights/engagement/28hr

L’endpoint “28 hour” consente di ottenere impression e interazioni per un insieme fino a 25 Tweet nelle ultime 28 ore. L’endpoint “28 hour” consente anche di richiedere tutte le metriche supportate a livello individuale. Per l’elenco completo delle metriche supportate, consultare Metric Availability.
Metodo di richiestaHTTP POST
URLhttps://data-api.x.com/insights/engagement/28hr
Tipo di contenutoapplication/json
CompressioneGzip. Per effettuare una richiesta utilizzando la compressione Gzip, invia un header Accept-Encoding nella richiesta di connessione.
L’header dovrebbe apparire come segue:

Accept-Encoding: gzip
Formato POSTLe richieste possono essere inviate come richiesta POST dove il corpo è un oggetto JSON contenente una raccolta di ID Tweet e un raggruppamento desiderato. Il POST è formattato come un array con un oggetto tweets, engagements e groupings. Ogni richiesta può avere un massimo di 25 ID Tweet.

Un esempio di corpo POST appare come:


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.hour”
]
}
}
}
ID TweetUn array che include gli ID Tweet per i Tweet da interrogare per i dati di coinvolgimento. Si prega di notare che è possibile richiedere dati solo per Tweet che sono stati creati dall’@handle autenticante. L’endpoint 28 ore supporta fino a un massimo di 25 Tweet per richiesta, e gli ID Tweet devono essere rappresentati come stringhe.
Tipi di coinvolgimentoUn array dei tipi di metriche di coinvolgimento da interrogare.

Per l’endpoint 28 ore, impressions, engagements e tutti i tipi di coinvolgimento individuali sono metriche supportate. Per l’elenco completo delle metriche di coinvolgimento supportate vedere Dati di coinvolgimento.
RaggruppamentiI risultati dall’API di coinvolgimento possono essere restituiti in gruppi diversi per adattarsi al meglio alle tue esigenze. Puoi includere un massimo di 3 raggruppamenti per richiesta.

Per ogni raggruppamento, puoi definire un nome di raggruppamento personalizzato per rendere più facile fare riferimento a questo tipo di raggruppamento nella tua applicazione. Una volta definito un nome di raggruppamento, puoi scegliere di raggruppare per uno o più dei seguenti valori:
tweet.id
engagement.type
engagement.day
engagement.hour
I raggruppamenti sono rispettati in serie, così puoi cambiare il formato del risultato desiderato cambiando l’ordine dei tuoi valori group_by. Un esempio di raggruppamento che mostrerà le metriche separate per ID Tweet, tipo di metrica, e appare come:

“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”
]
}
}


I raggruppamenti che hanno 4 elementi group_by sono validi solo se utilizzano uno dei seguenti due ordini. Le richieste che hanno 4 elementi group_by in un singolo raggruppamento che non sono uno dei seguenti restituiranno un errore. Inoltre, sarà consentito solo un raggruppamento con 4 elementi group_by per richiesta.

“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]

“group_by”: [
“engagement.type”,
“tweet.id”,
“engagement.day”,
“engagement.hour”
]
Limite dimensione POSTLe richieste possono essere effettuate per un massimo di 25 ID Tweet alla volta.
Formato rispostaJSON. L’header della tua richiesta dovrebbe specificare il formato JSON per la risposta.
Limite di velocitàSarai soggetto a limitazioni per minuto, come specificato nel tuo contratto secondo il tuo livello di accesso.
Richiesta di esempiocurl -X POST “https://data-api.x.com/insights/engagement/28hr”
-H ‘Accept-Encoding: gzip’
-H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
-d ’{
“tweet_ids”: [
“123456789”
],
“engagement_types”: [
“impressions”,
“engagements”
],
“groupings”: {
“hourly-time-series”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]
}
}
}‘
Esempio di Risposta{
“start”: “2015-09-14T17:00:00Z”,
“end”: “2015-09-15T22:00:00Z”,
“hourly-time-series”: {
“123456789”: {
“impressions”: {
“2015-09-14”: {
“17”: “551”,
“18”: “412”,
“19”: “371”,
“20”: “280”,
“21”: “100”,
“22”: “19”,
“23”: “6”
},
“2015-09-15”: {
“00”: “5”,
“01”: “2”,
“02”: “7”,
“03”: “3”,
“04”: “1”,
“05”: “0”,
“06”: “0”,
“07”: “0”,
“08”: “0”,
“09”: “0”,
“10”: “0”,
“11”: “0”,
“12”: “0”,
“13”: “0”,
“14”: “0”,
“15”: “0”,
“16”: “0”,
“17”: “0”,
“18”: “0”,
“19”: “0”,
“20”: “0”,
“21”: “0”
}
},
“engagements”: {
“2015-09-14”: {
“17”: “0”,
“18”: “0”,
“19”: “0”,
“20”: “0”,
“21”: “0”,
“22”: “0”,
“23”: “0”
},
“2015-09-15”: {
“00”: “0”,
“01”: “0”,
“02”: “0”,
“03”: “0”,
“04”: “0”,
“05”: “0”,
“06”: “0”,
“07”: “0”,
“08”: “0”,
“09”: “0”,
“10”: “0”,
“11”: “0”,
“12”: “0”,
“13”: “0”,
“14”: “0”,
“15”: “0”,
“16”: “0”,
“17”: “0”,
“18”: “0”,
“19”: “0”,
“20”: “0”,
“21”: “0”
}
}
}
}
}
ID Tweet Non DisponibiliPer le query che includono ID Tweet che sono diventati non disponibili (ad esempio, sono stati eliminati), verranno restituiti i dati appropriati per tutti gli ID Tweet disponibili, mentre gli ID Tweet non disponibili saranno indicati in un array denominato unavailable_tweet_ids. Ad esempio:

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:00:00Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: 26
}
}
}

​
POST /insights/engagement/historical

L’endpoint storico consente di ottenere impression e interazioni per un insieme fino a 25 Tweet, per qualsiasi periodo di durata massima di 4 settimane. Al momento non è possibile richiedere tramite API dati antecedenti al 1º settembre 2014. L’endpoint storico consente inoltre di richiedere le metriche per tutte le metriche individuali supportate. Per l’elenco completo delle metriche supportate, consulta Disponibilità delle metriche.
Metodo di RichiestaHTTP POST
URLhttps://data-api.x.com/insights/engagement/historical
Tipo di Contenutoapplication/json
CompressioneGzip. Per effettuare una richiesta utilizzando la compressione Gzip, invia un header Accept-Encoding nella richiesta di connessione.
L’header dovrebbe apparire come segue:

Accept-Encoding: gzip
Formato POSTLe richieste possono essere inviate come richiesta POST dove il corpo è un oggetto JSON contenente una raccolta di ID Tweet e un raggruppamento desiderato. Il POST è formattato come un array con un oggetto tweets, engagements e groupings. Ogni richiesta può avere un massimo di 25 ID Tweet. Ogni richiesta può essere specificata con una data di inizio e fine personalizzata fino a quattro settimane di durata.


{
“tweet_ids”: [
“Tweet ID 1”,
“Tweet ID 2”,
“Tweet ID 3”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.hour”
]
}
}
}
Data di Inizio e FineÈ possibile specificare una data di inizio e fine personalizzata con i valori start e end come parte della richiesta. È necessario specificare una data di inizio e fine che non superino le 4 settimane di durata. La data di inizio più antica possibile al momento è il 1° settembre 2014. Le date di fine nel futuro non sono supportate. Se non vengono fornite date di inizio e fine, l’API utilizzerà come impostazione predefinita le 4 settimane immediatamente precedenti.

La granularità più bassa con cui i dati possono essere restituiti dall’API di Engagement è per ora. Per qualsiasi richiesta effettuata con valori di inizio o fine che non cadono direttamente su un confine orario, le richieste utilizzeranno come impostazione predefinita l’ora inclusiva più vicina. Ad esempio, una richiesta con “start”:“2015-07-01T12:24:00Z” e “end”:“2015-07-10T08:37:00Z” utilizzerà come impostazione predefinita “start”:“2015-07-01T12:00:00Z”,“end”:“2015-07-10T09:00:00Z”.
ID TweetUn array che include gli ID Tweet per i Tweet da interrogare per i dati di engagement. Si prega di notare che è possibile richiedere dati solo per Tweet che sono stati creati dall’@handle autenticante. L’endpoint storico di 4 settimane supporta fino a un massimo di 25 Tweet per richiesta, e gli ID Tweet devono essere rappresentati come stringhe.
Tipi di EngagementUn array che include i tipi di metriche di engagement da interrogare.

Per l’endpoint storico di 4 settimane, impressions, engagements e tutti i tipi di engagement individuali sono metriche supportate. Per l’elenco completo delle metriche di engagement supportate vedere Dati di Engagement.

Nota: Attualmente ci sono tre metriche che verranno visualizzate come zero per le query effettuate prima del 15 settembre 2015: favorites, replies e retweets.
RaggruppamentiI risultati dall’API di Engagement possono essere restituiti in gruppi diversi per adattarsi al meglio alle tue esigenze. Puoi includere un massimo di 3 raggruppamenti per richiesta.

Per ogni raggruppamento, puoi definire un nome di raggruppamento personalizzato per rendere più facile fare riferimento a questo tipo di raggruppamento nella tua applicazione. Una volta definito un nome di raggruppamento, puoi scegliere di raggruppare per uno o più dei seguenti valori:
tweet.id
engagement.type
engagement.day
engagement.hour
I raggruppamenti sono rispettati in sequenza, in modo che tu possa cambiare il formato del risultato desiderato cambiando l’ordine dei tuoi valori group_by. Un esempio di raggruppamento che mostrerà le metriche separate per ID Tweet, tipo di metrica, appare come:

“groupings”: {
“my grouping name”: {
“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”
]
}
}


I raggruppamenti che hanno 4 elementi group_by sono validi solo se utilizzano uno dei seguenti due ordini. Le richieste che hanno 4 elementi group_by in un singolo raggruppamento che non sono uno dei seguenti restituiranno un errore. Inoltre, sarà consentito solo un raggruppamento con 4 elementi group_by per richiesta.

“group_by”: [
“tweet.id”,
“engagement.type”,
“engagement.day”,
“engagement.hour”
]

“group_by”: [
“engagement.type”,
“tweet.id”,
“engagement.day”,
“engagement.hour”
]
Limite Dimensione POSTLe richieste possono essere effettuate per un massimo di 25 ID Tweet alla volta.
Formato RispostaJSON. L’header della tua richiesta dovrebbe specificare il formato JSON per la risposta.
Limite di VelocitàSarai soggetto a limite di velocità per minuto, come specificato nel tuo contratto secondo il tuo livello di accesso.
Richiesta di Esempiocurl -XPOST “https://data-api.x.com/insights/engagement/historical”
-H ‘Accept-Encoding: gzip’
-H ‘Authorization OAuth oauth_consumer_key=“consumer-key-for-app”,oauth_nonce=“generated-nonce”,oauth_signature=“generated-signature”,oauth_signature_method=“HMAC-SHA1”, oauth_timestamp=“generated-timestamp”,oauth_token=“access-token-for-authed-user”, oauth_version=“1.0”’
-d ’{
“start”: “2015-08-01”,
“end”: “2015-08-15”,
“tweet_ids”: [
“123456789”,
“223456789”,
“323456789”
],
“engagement_types”: [
“impressions”,
“engagements”,
“url_clicks”,
“detail_expands”
],
“groupings”: {
“types-by-tweet-id”: {
“group_by”: [
“tweet.id”,
“engagement.type”
]
}
}
}‘
Esempio di Risposta{
“start”: “2015-08-01T00:00:00Z”,
“end”: “2015-08-15T00:00:00Z”,
“types-by-tweet-id”: {
“123456789”: {
“impressions”: “0”,
“engagements”: “0”,
“url_clicks”: “0”,
“detail_expands”: “0”
},
“223456789”: {
“impressions”: “788”,
“engagements”: “134”,
“url_clicks”: “30”,
“detail_expands”: “1323”
},
“323456789”: {
“impressions”: “4”,
“engagements”: “0”,
“url_clicks”: “2”,
“detail_expands”: “0”
}
}
}
ID Tweet Non DisponibiliPer le query che includono ID Tweet che sono diventati non disponibili (ad esempio, sono stati eliminati), verranno restituiti i dati appropriati per tutti gli ID Tweet disponibili, mentre gli ID Tweet non disponibili saranno indicati in un array denominato unavailable_tweet_ids. Ad esempio:

{
“start”: “2015-11-17T22:00:00Z”,
“end”: “2015-11-19T02:27:50Z”,
“unavailable_tweet_ids”: [
“323456789”
],
“group1”: {
“423456789”: {
“favorites”: “67”,
“replies”: “8”,
“retweets”: 26
}
}
}

​
Codici di risposta

StatusTextDescription
200OKLa richiesta è stata completata correttamente.
400Bad RequestIn genere, questa risposta si verifica quando la richiesta contiene JSON non valido oppure non invia alcun payload JSON.
401UnauthorizedL’autenticazione HTTP non è riuscita a causa di credenziali non valide. Verifica le tue chiavi e token OAuth.
404Not FoundLa risorsa non è stata trovata all’URL a cui è stata inviata la richiesta, probabilmente perché è stato usato un URL errato.
429Too Many RequestsLa tua App ha superato il limite di richieste all’API.
500Internal Server ErrorSi è verificato un errore sul lato Gnip. Riprova la richiesta utilizzando una strategia di backoff esponenziale.
502Proxy ErrorSi è verificato un errore sul lato Gnip. Riprova la richiesta utilizzando una strategia di backoff esponenziale.
503Service UnavailableSi è verificato un errore sul lato Gnip. Riprova la richiesta utilizzando una strategia di backoff esponenziale.

​
Messaggi di errore

In vari scenari, la Engagement API restituisce messaggi di errore specifici al contesto che la tua applicazione deve essere in grado di gestire. La tabella seguente include esempi comuni di questi messaggi e come interpretarli. Tieni presente che in molti casi la Engagement API può restituire risultati parziali per i dati disponibili, includendo specifici messaggi di errore all’interno di una risposta 200 OK con ulteriori informazioni.
Messaggio di erroreDescrizione
"errors":["Your account could not be authenticated. Reason: Access token not found"]Indica un errore nel componente di autenticazione della richiesta. Il “Reason” dovrebbe fornire informazioni utili per la risoluzione del problema. Se non riesci a risolvere, invia l’errore completo, incluso il “Reason”, al nostro team di supporto.
"errors":["1 Tweet ID(s) are unavailable"],"unavailable_tweet_ids": ["TWEET_IDS"]L’ID o gli ID del Tweet richiesti non sono più disponibili, in genere perché eliminati o non più pubblicamente accessibili per altri motivi.
"errors":["Impressions & engagements for tweets older than 90 days (*TIME_PERIOD*) are not supported"],"unsupported_for_impressions_engagements_tweet_ids":[*TWEET_IDS*]L’ID o gli ID del Tweet richiesti, specifici per l’endpoint /totals, non rientrano negli ultimi 90 giorni e pertanto non sono disponibili per restituire le metriche di impressions o engagements.
"errors":["Forbidden to access tweets: *TWEET_IDS*"]L’ID o gli ID del Tweet richiesti non sono accessibili in base al token di autenticazione che stai utilizzando per recuperare i dati per conto di terzi.
⌘I