Premium v1.1 compared to Twitter API v2
Similarities
- OAuth 2.0 Bearer Token
- Pagination
- Timezone
Differences
- Endpoint URLs
- App and project requirement
- Available time periods
- Response data format
- HTTP methods
- Request time formats
- Request parameters
- Filtering operators
Similarities
OAuth 2.0 Bearer Token
Both the premium version of the Search API and the v2 version of full-archive search require authentication with OAuth 2.0 Bearer Token. Therefore, if you were previously using the premium version of the endpoint you can continue using the same authentication method if you migrate to the Twitter API v2 version.
Please note that the v2 recent search endpoint allows for you to authenticate with OAuth 1.0a User Context or OAuth 2.0 Bearer Token, whereas full-archive search only allows OAuth 2.0 Bearer Token.
Pagination
While v2 has additional pagination features (new pagination parameters that allow you to navigate using Tweet IDs with since_id
and until_id
), both premium and v2 allow you to paginate using time (fromDate
and toDate
with premium, and start_time
and end_time
for v2).
If you are using the premium version, you will use the next
parameter to paginate, the next token field will be called next
, and it will be located at the root in the response.
If you are using v2, you can use either the next_token
or pagination_token
parameter to paginate, and your next token will be located at meta.next_token
in the response.
Timezone
As noted in the pagination section, you can navigate different pages of data using time for both premium and v2. In both cases, you will be using UTC as the timezone when using these parameters.
Differences
Endpoint URLs
- Premium endpoints:
- 30 day -
https://api.twitter.com/1.1/tweets/search/30day/:label.json
- Full-archive -
https://api.twitter.com/1.1/tweets/search/fullarchive/:label.json
- 30 day -
- Twitter API v2 endpoints
- Recent (7 day) -
https://api.twitter.com/2/tweets/search/recent
- Full-archive -
https://api.twitter.com/2/tweets/search/all
- Recent (7 day) -
App and Project requirement
The Twitter API v2 endpoints require that you use credentials from a developer App that is associated with a Project when authenticating your requests. All Twitter API v1.1 endpoints can use credentials from standalone Apps or Apps associated with a Project.
Available time periods
Both the premium API and Twitter API v2 offer endpoints that allow you to search Tweet data from the full-archive of Tweets.
However, the Twitter API v2 does not offer a 30 day time period endpoint like the Premium API does. Instead it offers the aforementioned full-archive, or a 7 day time period, which align with the v2 Tweet counts endpoints.
Response data format
We have put together a data format migration guide which can help you map premium fields to the newer v2 fields. This guide will also provide you the specific expansion and field parameter that you will need to pass with your v2 request to return specific fields.
One of the biggest differences between the premium response format, also known as Native Enriched, and Twitter API v2’s format is how you select which fields return in your payload.
For the premium Search API, you receive many of the response fields by default, and then have the option to use parameters to identify which fields or sets of fields should return in the payload.
The Twitter API v2 version only delivers the Tweet id
and text
fields by default. To request any additional fields or objects, you will need to use the fields and expansions parameters. Any Tweet fields that you request from these endpoints will return in the primary Tweet object. Any expanded user, media, poll, or place objects and fields will return in an includes
object within your response. You can then match any expanded objects back to the Tweet object by matching the IDs located in both the Tweet and the expanded object.
We encourage you to read more about these new parameters in their respective guides, or by reading our guide on how to use fields and expansions.
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 adata
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
anduser.translator_type
are being removed. - Instead of using both
favorites
(in Tweet object) andfavourites
(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.
We also introduced a new set of fields to the Tweet object including the following:
- A conversration_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
And one last note. The premium response includes a requestParameters
object at the root level, which contains the parameters that you included in your request. The v2 version instead contains a meta
object that lives at the root level which includes the newest_id
, oldest_id
, result_count
, and next_token
if there is an additional page of results.
HTTP methods
The premium version of the API allows you to pass the request as either a POST HTTP method with a JSON body, or a GET HTTP method with a query string.
V2 only allows you to use the GET HTTP method with a query string.
Request time formats
The premium version of this endpoint uses the following date/time format in both the pagination parameters and the timePeriod
response field: YYYYMMDDHHmm
The v2 endpoint uses ISO 8601/RFC 3339 date/time format in both the pagination parameters and the start
and end
response fields: YYYY-MM-DDTHH:mm:ssZ
Request parameters
The following is a table of the request parameters for premium and Twitter API v2:
Premium | Search Tweets v2 |
---|---|
query | query |
maxResults | max_results |
fromDate (YYMMDDHHmm) | start_time (YYYY-MM-DDTHH:mm:ssZ) |
toDate (YYMMDDHHmm) | end_time (YYYY-MM-DDTHH:mm:ssZ) |
since_id | |
until_id | |
next | next_token and pagination_token |
Filtering operators
While the operators between premium and Twitter API v2 are mostly the same, there are some differences in operator availability and some new operators that were introduced to just the Twitter APi v2 version.
To see a full table of the operators that are available for Twitter API v2, premium, and even enterprise, please visit the search Tweets migration landing page.