Please note:

We recently graduated recent search into Twitter API v2: Early Access and announced a 90-day deprecation window. We will retire this endpoint in mid-November 2020.

Learn more about the new recent search, and review our migration resources to update to The New Twitter API.

 

Comparing Labs and premium search endpoints

If you have been working with the premium search endpoint, the goal of this guide is to help you understand the similarities and differences between the premium and Labs search endpoints. If you have premium-based code that you want to use with Labs, read on to see what that conversion will entail. 

Here we are comparing these Twitter search endpoints:

  • Premium:
    • 30-day search: https://api.twitter.com/1.1/tweets/search/30day/:label.json
    • Full-archive search: https://api.twitter.com/1.1/tweets/search/fullarchive/:label.json
  • Labs recent search: https://api.twitter.com/labs/1/tweets/search
     

One fundamental difference between the two is that the Labs recent search endpoint does not include a counts endpoint.

See these sections to learn more about the similarities and differences between Labs and premium search endpoints.

 

Similarities

Authentication

If you have been working with the premium search APIs and making OAuth 2.0 Bearer Token requests, then your code is likely ready to authenticate with the Labs recent search endpoint. If you have have been making requests using a OAuth 1.0a, you will need to switch to OAuth 2.0 Bearer Token. 

Query syntax

The boolean syntax (how rule clauses are OR'ed together, AND'ed together, and excluded/negated) is identical. The only difference is the set of operators supported by the search endpoint. See this table for more information on what operators are available for the Labs, premium, and enterprise tiers. 
 

Differences

Supported HTTP request methods

Premium search supports both GET and POST HTTP request methods. The Labs recent search search endpoint supports only GET requests.

Request parameters

The premium and Labs search endpoints have a similar set of request parameters, although Labs adds support for making requests based on Tweet IDs. 

Premium

Labs  

query

query  

toDate  (YYYYMMDDHHmm)

start_time (YYYY-MM-DDTHH:mm:ssZ)

 

fromDate (YYYYMMDDHHmm)

end_time (YYYY-MM-DDTHH:mm:ssZ)  

(No equivalent)

since_id  


(No equivalent)

until_id  

maxResults

nax_results  

next

next_token  


Tweet and User object JSON

Twitter Developer Labs are introducing new JSON designs for the objects returned by the APIs, including Tweet and User objects. The Labs JSON formats represent the future JSON formats that Twitter APIs will return. We are taking this opportunity to update the JSON key names of common objects and their attributes. Here are some examples of these changes:

  • At the JSON root/top-level, the premium search endpoint returns Tweet objects in a results array, while Labs search returns a data array.
  • Instead of using the term statuses, the term tweet will be used. 
  • 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), Labs uses the term like.  
  • Lab formats are adopting the convention that JSON values with no value (e.g., null) are not written to the payload. Tweet and User attributes are only included if they have a non-null value. 

To see the new JSON field names, see the response section of the Labs recent search API Reference guide.

Response pagination metadata

With premium (and enterprise) search, response payloads include a next token for cases when more "pages" of data are available. These next tokens are included in requests for more data. 

With Labs recent search, response payloads include a meta section with a next_token when another page of data is available, and newest_id and oldest_id Tweet IDs to support polling use cases. 

 


 

Additional resources

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.