Enrichment dei data: Enterprise

​

Introduzione

Enterprise

Gli enrichment Enterprise sono metadati aggiuntivi inclusi nel payload della risposta di alcune API dei dati. Sono disponibili solo con piani in abbonamento a pagamento.

La tabella seguente offre una breve descrizione di ciascun enrichment:

Enrichment:	Descrizione:
URL espansi e migliorati	Espande automaticamente gli URL accorciati (ad es. bitly) inclusi nel corpo di un Post e fornisce i metadati HTML Title e Description dalla pagina di destinazione.
Oggetto delle regole corrispondenti	Indica quale o quali regole hanno fatto match con i Post ricevuti. L’oggetto restituisce il tag della regola e l’id della regola nell’oggetto di risposta.
Metadati del sondaggio	Indica la presenza di un sondaggio in un Post, include l’elenco delle opzioni del sondaggio e fornisce sia la durata del sondaggio sia l’orario di scadenza.
Profilo geografico	Dati derivati dalla posizione del profilo utente, incluse le coordinate [longitudine, latitudine] (ove possibile) e i metadati del luogo correlato.

​

URL estese e avanzate

L’enrichment “Expanded and Enhanced URL” espande automaticamente le URL accorciate incluse nel corpo di un Post e include l’URL risultante come metadata all’interno del payload. Inoltre, questo enrichment fornisce anche i metadata della pagina HTML ricavati dal title e dalla description della pagina di destinazione.

Dettagli importanti:

• Per risolvere un link accorciato, il nostro sistema invia richieste HTTP HEAD all’URL fornito e segue eventuali reindirizzamenti fino ad arrivare all’URL finale. Questo URL finale (NON il contenuto della pagina) viene quindi incluso nel payload di risposta.

• L’enrichment delle URL aggiunge tra 5 e 10 secondi di latenza agli stream in tempo reale

• Per le richieste effettuate alla Full Archive Search API, i dati di enrichment delle URL estese sono disponibili solo per Post di 13 mesi o più recenti.

• L’enrichment delle URL non è disponibile per link ai Post (inclusi i Tweet citati), ai Moments e ai profili inclusi all’interno di un Post.   

​

Payload del Post

L’arricchimento Expanded ed Enhanced dell’URL è disponibile all’interno dell’oggetto entities del payload del Post, in particolare nell’oggetto entities.urls.unwound. Fornisce i seguenti campi di metadata:

• URL espanso - unwound.url
• Stato HTTP espanso - unwound.status
• Titolo HTML dell’URL espanso - limite di 300 caratteri - unwound.title
• Descrizione HTML dell’URL espanso - limite di 1000 caratteri - unwound.description

Ecco un esempio di oggetto entities con l’arricchimento dell’URL:

"entities": {
    "hashtags": [

    ],
    "urls": [
      {
        "url": "https:\/\/t.co\/HkTkwFq8UT",
        "expanded_url": "http:\/\/bit.ly\/2wYTb9y",
        "display_url": "bit.ly\/2wYTb9y",
        "unwound": {
          "url": "https:\/\/www.forbes.com\/sites\/laurencebradford\/2016\/12\/08\/11-websites-to-learn-to-code-for-free-in-2017\/",
          "status": 200,
          "title": "11 Siti Web per Imparare a Programmare Gratis nel 2017",
          "description": "È assolutamente possibile imparare a programmare gratuitamente... ma quali sono le migliori risorse per raggiungere questo obiettivo? Ecco 11 siti web dove puoi iniziare."
        },
        "indices": [
          10,
          33
        ]
      }
    ],
    "user_mentions": [

    ],
    "symbols": [

    ]
  },

**Questo è un esempio di oggetto entities contenente un link a un Post non arricchito: **

"entities": {
  "urls": [{
    "url": "https://t.co/SywNbZdDmb",
    "expanded_url": "https://x.com/XDevelopers/status/1050118621198921728",
    "display_url": "x.com/XDevelopers/s…",
     "indices": [
        142,
        165
     ]
   }
  ]
}

​

Operatori di filtraggio

I seguenti operatori filtrano e forniscono una corrispondenza tokenizzata sui campi correlati dei metadata dell’URL:

url:

• Esempio: “url:tennis”
• Corrispondenza tokenizzata su qualsiasi Expanded URL che includa la parola “tennis”
• Può anche essere usato come filtro per includere o escludere link da un sito web specifico usando qualcosa come “url:npr.org”

url_title:

• Esempio: “url_title:tennis”
• Corrispondenza tokenizzata su qualsiasi HTML title dell’Expanded URL che includa la parola “tennis”
• Corrisponde ai data dell’HTML title inclusi nel payload, limitati a 300 caratteri.

url_description:

• Esempio: “url_description:tennis”
• Corrispondenza tokenizzata su qualsiasi HTML description dell’Expanded URL che includa la parola “tennis”
• Corrisponde all’HTML description inclusa nel payload, limitata a 1000 caratteri.  

