Migrating from Native Enriched data format to v2
The Native Enriched data format is used by our enterprise products.
The Native Enriched data format has been updated to provide edited Tweet metadata. To learn more about Edit Tweet metadata, check out the Edit Tweets fundamentals page.
If you are using the standard v1.1 endpoints, please refer to the standard v1.1 to v2 guide. If you are using the enterprise products with Activity Streams, we have an Activity Streams to v2 guide for you as well.
Twitter API v2 introduces new JSON designs for Tweet and user objects.
- At the JSON root level, the Native Enriched format returns Tweet objects in a results array, while Twitter API v2 returns a data array.
- Instead of using both favorites (in Tweet object) and favourites (in user object), Twitter API v2 uses the term like.
- Twitter is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Tweet and user attributes are only included if they have non-null values.
- All id fields in v2 will be in string format
In addition to the changes made to the new JSON format, we also introduced a new set of fields to the Tweet object including the following:
- conversation_id
- reply_settings
- alt_text on media
- Two new annotations fields, including context and entities
- Several new metrics fields
- Several new polls fields
Many legacy and deprecated fields are being removed:
- contributors
- Certain entities.media and extended_entities.media fields
- filter_level
- timestamp_ms
- truncated
Native Enriched vs v2 payload structure
The following table displays the high-level objects and format that you can expect to receive from v2 compared to the Native Enriched format.
| Native Enriched structure | v2 structure | |
| Default |
{
~tweet object fields~,
"user": {},
"place": {},
"entities": {
"hashtags": [],
"urls": [],
"user_mentions": [],
"symbols": [],
"annotations": [],
"media": []
},
"extended_entities": {},
"matching_rules": []
}
|
{
"data": [{
"id",
"text",
"edit_history_tweet_ids"
}]
}
|
| With defined field and expansion parameters |
{
"data": [{
~tweet object fields~,
"entities": {
"hashtags": [],
"cashtags": [],
"mentions": [],
"urls": [],
},
"attachments": {
"media_keys": [],
"poll_ids": []
}
}],
"includes": [
"tweets": [~user objects~],
"users": [~user objects~],
"media": [~media objects~],
"places": [~place object~],
"polls": [~poll object~]
],
"matching_rules": []
}
|
Field mapping
The following section describes which native enriched fields map to v2 fields, as well as which v2 parameters are required to receive the new field.
Tweet object
Native Enriched format |
Twitter v2 format |
Required v2 parameters |
Type in v2 |
created_at |
data.created_at |
tweet.fields=created_at |
String |
id |
N/A - See id |
||
id_str |
data.id |
Default |
String |
text |
data.text |
Default |
String |
| edit_history | data.edit_history_tweet_ids | Default | Array |
| edit_controls | data.edit_controls | tweet.fields=edit_controls | Object |
| editable | data.edit_controls.is_edit_eligible | tweet.fields=edit_controls | Boolean |
display_text_range |
N/A - text includes complete text | ||
| source | data.source | tweet.fields=source | String |
truncated |
N/A - text includes complete text |
||
| Not available | data.conversation_id | tweet.fields=conversation_id | String |
| Not available | data.reply_settings | tweet.fields=reply_settings | String |
in_reply_to_status_id |
N/A - See referenced_tweets.id |
||
in_reply_to_status_id_str |
data.referenced_tweets.id (if type=replied_to) |
expansions=referenced_tweets.id |
String |
in_reply_to_user_id |
N/A - See in_reply_to_user_id_str |
||
in_reply_to_user_id_str |
data.in_reply_to_user_id |
tweet.fields=in_reply_to_user_id |
String |
in_reply_to_screen_name |
includes.users..username | tweet.fields=in_reply_to_user_id&expansions=entities.mentions.username |
String |
user |
includes.users |
expansions=author_id |
Object |
| user.id_str | data.author_id | tweet.fields=author_id | String |
geo |
data.geo.place_id |
tweet.fields=geo |
|
coordinates |
data.geo.place_id |
tweet.fields=geo |
|
place |
data.geo.place_id |
tweet.fields=geo |
|
is_quoted_status |
data.referenced_tweets.id (if type=quoted) | tweet.fields=referenced_tweets |
String |
| extended_tweet.full_text | N/A - text is complete text | ||
| Not available | data.public_metrics | tweet.fields=public_metrics | Object |
| quote_count | data.public_metrics.quote_count | tweet.fields=public_metrics | Int |
| reply_count | data.public_metrics.reply_count | tweet.fields=public_metrics | Int |
| retweet_count | data.public_metrics.retweet_count | tweet.fields=public_metrics | Int |
| favorite_count | data.public_metrics.like_count | tweet.fields=public_metrics | Int |
| Not available | data.non_public_metrics | tweet.fields=non_public_metrics | Object |
| Not available | data.non_public_metrics.impression_count | tweet.fields=non_public_metrics | Int |
| Not available | data.non_public_metrics.url_link_count | tweet.fields=non_public_metrics | Int |
| Not available | data.non_public_metrics.user_profile_count | tweet.fields=non_public_metrics | Int |
| Not available | data.organic_metrics | tweet.fields=organic_metrics | Object |
| Not available | data.organic_metrics.like_count | tweet.fields=organic_metrics | Int |
| Not available | data.organic_metrics.retweet_count | tweet.fields=organic_metrics | Int |
| Not available | data.organic_metrics.reply_count | tweet.fields=organic_metrics | Int |
| Not available | data.organic_metrics.impression_count | tweet.fields=organic_metrics | Int |
| Not available | data.organic_metrics.url_link_count | tweet.fields=organic_metrics | Int |
| Not available | data.organic_metrics.user_profile_count | tweet.fields=organic_metrics | Int |
| Not available | data.promoted_metrics | tweet.fields=promoted_metrics | Object |
| Not available | data.promoted_metrics.like_count | tweet.fields=promoted_metrics | Int |
| Not available | data.promoted_metrics.retweet_count | tweet.fields=promoted_metrics | Int |
| Not available | data.promoted_metrics.reply_count | tweet.fields=promoted_metrics | Int |
| Not available | data.promoted_metrics.impression_count | tweet.fields=promoted_metrics | Int |
| Not available | data.promoted_metrics.url_link_count | tweet.fields=promoted_metrics | Int |
| Not available | data.promoted_metrics.user_profile_count | tweet.fields=promoted_metrics | Int |
| contributors | Not available | Not available | |
entities |
data.entities |
tweet.fields=entities |
Object |
entities.user_mentions |
data.entities.mentions |
tweet.fields=entities |
Array of objects |
entities.symbols |
data.entities.cashtags |
tweet.fields=entities |
Array of objects |
entities.hashtags |
data.entities.hashtags |
tweet.fields=entities |
Array of objects |
entities.urls |
data.entities.urls |
tweet.fields=entities |
Array of objects |
entities.media |
includes.media |
expansions=attachments.media_keys |
Array of objects |
| entities.annotations | tweet.fields=entities,context_annotations | Object | |
| entities.annotations.context | data.context_annotations | tweet.fields=entities,context_annotations | Array of objects |
| No equivalent | data.context_annotations.domain | tweet.fields=context_annotations | Object |
| entities.annotations.context.context_domain_id_str | data.context_annotations.domain.id | tweet.fields=context_annotations | String |
| entities.annotations.context.context_domain_id | Not available | Not available - see data.context_annotations.domain.id for string format | |
| entities.annotations.context.context_domain_name | data.context_annotations.domain.name | tweet.fields=context_annotations | String |
| entities.annotations.context.context_domain_description | data.context_annotations.domain.description | tweet.fields=context_annotations | String |
| No equivalent | data.context_annotations.entity | tweet.fields=context_annotations | Object |
| entities.annotations.context.context_entity_id_str | data.context_annotations.entity.id | tweet.fields=context_annotations | String |
| entities.annotations.context.context_entity_id | Not available | Not available - see data.context_annotations.entity.id for string format | |
| entities.annotations.context.context_entity_name | data.context_annotations.entity.name | tweet.fields=context_annotations | String |
| entities.annotations.context.context_entity_description | data.context_annotations.entity.description | tweet.fields=context_annotations | String |
| entities.annotations.entity | data.entities.annotations | tweet.fields=entities,context_annotations | Array of objects |
extended_entities |
data.attachments |
tweet_fields=attachments |
Object |
favorited |
Not available | Not available |
|
retweeted |
Not available | Not available |
|
| retweeted_status | |||
possibly_sensitive |
data.possibly_sensitive |
tweet.fields=possibly_sensitive |
Boolean |
lang |
data.lang |
tweet.fields=lang |
String |
| filter_level | Not available | Not available | |
scopes |
Not available | Not available |
|
| timestamp_ms | Not available | Not available | |
withheld |
data.withheld |
tweet.fields=withheld |
Array of objects |
| matching_rules | matching_rules | Array of objects | |
| matching_rules.id | Not available | Not available | |
| matching_rules.id_str | matching_rules.id | Default with filtered stream | String |
| matching_rules.tag | matching_rules.tag | Default with filtered stream | String |
User object
Native Enriched format |
Twitter v2 format |
Required v2 parameters |
Type in v2 |
user |
includes.users |
expansions=author_id |
Array of objects |
user.id |
Not available |
N/A - See includes.users.id | String |
user.id_str |
includes.users.id |
expansions=author_id |
String |
user.name |
includes.users.name |
expansions=author_id |
String |
user.screen_name |
includes.user.username |
expansions=author_id |
String |
user.location |
includes.users.location |
expansions=author_id&user.fields=location |
Object |
user.description |
includes.users.description |
expansions=author_id&user.fields=description |
String |
Not available |
includes.users.url |
expansions=author_id&user.fields=url |
String |
user.followers_count |
includes.users.public_metrics.followers_count |
expansions=author_id&user.fields=public_metrics |
Int |
user.friends_count |
includes.users.public_metrics.following_count |
expansions=author_id&user.fields=public_metrics |
Int |
user.listed_count |
includes.users.public_metrics.listed_count |
expansions=author_id&user.fields=public_metrics |
Int |
user.created_at |
includes.users.created_at |
expansions=author_id&user.fields=created_at |
String |
user.favourites_count |
|
Not yet available |
|
user.verified |
includes.users.verified |
expansions=author_id&user.fields=verified |
Boolean |
| Not available | includes.users.pinned_tweet_id | expansions=author_id&user.fields=pinned_tweet_id | String |
user.statuses_count |
includes.users.public_metrics.tweet_count |
expansions=author_id&user.fields=public_metrics |
Int |
user.profile_image_url_https |
includes.users.profile_image_url |
expansions=author_id&user.fields=profile_image_url | String |
| user.translator_type | Not available | Not available | |
| user.utc_offset | Not available | Not available | |
| user.time_zone | Not available | Not available | |
| user.geo_enabled | Not available | Not available | |
| user.lang | Not available | Not available - infer from Tweet lang | |
| user.contributors_enabled | Not available | Not available | |
| user.is_translator | Not available | Not available | |
| user.profile_background_color | Not available | Not available | |
| user.profile_background_image_url | Not available | Not available | |
| user.profile_background_image_url_https | Not available | Not available | |
| user.profile_background_title | Not available | Not available | |
| user.profile_sidebar_border_color | Not available | Not available | |
| user.profile_sidebar_fill_color | Not available | Not available | |
| user.profile_text_color | Not available | Not available | |
| user.profile_user_background_image | Not available | Not available | |
| user.profile_image_url | See includes.user.profile_image_url | ||
| user.default_profile | Not available | Not available | |
| user.default_profile_image | Not available | Not available | |
| user.following | Not available | Not available | |
| user.follow_request_sent | Not available | Not available | |
| user.notifications | Not available | Not available | |
| user.withheld_in_countries | includes.users.withheld | expansions=author_id&user.fields=withheld | Object |
| user.protected | includes.users.protected | expansions=author_id&user.fields=protected | Boolean |
| Not available | includes.users.entities | expansions=author_id&user.fields=entities | Object |
| Not available | includes.users.entities.url | expansions=author_id&user.fields=entities | Object |
| Not available | includes.users.entities.url.urls | expansions=author_id&user.fields=entities | Array of objects |
| Not available | includes.users.entities.url.urls.start | expansions=author_id&user.fields=entities | Int |
| Not available | includes.users.entities.url.urls.end | expansions=author_id&user.fields=entities | Int |
| Not available | includes.users.entities.url.urls.url | expansions=author_id&user.fields=entities | String |
| user.url | includes.users.entities.url.urls.expanded_url | expansions=author_id&user.fields=entities | String |
| Not available | includes.users.entities.url.urls.display_url | expansions=author_id&user.fields=entities | String |
| Not available | includes.users.entities.descriptions | expansions=author_id&user.fields=entities | Object |
| Not available | includes.users.entities.descriptions.hashtags | expansions=author_id&user.fields=entities | Array of objects |
| Not available | includes.users.entities.descriptions.hashtags.start | expansions=author_id&user.fields=entities | Int |
| Not available | includes.users.entities.descriptions.hashtags.end | expansions=author_id&user.fields=entities | Int |
| included in user.description | includes.users.entities.descriptions.hashtags.tag | expansions=author_id&user.fields=entities | String |
| Not available | includes.users.entities.descriptions.mentions | expansions=author_id&user.fields=entities | Array of objects |
| Not available | includes.users.entities.descriptions.mentions.start | expansions=author_id&user.fields=entities | Int |
| Not available | includes.users.entities.descriptions.mentions.end | expansions=author_id&user.fields=entities | Int |
| Included in user.description | includes.users.entities.descriptions.mentions.username | expansions=author_id&user.fields=entities | String |
| Not available | includes.users.entities.descriptions.cashtags | expansions=author_id&user.fields=entities | Array of objects |
| Not available | includes.users.entities.descriptions.cashtags.start | expansions=author_id&user.fields=entities | Int |
| Not available | includes.users.entities.descriptions.cashtags.end | expansions=author_id&user.fields=entities | Int |
| Included in user.description | includes.users.entities.descriptions.cashtags.tag | expansions=author_id&user.fields=entities | String |
Entities and expanded entities objects
Native Enriched format |
Twitter v2 format |
Required v2 parameters |
Type in v2 |
entities |
data.entities |
tweet.fields=entities |
Object |
entities.hashtags |
data.entities.hashtags |
tweet.fields=entities |
Array of objects |
entities.hashtags.indices[0] |
data.entities.hashtags.start |
tweet.fields=entities |
Integer |
entities.hashtags.indices[1] |
data.entities.hashtags.end |
tweet.fields=entities |
Integer |
entities.hashtags.text |
data.entities.hashtags.tag |
tweet.fields=entities |
String |
entities.urls |
data.entities.urls |
tweet.fields=entities |
Array of objects |
entities.urls.indices[0] |
data.entities.urls.start |
tweet.fields=entities |
Integer |
entities.urls.indices[1] |
data.entities.urls.end |
tweet.fields=entities |
Integer |
entities.urls.url |
data.entities.urls.url |
tweet.fields=entities |
String |
| entities.urls.expanded_url | data.entities.urls.expanded_url | tweet.fields=entities | String |
| entities.urls.display_url | data.entities.urls.display_url | tweet.fields=entities | String |
| entities.urls.unwound.url | data.entities.urls.unwound_url | tweet.fields=entities | String |
| entities.urls.unwound.status | data.entities.urls.status | tweet.fields=entities | String |
| entities.urls.unwound.title | data.entities.urls.title | tweet.fields=entities | String |
| entities.urls.unwound.description | data.entities.urls.description | tweet.fields=entities | String |
| Not available | data.entities.urls.images | tweet.fields=entities | Array of objects |
| Not available | data.entities.urls.images.url | tweet.fields=entities | String |
| Not available | data.entities.urls.images.width | tweet.fields=entities | Int |
| Not available | data.entities.urls.images.height | tweet.fields=entities | Int |
entities.user_mentions |
data.entities.mentions |
tweet.fields=entities |
Array of objects |
entities.user_mentions.indicies[0] |
data.entities.mentions.start |
tweet.fields=entities |
Integer |
entities.user_mentions.indicies[1] |
data.entities.mentions.end |
tweet.fields=entities |
Integer |
entities.user_mentions.screen_name |
data.entities.mentions.username |
tweet.fields=entities |
String |
entities.symbols |
data.entities.cashtags |
tweet.fields=entities |
Array of objects |
entities.symbols.indices[0] |
data.entities.cashtags.start |
tweet.fields=entities |
Integer |
entities.symbols.indices[1] |
data.entities.cashtags.end |
tweet.fields=entities |
Integer |
entities.symbols.text |
data.entities.cashtags.tag |
tweet.fields=entities |
String |
entities.media OR extended_entities.media |
includes.media |
expansions=attachments.media_keys |
Array of objects |
entities.media.id_str OR extended_entities.media.id_str |
includes.media.media_key |
expansions=attachments.media_keys |
String |
| entities.media.id OR extended_entities.media.id | Not available - id is a String | ||
entities.media.type OR extended_entities.media.type |
includes.media.media.type |
expansions=attachments.media_keys |
String |
| entities.media.indices OR extended_entities.media.indices | Not available | Not available | |
| Not available | includes.media.alt_text | expansions=attachments.media_keys&media.fields=alt_text | String |
| entities.media.additional_media_info OR extended_entities.media.additional_media_info | Not available | Not available | |
| entities.media.additional_media_info.monetizable OR extended_entities.media.additional_media_info.monetizable | Not available | Not available | |
entities.media.media_url OR extended_entities.media.media_url |
|
N/A - See includes.media.url |
String |
entities.media.media_url_https OR extended_entities.media.media_url_https |
includes.media.url |
expansions=attachments.media_keys&media.fields=url |
String |
entities.media.url OR extended_entities.media.url |
|||
entities.media.display_url OR extended_entities.media.expanded_url |
|||
entities.media.expanded_url |
|||
entities.media.media_url_https |
includes.media.preview_image_url |
expansions=attachments.media_keys&media.fields=preview_image_url |
String |
extended_entities |
data.attachments |
tweet_fields=attachments |
Object |
extended_entities |
data.attachments.media_keys |
tweet.fields=attachments |
Array of objects |
| Not available | data.attachments.poll_ids | tweet.fields=attachments | Array of objects |
extended_entities.media.sizes.thumb.w |
Not Available |
||
extended_entities.media.sizes.thumb.h |
|
Not Available |
|
extended_entities.media.sizes.thumb.resize |
|
Not Available |
|
extended_entities.media.sizes.large.w |
includes.media.height |
expansions=attachments.media_keys&media.fields=height |
|
extended_entities.media.sizes.large.h |
includes.media.width |
expansions=attachments.media_keys&media.fields=width |
|
extended_entities.media.sizes.large.resize |
Not Available |
Not Available |
|
extended_entities.media.sizes.small.w |
Not Available |
Not Available |
|
extended_entities.media.sizes.small.h |
Not Available |
Not Available |
|
extended_entities.media.sizes.small.resize |
Not Available |
Not Available |
|
extended_entities.media.sizes.medium.w |
Not Available |
Not Available |
|
extended_entities.media.sizes.medium.h |
Not Available |
Not Available |
|
extended_entities.media.sizes.medium.resize |
Not Available |
Not Available |
|
extended_entities.media.media_url_https |
includes.media.preview_image_url |
expansions=attachments.media_keys&media.fields=preview_image_url |
String |
| extended_entities.media.video_info.aspect_ratio | Not available | Not available | |
| extended_entities.media.variants | Not available | Not available | |
| extended_entities.media.variants.bitrate | Not available | Not available | |
| extended_entities.media.variants.content_type | Not available | Not available | |
| extended_entities.media.variants.url | Not available | Not available | |
extended_entities.media.video_info.duration_millis |
includes.media.duration_ms |
expansions=attachments.media_keys&media.fields=duration_ms |
Int |
| Not available | includes.media.public_metrics | expansions=attachments.media_keys&media.fields=public_metrics | Object |
| Not available | includes.media.public_metrics.view_count | expansions=attachments.media_keys&media.fields=public_metrics | Int |
| Not available | includes.media.non_public_metrics | expansions=attachments.media_keys&media.fields=non_public_metrics | Object |
| Not available | includes.media.non_public_metrics.playback_0_count | expansions=attachments.media_keys&media.fields=non_public_metrics | Int |
| Not available | includes.media.non_public_metrics.playback_25_count | expansions=attachments.media_keys&media.fields=non_public_metrics | Int |
| Not available | includes.media.non_public_metrics.playback_50_count | expansions=attachments.media_keys&media.fields=non_public_metrics | Int |
| Not available | includes.media.non_public_metrics.playback_75_count | expansions=attachments.media_keys&media.fields=non_public_metrics | Int |
| Not available | includes.media.non_public_metrics.playback_100_count | expansions=attachments.media_keys&media.fields=non_public_metrics | Int |
| Not available | includes.media.organic_metrics | expansions=attachments.media_keys&media.fields=organic_metrics | Object |
| Not available | includes.media.organic_metrics.playback_0_count | expansions=attachments.media_keys&media.fields=organic_metrics | Int |
| Not available | includes.media.organic_metrics.playback_25_count | expansions=attachments.media_keys&media.fields=organic_metrics | Int |
| Not available | includes.media.organic_metrics.playback_50_count | expansions=attachments.media_keys&media.fields=organic_metrics | Int |
| Not available | includes.media.organic_metrics.playback_75_count | expansions=attachments.media_keys&media.fields=organic_metrics | Int |
| Not available | includes.media.organic_metrics.playback_100_count | expansions=attachments.media_keys&media.fields=organic_metrics | Int |
| Not available | includes.media.organic_metrics.view_count | expansions=attachments.media_keys&media.fields=organic_metrics | Int |
| Not available | includes.media.promoted_metric | expansions=attachments.media_keys&media.fields=promoted_metrics | Object |
| Not available | includes.media.promoted_metric.playback_0_count | expansions=attachments.media_keys&media.fields=promoted_metrics | Int |
| Not available | includes.media.promoted_metric.playback_25_count | expansions=attachments.media_keys&media.fields=promoted_metrics | Int |
| Not available | includes.media.promoted_metric.playback_50_count | expansions=attachments.media_keys&media.fields=promoted_metrics | Int |
| Not available | includes.media.promoted_metric.playback_75_count | expansions=attachments.media_keys&media.fields=promoted_metrics | Int |
| Not available | includes.media.promoted_metric.playback_100_count | expansions=attachments.media_keys&media.fields=promoted_metrics | Int |
| Not available | includes.media.promoted_metrics.view_count | expansions=attachments.media_keys&media.fields=promoted_metrics | Int |
Place object
Native Enriched format |
Twitter v2 format |
Required v2 parameters |
Type in v2 |
place |
includes.places |
expansions=geo.place_id |
Array of objects |
place.id |
includes.places.id |
expansions=geo.place_id |
String |
| place.url | Not available | Not available | |
place.id.place_type |
includes.places.place_type |
expansions=geo.place_id&place.fields=place_type |
String |
place.id.name |
includes.places.name |
expansions=geo.place_id&place.fields=name |
String |
place.id.full_name |
includes.places.full_name |
expansions=geo.place_id |
String |
place.id.country_code |
includes.places.country_code |
expansions=geo.place_id&place.fields=country_code |
String |
place.id.country |
includes.places.country |
expansions=geo.place_id&place.fields=country |
String |
place.id.contained_within |
includes.places.contained_within |
expansions=geo.place_id&place.fields=contained_within |
Array |
place.id.bounding_box.type |
includes.places.geo.type |
expansions=geo.place_id&place.fields=place_type |
String |
place.id.bounding_box.coordinates |
includes.places.geo.bbox |
expansions=geo.place_id&place.fields=geo |
Array |
place.id.attributes |
includes.places.properties |
expansions=geo.place_id&place.fields=geo |
Object |
Poll object
Native Enriched format |
Twitter v2 format |
Required v2 parameters |
Type in v2 |
entities.polls |
includes.polls | expansions=attachments.poll_ids | Array of objects |
| Not available | includes.polls.id | expansions=attachments.poll_ids | String |
| entities.poll.options | includes.polls.options | expansions=attachments.poll_ids | Array of objects |
| entities.polls.options.position | includes.polls.options.position | expansions=attachments.poll_ids | Int |
| entities.polls.options.text | includes.polls.options.label | expansions=attachments.poll_ids | String |
| Not available | includes.polls.options.votes | expansions=attachments.poll_ids | Int |
| Not available | includes.polls.voting_status | expansions=attachments.poll_ids&poll.fields=voting_status | String |
| entities.polls.duration_minutes | includes.polls.duration_minutes | expansions=attachments.poll_ids&poll.fields=duration_minutes | Int |
| entities.polls.end_datetime | includes.polls.end_datetime | expansions=attachments.poll_ids&poll.fields=end_datetime | Date (ISO 8601) |