Annotations


Interested in exploring Labs?
The endpoints we release in Labs are previews of tools that may be released more broadly in the future, but will likely undergo changes before then. We encourage you to take that into consideration as you explore. Before getting started, please read more about Twitter Developer Labs.
 

Overview

Annotations have been added to the the Tweet object on the Tweets, Recent Search, Filtered Stream, and Sampled Stream Tweet payloads as a way to offer contextual information about the Tweet itself. Tweets are analyzed and annotated based on the content of the Tweet.

  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: While we are working to move the filtered stream and sampled stream endpoints to v2, there will be some differences when requesting annotations.

Endpoint Current Version Query Parameters for context_annotations Query Parameters for entities
Filtered Stream 1 format=detailed format=detailed OR format=default
Sampled Stream
1 format=detailed format=detailed OR format=default
Tweets 2 tweet.fields=context_annotations tweet.fields=entities
Recent Search
2 tweet.fields=context_annotations tweet.fields=entities


 

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 - Barack Obama, Daniel, or George W. Bush
  • Place - Detroit, Cali, or "San Francisco, California"
  • Product - Mountain Dew, Mozilla Firefox
  • Organization - Chicago White Sox, IBM
  • Other - Diabetes, Super Bowl 50
     

Here is a response snippet with the default and entities fields:

{
    "data": {
        "entities": {
            "annotations": [
                {
                    "start": 55,
                    "end": 61,
                    "probability": 0.9596,
                    "type": "Product",
                    "normalized_text": "Android"
                }
            ]
        },
        "id": "1189226081406083073",
        "text": "Sharing Tweets in DMs is our love language. Today, for Android users, we’re making that easier."
    }
}

 

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 the default andcontext_annotationsfields:

{
    "data": {
        "context_annotations": [
            {
                "domain": {
                    "id": "45",
                    "name": "Brand Vertical",
                    "description": "Top level entities that describe a Brands industry"
                },
                "entity": {
                    "id": "781974596165640193",
                    "name": "Technology"
                }
            },
            {
                "domain": {
                    "id": "46",
                    "name": "Brand Category",
                    "description": "Categories within Brand Verticals that narrow down the scope of Brands"
                },
                "entity": {
                    "id": "781974596752842752",
                    "name": "Services"
                }
            },
            {
                "domain": {
                    "id": "46",
                    "name": "Brand Category",
                    "description": "Categories within Brand Verticals that narrow down the scope of Brands"
                }
            },
            {
                "domain": {
                    "id": "47",
                    "name": "Brand",
                    "description": "Brands and Companies"
                },
                "entity": {
                    "id": "10026820777",
                    "name": "Android"
                }
            },
            {
                "domain": {
                    "id": "47",
                    "name": "Brand",
                    "description": "Brands and Companies"
                },
                "entity": {
                    "id": "10045225402",
                    "name": "Twitter"
                }
            },
            {
                "domain": {
                    "id": "65",
                    "name": "Interests and Hobbies Vertical",
                    "description": "Top level interests and hobbies groupings, like Food or Travel"
                },
                "entity": {
                    "id": "848920371311001600",
                    "name": "Technology and computing",
                    "description": "Technology and computing"
                }
            },
            {
                "domain": {
                    "id": "66",
                    "name": "Interests and Hobbies Category",
                    "description": "A grouping of interests and hobbies entities, like Novelty Food or Destinations"
                },
                "entity": {
                    "id": "848985956778561538",
                    "name": "Mobile",
                    "description": "Mobile"
                }
            }
        ],
        "id": "1189226081406083073",
        "text": "Sharing Tweets in DMs is our love language. Today, for Android users, we’re making that easier."
    }
}

 


 

Additional resources

Was this document helpful?

Thank you for the feedback. We’re really glad we could help!

Thank you for the feedback. How could we improve this document?

Thank you for the feedback. Your comments will help us improve our documents in the future.