Tweet annotations

Overview

Annotations have been added to the Tweet object from all v2 endpoints that return a Tweet object. Tweet annotations offer a way to understand contextual information about the Tweet itself. Though 100% of Tweets are reviewed, due to the contents of Tweet text, only a portion are annotated.

  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.

 

Tweet 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

 

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 - Book Music 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

 

Requesting annotations

Sample Request

  curl --location --request GET 'https://api.twitter.com/2/tweets/1212092628029698048?tweet.fields=context_annotations,entities' --header 'Authorization: Bearer $BEARER_TOKEN'


Sample Response

{
    "data": {
        "context_annotations": [
            {
                "domain": {
                    "id": "119",
                    "name": "Holiday",
                    "description": "Holidays like Christmas or Halloween"
                },
                "entity": {
                    "id": "1186637514896920576",
                    "name": " New Years Eve"
                }
            },
            {
                "domain": {
                    "id": "119",
                    "name": "Holiday",
                    "description": "Holidays like Christmas or Halloween"
                },
                "entity": {
                    "id": "1206982436287963136",
                    "name": "Happy New Year: It’s finally 2020 everywhere!",
                    "description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages "
                }
            },
            {
                "domain": {
                    "id": "45",
                    "name": "Brand Vertical",
                    "description": "Top level entities that describe a Brands industry"
                }
            },
            {
                "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": "47",
                    "name": "Brand",
                    "description": "Brands and Companies"
                },
                "entity": {
                    "id": "10045225402",
                    "name": "Twitter"
                }
            },
            {
                "domain": {
                    "id": "119",
                    "name": "Holiday",
                    "description": "Holidays like Christmas or Halloween"
                },
                "entity": {
                    "id": "1206982436287963136",
                    "name": "Happy New Year: It’s finally 2020 everywhere!",
                    "description": "Catch fireworks and other celebrations as people across the globe enter the new year.\nPhoto via @GettyImages "
                }
            }
        ],
        "entities": {
            "annotations": [
                {
                    "start": 144,
                    "end": 150,
                    "probability": 0.626,
                    "type": "Product",
                    "normalized_text": "Twitter"
                }
            ],
            "urls": [
                {
                    "start": 222,
                    "end": 245,
                    "url": "https://t.co/yvxdK6aOo2",
                    "expanded_url": "https://twitter.com/LovesNandos/status/1211797914437259264/photo/1",
                    "display_url": "pic.twitter.com/yvxdK6aOo2"
                }
            ]
        },
        "id": "1212092628029698048",
        "text": "We believe the best future version of our API will come from building it with YOU. Here’s to another great year with everyone who builds on the Twitter platform. We can’t wait to continue working with you in the new year. https://t.co/yvxdK6aOo2"
    }
}

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.