Introduction

With the launch of the v2 version of the Twitter API, we have adopted a new data response format and method of requesting different objects and fields, which we are simply calling the Twitter API v2 format. 

In the general differences section, you can learn about some changes that are relevant to standard, premium, and enterprise users. However, we also put together a specific guide for the standard v1.1 Native format, the premium and enterprise Native Enriched format, and the enterprise Activity Streams format which helps to map fields and explains which fields and expansions you must use to request the new v2 fields. 

 

General differences

Requesting objects and fields

One of the biggest changes between the pre-v2 endpoints and v2 is that the newer version only returns a few fields by default, whereas standard, premium, and enterprise endpoints deliver most fields by default. The new version uses parameters called fields and expansions to specifically request additional data beyond the defaults, meaning that you can request just the data you need without having to ingest fields that don’t matter to you. 

Any fields that you request that relate to the primary data object will return in that primary data object along with the default values. However, if you request any expanded objects using the expansions parameter, the secondary objects will return in a new includes object. You can match the expanded objects in the includes object back to the primary object by using the ID field which will return in both.

For example, if you are using the v2 Tweet lookup endpoint and you include the expansions=author_id parameter in your request, you will receive the author_id field within the primary Tweet object, as well as a user object per Tweet in the includes object, each of which will include the default id field that can be used to match the user object back to the Tweet object. Here is an example of what this looks like:

      {
  "data": [
    {
      "author_id": "2244994945",
      "id": "1397568983931392004",
      "text": "The Twitter Developer Platform. Ooh la la! https://t.co/iGTdPXBfOv https://t.co/Ze8z8EODdg"
    }
  ],
  "includes": {
    "users": [
      {
        "id": "2244994945",
        "name": "Twitter Dev",
        "username": "TwitterDev"
      }
    ]
  }
}
    

 

Updated JSON design

In addition to the changes in how you request certain fields, Twitter API v2 is also introducing new JSON designs for the objects returned by the APIs, including Tweet and user objects.

  • At the JSON root level, the standard endpoints return Tweet objects in a statuses array, while Twitter API v2 returns a data array. 
  • Instead of referring to Retweeted and Quoted "statuses", Twitter API v2 JSON refers to Retweeted and Quoted Tweets. Many legacy and deprecated fields, such as contributors and user.translator_type are being removed. 
  • 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 a non-null values. 
     

New v2 fields

We also introduced a new set of fields to the Tweet object including the following:

  • conversation_id field
  • Two new annotations fields, including context and entities
  • Several new metrics fields 
  • A new reply_setting field, which shows you who can reply to a given Tweet
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.