Migrating from Native Enriched data format to v2

The Native Enriched data format is used by our premium Search API and enterprise products. 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"
  }]
}
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

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)

 

Was this document helpful?
Thank you

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.