​

Codici di stato HTTP

L’arricchimento degli URL espansi fornisce anche il codice di stato HTTP per l’URL finale che stiamo tentando di “unwind”. Nei casi normali si tratta di un valore 200. Altri valori della serie 400 indicano problemi nella risoluzione dell’URL.

È possibile che vengano restituiti vari codici di stato quando si tenta di “unwind” un URL. Durante il processo di “unwind” di un URL, se riceviamo un reindirizzamento, lo seguiremo indefinitamente finché non:

• Raggiungiamo un codice della serie 200 (successo)
• Raggiungiamo un codice di una serie diversa dai reindirizzamenti (errore)
• Si verifica un timeout perché l’URL finale non può essere risolto in un tempo ragionevole (restituisce un 408 - timeout)
• Si verifica un’eccezione di qualche tipo  

Se si verifica un’eccezione, utilizziamo la seguente mappatura tra cause e codici di stato restituiti:

Causa	Codice di stato restituito
Eccezioni SSL	403 (Forbidden)
“Unwind” non consentito dall’URL	405
Timeout del socket	408 (Timeout)
Unknown Host Exception	404 (Not Found)
Operazione non supportata	404 (Not Found)
Connect Exception	404 (Not Found)
Argomento non valido	400 (Bad Request)
Tutto il resto	400 (Bad Request)

​

Regole di corrispondenza

L’enrichment delle regole di corrispondenza è un oggetto di metadata che indica quale regola o quali regole hanno fatto corrispondenza con i Post ricevuti. È usato più comunemente con lo stream PowerTrack.

La corrispondenza avviene tramite una corrispondenza esatta dei termini contenuti in una regola, analizzando il contenuto dell’attività con e senza punteggiatura. La corrispondenza non è sensibile alle maiuscole/minuscole. Quando il contenuto contiene tutti i termini definiti nella regola, a livello radice sarà presente un oggetto matching_rules che indica la/le regola/e che hanno determinato la corrispondenza.

PowerTrack

I Post erogati tramite PowerTrack (realtime, Replay e Historical) conterranno l’oggetto matching_rules come segue:

"matching_rules": [{
        "tag": null,
        "id": 907728589029646336,
        "id_str": "907728589029646336"
    }]

In PowerTrack, l’oggetto matching_rules riflette tutte le regole che hanno fatto corrispondenza con il risultato in questione. In altre parole, se più di una regola corrisponde a uno specifico Post, questo verrà recapitato una sola volta, ma l’elemento matching_rules conterrà tutte le regole che hanno fatto corrispondenza.

​

Metadati dei sondaggi

I metadati dei sondaggi sono un arricchimento gratuito disponibile in tutti i prodotti (API in tempo reale e storiche) nei payload in formato nativo arricchito. I metadati indicano la presenza del sondaggio in un Post, includono l’elenco delle opzioni del sondaggio e riportano sia la durata del sondaggio sia l’ora di scadenza. Questo arricchimento semplifica il riconoscimento della presenza di un sondaggio e consente il rendering corretto di un Post con sondaggio per la visualizzazione.

Dettagli importanti:

• Disponibile in tutte le API Enterprise (PowerTrack, Replay, Search, Historical PowerTrack)
  • Nota: Per Replay e Historical PowerTrack, questi metadati sono stati resi disponibili per la prima volta il 22/02/17.
• Non include informazioni sui voti o sui risultati dei sondaggi
• Al momento non supporta filtri/operatori
• Disponibile solo nel formato nativo arricchito
  • Il formato nativo arricchito è un’impostazione controllata dall’utente che può essere modificata in qualsiasi momento tramite la Console: Select a Product (PowerTrack, Replay, Search) > Settings tab > Output Format (Leave data in its original format)

​

Payload del Post

Il Post con sondaggio conterrà i seguenti metadati nell’oggetto “entities.polls” del payload:

• Un array “options” con fino a quattro opzioni che includono la posizione (1-4) e il testo dell’opzione
• Data di scadenza del sondaggio
• Durata del sondaggio

Consulta il payload di esempio riportato di seguito per ulteriori informazioni.

​

Payload di esempio

Di seguito è riportato uno snippet del payload nel formato nativo arricchito che evidenzia i metadati aggiunti del sondaggio:

"entities":{
          "hashtags":[],
          "urls":[],
          "user_mentions":[],
          "symbols":[],
          "polls":[
             {
                "options":[
                   {
                      "position":1,
                      "text":"La risposta migliore"
                   },
                   {
                      "position":2,
                      "text":"La risposta migliore"
                   }
                ],
                "end_datetime":"Sat Feb 04 15:33:11 +0000 2017",
                "duration_minutes":1440
             }
          ]
       },

​

Geolocalizzazione profilo

​

Introduzione

