Datenanreicherungen: Enterprise

​

Einführung

Enterprise

Enterprise-Anreicherungen sind zusätzliche Metadaten, die in die Antwort-Nutzlast einiger Daten-APIs aufgenommen werden. Sie sind nur in kostenpflichtigen Abonnements verfügbar.

Die folgende Tabelle enthält eine kurze Beschreibung der einzelnen Anreicherungen:

Anreicherung:	Beschreibung:
Erweiterte und angereicherte URLs	Erweitert automatisch verkürzte URLs (z. B. bitly), die im Text eines Posts enthalten sind, und stellt HTML-Title- und Description-Metadaten von der Zielseite bereit.
Objekt übereinstimmender Regeln	Gibt an, welche Regel(n) auf die empfangenen Posts zutraf(en). Das Objekt liefert in der Antwort den Regel-Tag und die Regel-id zurück.
Umfrage-Metadaten	Vermerkt das Vorhandensein einer Umfrage in einem Post, enthält die Liste der Umfrageoptionen und umfasst sowohl die Umfragedauer als auch die Ablaufzeit.
Profil-Geodaten	Abgeleitete Standortdaten aus dem Nutzerprofil, einschließlich der [Längengrad-, Breitengrad-]Koordinaten (wenn möglich) und zugehöriger Ortsmetadaten.

​

Erweiterte und optimierte URLs

Die Anreicherung „Expanded and Enhanced URL“ erweitert automatisch verkürzte URLs, die im Text eines Posts enthalten sind, und fügt die resultierende URL als metadata innerhalb der Payload hinzu. Zusätzlich stellt diese Anreicherung auch HTML-Seiten-metadata aus dem title und der description der Zielseite bereit.

Wichtige Details:

• Um einen verkürzten Link aufzulösen, sendet unser System HTTP-HEAD-Anfragen an die angegebene URL und folgt allen Weiterleitungen, bis die endgültige URL erreicht ist. Diese endgültige URL (NICHT der Inhalt der Seite selbst) wird dann in die Antwort-Payload aufgenommen.

• Die URL-Anreicherung erhöht die Latenz in Echtzeit-Streams um 5–10 Sekunden.

• Für Anfragen an die Full Archive Search API sind erweiterte URL-Anreicherungsdaten nur für Posts verfügbar, die 13 Monate alt oder jünger sind.

• Die URL-Anreicherung ist nicht verfügbar für Post-Links (einschließlich Quote-Tweets), Moments-Links und Profil-Links, die in einem Post enthalten sind.   

​

Post-Payload

Die Expanded- und Enhanced-URL-Anreicherung befindet sich im entities-Objekt des Post-Payloads – genauer gesagt im Objekt entities.urls.unwound. Sie stellt die folgenden Metadatenfelder bereit:

• Expanded URL – unwound.url
• Expanded HTTP Status – unwound.status
• Expanded URL HTML Title – Limit 300 Zeichen – unwound.title
• Expanded URL HTML Description – Limit 1000 Zeichen – unwound.description

Dies ist ein Beispiel für ein entities object mit der URL-Anreicherung:

"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 Websites, um 2017 kostenlos Programmieren zu lernen",
          "description": "Es ist durchaus möglich, kostenlos Programmieren zu lernen... aber welche sind die besten Ressourcen dafür? Hier sind 11 Websites, mit denen Sie loslegen können."
        },
        "indices": [
          10,
          33
        ]
      }
    ],
    "user_mentions": [

    ],
    "symbols": [

    ]
  },

**Dies ist ein Beispiel für ein Entities-Objekt mit einem nicht angereicherten Post-Link: **

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

​

Filteroperatoren

Die folgenden Operatoren filtern und liefern eine tokenisierte Übereinstimmung in den zugehörigen Feldern der URL-Metadaten:

url:

• Beispiel: „url:tennis“
• Tokenisierte Übereinstimmung bei jeder erweiterten URL (Expanded URL), die das Wort „tennis“ enthält
• Kann auch als Filter verwendet werden, um Links von einer bestimmten Website ein- oder auszuschließen, z. B. mit „url:npr.org“

url_title:

• Beispiel: „url_title:tennis“
• Tokenisierte Übereinstimmung bei jedem HTML-Titel einer erweiterten URL, der das Wort „tennis“ enthält
• Übereinstimmungen basieren auf den im Payload enthaltenen HTML-Titel­daten, die auf 300 Zeichen begrenzt sind.

url_description:

• Beispiel: „url_description:tennis“
• Tokenisierte Übereinstimmung bei jeder HTML-Beschreibung einer erweiterten URL, die das Wort „tennis“ enthält
• Übereinstimmungen basieren auf der im Payload enthaltenen HTML-Beschreibung, die auf 1000 Zeichen begrenzt ist.  

​

HTTP-Statuscodes

Die erweiterte URL-Anreicherung liefert auch den HTTP-Statuscode für die endgültige URL, die wir aufzulösen versuchen. In der Regel ist dies der Wert 200. Andere 400er-Codes weisen auf Probleme bei der Auflösung der URL hin.

