Data formats migration

Introduction

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

In the general differences section, you can learn about some changes that are relevant to standard, and enterprise users. However, we also put together a specific guide for the standard v1.1 Native format, the 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.

You may also be interested in our visual data format migration tool to help you quickly see the differences between the X API v1.1 data format and the X API v2 format.

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 Postt lookup endpoint and you include the expansions=author_id parameter in your request, you will receive the author_id field within the primary Post object, as well as a user object per Post 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 Post 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, X API v2 is also introducing new JSON designs for the objects returned by the APIs, including Post and user objects.

At the JSON root level, the standard endpoints return Post objects in a statuses array, while X API v2 returns a data array.
Instead of referring to Retweeted and Quoted "statuses", X 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 Post object) and favourites (in user object), X API v2 uses the term like.
X is adopting the convention that JSON values with no value (for example, null) are not written to the payload. Post 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 Post object including the following:

A 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 Post