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.
- 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.
- 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
- Learn more about the new Developer Labs on the "About Labs" page.
- Learn more about What’s new.
- Give feedback on Twitter Developer Labs.
- Tell us about your experience using the Twitter Developer Labs endpoints by filling out this survey.