Beim Versuch, eine URL aufzulösen, können verschiedene Statuscodes zurückgegeben werden. Während dieses Vorgangs folgen wir Weiterleitungen unbegrenzt, bis wir entweder:

• einen Code der 200er-Serie erreichen (Erfolg)
• einen Code außerhalb der Weiterleitungsserie erhalten (Fehler)
• ein Timeout erhalten, weil die endgültige URL nicht in angemessener Zeit aufgelöst werden konnte (gibt 408 – Timeout zurück)
• auf eine Art Ausnahme stoßen  

Wenn eine Ausnahme auftritt, verwenden wir die folgende Zuordnung zwischen Ursachen und zurückgegebenen Statuscodes:

Grund	Zurückgegebener Statuscode
SSL-Ausnahmen	403 (Forbidden)
Auflösen durch URL nicht erlaubt	405
Socket-Timeout	408 (Timeout)
Unbekannter Host (Exception)	404 (Not Found)
Nicht unterstützte Operation	404 (Not Found)
Verbindungsfehler (Connect Exception)	404 (Not Found)
Ungültiges Argument	400 (Bad Request)
Alles andere	400 (Bad Request)

​

Übereinstimmungsregeln

Die Anreicherung für Übereinstimmungsregeln ist ein metadata-Objekt, das angibt, welche Regel bzw. welche Regeln auf die empfangenen Posts zutrafen. Dies wird am häufigsten mit dem PowerTrack Stream verwendet.

Die Übereinstimmung erfolgt über eine exakte Übereinstimmung der in einer Regel enthaltenen Begriffe, wobei der Inhalt der Aktivität mit und ohne Interpunktion gescannt wird. Die Übereinstimmung ist nicht abhängig von der Groß- und Kleinschreibung. Wenn festgestellt wird, dass der Inhalt alle in der Regel definierten Begriffe enthält, gibt es auf Root-Ebene ein matching_rules-Objekt, das die Regel(n) angibt, die zur Übereinstimmung geführt haben.

PowerTrack

Posts, die über PowerTrack (Echtzeit, Replay und Historisch) ausgeliefert werden, enthalten das matching_rules-Objekt wie folgt:

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

In PowerTrack gibt das Objekt matching_rules alle Regeln wieder, die auf das jeweilige Ergebnis zutreffen. Anders ausgedrückt: Wenn mehr als eine Regel auf einen bestimmten Post zutrifft, wird er nur einmal geliefert, aber das Element matching_rules enthält alle Regeln, die übereingestimmt haben.

​

Umfragemetadaten

Umfragemetadaten sind eine kostenlose Anreicherung, die in allen Produkten (Realtime- und Historical-APIs) in angereicherten Nutzlasten im nativen Format verfügbar ist. Die metadata vermerkt das Vorhandensein der Umfrage in einem Post, includes die Liste der Umfrageoptionen und enthält sowohl die Umfragedauer als auch die Ablaufzeit. Diese Anreicherung erleichtert das Erkennen einer vorhandenen Umfrage und ermöglicht die korrekte Darstellung eines Posts mit Umfrage.

Wichtige Details:

• Verfügbar in allen Enterprise-APIs (PowerTrack, Replay, Search, Historical PowerTrack)
  • Hinweis: Für Replay und Historical PowerTrack wurden diese metadata erstmals am 22.02.2017 bereitgestellt.
• Enthält keine Informationen zu Stimmen/Abstimmungen oder Umfrageergebnisse
• Unterstützt derzeit keine Filter/Operatoren
• Nur im angereicherten nativen Format verfügbar
  • Das angereicherte native Format ist eine benutzergesteuerte Einstellung, die jederzeit über die Console geändert werden kann: Select a Product (PowerTrack, Replay, Search) > Settings tab > Output Format (Leave data in its original format)

​

Post-Nutzlast

Ein Umfrage-Post enthält die folgenden metadata im Objekt „entities.polls“ der Nutzlast:

• Ein „options“-Array mit bis zu vier Optionen, einschließlich der Position (1–4) und des Optionstextes
• Ablaufdatum der Umfrage
• Dauer der Umfrage

Siehe die Beispiel-Nutzlast unten zur weiteren Referenz.

​

Beispiel-Payload

Unten finden Sie einen Ausschnitt der angereicherten Payload im nativen Format, der die hinzugefügten Umfrage-Metadaten hervorhebt:

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

​

Profil-Geodaten

​

Einführung

Viele X-Nutzerprofile enthalten öffentliche Standortinformationen, die vom Nutzer bereitgestellt werden. Diese Daten werden als normaler String in user.location zurückgegeben (siehe User-Objekt-Datenwörterbuch). Die Profile-Geo-Enrichment fügt strukturierte Geodaten hinzu, die für den Wert von user.location relevant sind, indem Standort-Strings, wo möglich, geokodiert und normalisiert werden. Sowohl Breiten-/Längengradkoordinaten als auch zugehörige Orts-Metadaten werden user.derived.locations nur hinzugefügt, wenn sie als Teil der Post-Payload in Enterprise-API‑Produkten enthalten sind. Diese Daten sind bei Verwendung des Enriched Native Format verfügbar und können mit einer Kombination aus PowerTrack-Regeln gefiltert werden.