Molti profili utente di X includono informazioni pubbliche sulla posizione fornite dall’utente. Questi dati vengono restituiti come una normale stringa in user.location (vedi User object data dictionary). Il Profile Geo Enrichment aggiunge geodati strutturati pertinenti al valore di user.location geocodificando e normalizzando, ove possibile, le stringhe di posizione. Sia le coordinate di latitudine/longitudine sia i relativi metadati del luogo vengono aggiunti a user.derived.locations solo quando inclusi come parte del payload del Post nei prodotti API Enterprise. Questi dati sono disponibili quando si utilizza il formato nativo arricchito e possono essere filtrati con una combinazione di regole PowerTrack.

Nota: Alcuni dei geodati di supporto utilizzati per creare il Profile Geo Enrichment provengono da GeoNames.org e sono utilizzati da X secondo la Creative Commons Attribution 3.0 License.

I dati Profile Geo saranno inclusi nelle API PowerTrack, Replay, Volume Stream, Search e Historical PowerTrack di X.

​

Dati geo del profilo

Nome del campo nativo arricchito	Valore di esempio	Descrizione
user.derived.locations.country	United States	Il paese di provenienza dell’utente che ha creato il Post.
user.derived.locations.country_code	US	Un codice paese ISO-3166 a due lettere che corrisponde al paese di provenienza dell’utente che ha creato il Post.
user.derived.locations.locality	Birmingham	La località (in genere la città) di provenienza dell’utente che ha creato il Post.
user.derived.locations.region	Alabama	La regione (in genere stato/provincia) di provenienza dell’utente che ha creato il Post.
user.derived.locations.sub_region	Jefferson County	La sottoregione (in genere la contea) di provenienza dell’utente che ha creato il Post.
user.derived.locations.full_name	Birmingham, Alabama, United States	Il nome completo (esclusa la sottoregione) del luogo di provenienza dell’utente che ha creato il Post.
user.derived.locations.geo	Vedi sotto	Un array che include un valore di lat/long per una coordinata corrispondente al livello di granularità più basso del luogo di provenienza dell’utente che ha creato il Post.

Le API Historical PowerTrack, Search e PowerTrack supportano il filtraggio basato sui dati geo del profilo. Consulta la documentazione del prodotto pertinente per maggiori dettagli sugli operatori disponibili per il filtraggio dei dati geo del profilo.

​

Esempio di payload

{
    "user": {
        "derived": {
            "locations": \[
                {
                    "country": "Stati Uniti",
                    "country_code": "US",
                    "locality": "Birmingham",
                    "region": "Alabama",
                    "sub_region": "Contea di Jefferson",
                    "full_name": "Birmingham, Alabama, Stati Uniti",
                    "geo": {
                        "coordinates": \[
                            -86.80249,
                            33.52066
                        \],
                        "type": "point"
                    }
                }
            \]
        }
    }
}

​

Limitazioni

• L’arricchimento Profile Geo tenta di determinare la scelta migliore per il luogo geografico descritto nella stringa della località del profilo. Il risultato potrebbe non essere accurato in tutti i casi a causa di fattori come la presenza di più luoghi con nomi simili o nomi ambigui.
• Se nel campo località del profilo di un utente (actor.location) non è fornito alcun valore, non tenteremo di effettuare una classificazione.
• Livello di precisione: se un arricchimento Profile Geo può essere determinato con certezza solo a livello di paese o regione, le geografie di livello inferiore, come subRegion e locality, saranno omesse dal payload.
• L’arricchimento Profile Geo fornisce coordinate lat/long (un singolo punto) che corrispondono al Livello di precisione dei risultati dell’arricchimento. Queste coordinate rappresentano il centro geografico del luogo risultante dall’arricchimento. Ad esempio, se il Livello di precisione è a livello Paese, tali coordinate sono impostate sul centro geografico di quel Paese.
• Gli operatori PowerTrack forniti per le proprietà dell’indirizzo (locality/region/country/country code) sono intenzionalmente granulari per consentire numerose combinazioni di regole. Quando si tenta di indirizzare una località specifica che condivide un nome con un’altra località, considera di combinare le regole di indirizzo. Ad esempio, quanto segue eviterebbe corrispondenze per “San Francisco, Philippines”: profile_locality:“San Francisco” profile_region:California. Quando si creano regole che mirano a singoli campi Profile Geo, tieni presente che ogni livello aggiuntivo di granularità limiterà i risultati visualizzati. In alcuni casi, quando si cerca di esaminare data provenienti da una città, potresti voler fare affidamento solo su una regola di regione in cui la regione copre in modo significativo la città; ad es., la città di Zurigo, Svizzera, può essere efficacemente indirizzata insieme alle aree circostanti con profile_region:“Zurich”.
• Uso con Native Geo Posts: l’arricchimento Profile Geo fornisce un tipo alternativo di geografia per un Post, diverso dal valore geo nativo nel payload. Questi due tipi di geografia possono essere combinati per acquisire tutti i possibili post relativi a una determinata area (in base ai geodati disponibili), sebbene non siano concettualmente equivalenti.