The endpoints we release in Labs will be previews and are likely to change before they are released broadly, so we encourage you to take that into consideration as you build. Before getting started, we encourage you to read more about Twitter Developer Labs.
 

Annotations

New metadata elements have been added as part of the Tweet object on the filtered stream and sampled stream Tweet payloads. Two new elements, entity and context, each offer contextual information about the Tweet text itself. Tweets are analyzed and annotated based on the content of the Tweet. These newly added elements are referred to as "annotations".

  1. Entity annotations: Entities are comprised of people, places, products, and organizations. Entities are delivered as part of the entity payload section. They are programmatically assigned based on what is explicitly mentioned in the Tweet text.
  2. Context annotations: Derived from the analysis of a Tweet’s text and will include a domain and entity pairing which can be used to discover Tweets on topics that may have been previously difficult to surface.  At present, we’re using a list of 50+ domains to categorize Tweets.
     

Please note: When developers access the filtered stream or sampled stream endpoints, the connection request will deliver the new entity annotations in the default and detailed format. While the context annotations will only be delivered in the detailed format. The new metadata will occur inline with the data object and will only include the field if data is present

GET /labs/1.1/tweets/stream/filter?format=detailed or format=default

Annotation types

Entities

Entity annotations are programmatically defined entities that are nested within the entities field and are reflected as “annotations” in the payload. Each annotation has a confidence score, and an  indication of where in the Tweet text the entities were identified (start and end fields).

The entity annotations can have the following types:

  • Person - for example, "Barack Obama," "Daniel," "George W. Bush"
  • Place - for example, "Detroit," "Cali," "San Francisco, California"
  • Product - for example, "Mountain Dew," "Mozilla Firefox"
  • Organization - for example, "Chicago White Sox," "IBM"
  • Other - for example, "diabetes," "Super Bowl 50"
     

Response snippet with detailed format:

{
  "data": [
    {
      "id": "1189226081406083073",
      "created_at": "2019-10-29T17:02:47.000Z",
      "text": "Sharing Tweets in DMs is our love language. Today, for Android users, we’re making that easier. See more details: https://t.co/eu1upmY4yo",
      "author_id": "783214",
      "in_reply_to_user_id": "783214",
      "referenced_tweets": [
        {
          "type": "replied_to",
          "id": "1151997885455581185"
        }
      ],
      "entities": {
        "urls": [
          {
            "start": 113,
            "end": 137,
            "url": "https://t.co/eu1upmY4yo",
            "expanded_url": "http://developer.twitter.com",
            "display_url": "developer.twitter.com",
            "status": 200,
            "title": "Developers Tap into What’s Happening",
            "description": "Discover the power of Twitter APIs"
          }
        ],
        "annotations": [
          {
            "start": 55,
            "end": 61,
            "probability": 0.9596,
            "type": "Product",
            "normalized_text": "Android"
          }
        ]
      },
      "stats": {
        "retweet_count": 341,
        "reply_count": 372,
        "like_count": 2773,
        "quote_count": 70
      },
      "possibly_sensitive": false,
      "lang": "en",
      "source": "<a href=\"https://mobile.twitter.com\" rel=\"nofollow\">Twitter Web App</a>",
      ...

 

Context

Context annotations are delivered as a context_annotations field in the payload. These annotations are inferred based on the Tweet text and result in domain and/or entity labels.  Context annotations can yield one or many domains. At present, we’re using a list of 50+ domains reflected in the table below.

3 - TV Shows

4 - TV Episodes

6 - Sports Events

10 - Person

11 - Sport

12 - Sports Team

26 - Sports League

27- American Football Game

28 - NFL Football Game

35 - Politicians

38 - Political Race

39 - Basketball Game

40 - Sports Series

45 - Brand Vertical 

46 - Brand Category

47 - Brand

48 - Product

49 - Product Version

54 - Musician 

55 - 56 - Actor

58 - Entertainment Personality

60 - Athlete

65 - Interests and Hobbies Vertical

66 - Interests and Hobbies Category

67 - Interests and Hobbies

68 - Hockey Game

71 - Video Game

78 - Video Game Publisher

79 - Video Game Hardware

84 - BookMusic Genre

85 - Book Genre

86 - Movie

87 - Movie Genre

88 - Political Body

89 - Music Album

90 - Radio Station

91 - Podcast

92 - Sports Personality 

93 - Coach

94 - Journalist

110 - Viral Accounts

114 - Concert

115 - Video Game Conference

116 - Video Game Tournament 

117 - Movie Festival

118 - Award Show

119 - Holiday

120 - Digital Creator

122 - Fictional Character

130 - Multimedia Franchise

132 - Song

136 - Video Game Personality

137 - eSports Team

138 - eSports Player

139 - Fan Community


Response snippet with detailedformat:

      "context_annotations": [
        {
          "domain": {
            "id": "45",
            "name": "Brand Vertical",
            "description": "Top level entities that describe a Brands industry"
          },
          "entity": {
            "id": 781974596165640193,
            "name": "Technology",
            "description": "This entity includes conversation about Information Technology"
          }
        },
        {
          "domain": {
            "id": "46",
            "name": "Brand Category",
            "description": "Categories within Brand Verticals that narrow down the scope of Brands"
          },
          "entity": {
            "id": 10026820777,
            "name": "Android",
            "description": "Mobile operating system based on the Linux kernel."
          }
        }
      ],
      "format": "detailed"
    }
  ]
}

 

Additional resources