Hinweis: Einige der unterstützenden Geodaten, die zur Erstellung der Profile-Geo-Enrichment verwendet werden, stammen von GeoNames.org und werden von X unter der Creative Commons Attribution 3.0 License genutzt.

Profile-Geo-Daten werden in den PowerTrack-, Replay-, Volume-Stream-, Search- und Historical-PowerTrack-APIs von X enthalten sein.

​

Profil-Geo-Daten

Angereicherter nativer Feldname	Beispielwert	Beschreibung
user.derived.locations.country	United States	Das Land, aus dem der Nutzer stammt, der den Post erstellt hat.
user.derived.locations.country_code	US	Ein zweibuchstabiger ISO-3166-Ländercode, der dem Land entspricht, aus dem der Nutzer stammt, der den Post erstellt hat.
user.derived.locations.locality	Birmingham	Die Ortschaft (in der Regel Stadt), aus der der Nutzer stammt, der den Post erstellt hat.
user.derived.locations.region	Alabama	Die Region (in der Regel Bundesstaat/Provinz), aus der der Nutzer stammt, der den Post erstellt hat.
user.derived.locations.sub_region	Jefferson County	Die Unterregion (in der Regel Landkreis/Bezirk), aus der der Nutzer stammt, der den Post erstellt hat.
user.derived.locations.full_name	Birmingham, Alabama, United States	Der vollständige Ortsname (ohne Unterregion), aus dem der Nutzer stammt, der den Post erstellt hat.
user.derived.locations.geo	Siehe unten	Ein Array, das einen Breiten-/Längengradwert für eine Koordinate enthält, der der niedrigsten Granularität des Ortes entspricht, aus dem der Nutzer stammt, der den Post erstellt hat.

Die Historical PowerTrack-, Search- und PowerTrack-APIs unterstützen das Filtern anhand von Profil-Geo-Daten. Siehe die entsprechende Produktdokumentation für Details zu verfügbaren Operatoren zum Filtern von Profil-Geo-Daten.

​

Beispielnutzlast

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

​

Einschränkungen

• Die Profile-Geo-Anreicherung versucht, die passendste geografische Örtlichkeit zu ermitteln, die in der Profil-Standortzeichenfolge beschrieben ist. Das Ergebnis ist möglicherweise nicht in allen Fällen korrekt, etwa aufgrund mehrerer Orte mit ähnlichen oder mehrdeutigen Namen.
• Wenn im Profilstandortfeld eines Nutzers (actor.location) kein Wert angegeben ist, wird keine Klassifizierung vorgenommen.
• Präzisionsstufe: Wenn eine Profile-Geo-Anreicherung nur mit hinreichender Sicherheit auf Länder- oder Regionalebene bestimmt werden kann, werden untergeordnete Geografiestufen wie subRegion und locality aus dem Payload weggelassen.
• Die Profile-Geo-Anreicherung liefert Lat-/Long-Koordinaten (einen einzelnen Punkt), die der Präzisionsstufe der Ergebnisse der Anreicherung entsprechen. Diese Koordinaten repräsentieren das geografische Zentrum der ermittelten Örtlichkeit. Liegt die Präzisionsstufe beispielsweise auf Länderebene, werden die Koordinaten auf das geografische Zentrum dieses Landes gesetzt.
• Die für Adress-Eigenschaften (locality/region/country/country code) bereitgestellten PowerTrack-Operatoren sind bewusst fein granular, um viele Regelkombinationen zu ermöglichen. Wenn Sie eine bestimmte Örtlichkeit anvisieren, die ihren Namen mit einer anderen teilt, sollten Sie Adressregeln kombinieren. So würde Folgendes Treffer für „San Francisco, Philippines“ vermeiden: profile_locality:“San Francisco” profile_region:California. Beim Erstellen von Regeln, die auf einzelne Profile-Geo-Felder abzielen, beachten Sie, dass jede zusätzliche Granularitätsstufe die Ergebnismenge einschränkt. In manchen Fällen, in denen Sie Daten aus einer Stadt betrachten möchten, kann es sinnvoll sein, sich nur auf eine Regionsregel zu stützen, wenn die Region eine erhebliche Überlappung mit der Stadt aufweist; z. B. kann die Stadt Zürich, Schweiz, zusammen mit den umliegenden Gebieten effektiv mit profile_region:“Zurich” anvisiert werden.
• Verwendung mit nativen Geo-Posts: Die Profile-Geo-Anreicherung stellt eine alternative geografische Angabe für einen Post bereit, die sich vom nativen Geo-Wert im Payload unterscheidet. Diese beiden Geografietypen können kombiniert werden, um alle möglichen Posts zu einem bestimmten Gebiet zu erfassen (basierend auf verfügbaren Geodaten), sind jedoch konzeptionell nicht gleichwertig.