Search Tweets

Premium

Premium search APIs

Introduction

Welcome to Twitter's premium Tweet search API. There are two premium search products based on the API:

• Search Tweets: 30-day endpoint → provides Tweets from the previous 30 days.
• Search Tweets: Full-archive endpoint → provides complete and instant access to Tweets dating all the way back to the first Tweet in March 2006.

The Search Tweets API kicks off the next era of innovation for Twitter developers. The premium 30-day and Full-archive endpoints provide low-latency, full-fidelity, query-based access to the Tweet archive with minute granularity. Tweet data are served in reverse chronological order, starting with the most recent Tweet that matches your query. Tweets are available from the search API approximately 30 seconds after being published.

This RESTful API supports a single query of up to 1,024 characters per request. Queries are written with premium operators and filter syntax - see Rules and filtering for more details. Requests can specify any time period, to the granularity of a minute.

There are two endpoints associated with each premium search product.

1. The data endpoint is available to both sandbox and paid users, and can be used to return full tweet payloads of those tweets which match a query.
2. The counts endpoint is just available to paid users and can be used to return the data volume associated with a query

Since search queries can match so many Tweets, matching data are returned one 'page' at a time. Data requests include a maxResults parameter (which defaults to 100 and has a maximum of 500) that determine how many Tweets to return per page, while the count endpoint will include 31-days worth of data per page. In both cases, a next token will be provided in responses that exceed the page limits, which users can use to paginate through the data. You will be provided a new next token in subsequent requests to page through the entire set of Tweets associated with the query.

Developer portal

Like all Twitter APIs, there are initial steps to take to prepare for API integration. The premium APIs can be set up using a Twitter app through the developer portal. To apply for a developer account, please click here and wait for approval. Once approved to use the developer portal, set up a development environment for the Search Tweets endpoints. The developer portal enables the deployment of independent environments (i.e. dev, staging, prod) with different rate limits, consumption, filter-sets, user permissions, etc. You can also manage the product package that you subscribe to through this portal.

When you are finished with those steps you should have a Twitter App Consumer Key and Token for authentication through your Twitter app, along with a search endpoint from the developer portal.

If you are using the 30-day endpoint:

https://api.twitter.com/1.1/tweets/search/30day/my_env_name.json

If you are using the full-archive endpoint:

https://api.twitter.com/1.1/tweets/search/fullarchive/my_env_name.json

Where my_env_name is the development environment name you select.

Product packages

The premium search API supports two tiers of access:

• Free Sandbox access that enables initial testing and development.
  • Note that this tier provides access to full-fidelity Tweet data, but has a lower set of limits and capabilities than Premium access.
• Paid Premium access that provides increased access.

Below is a table that summaries the differences in the Sandbox and Premium tiers. For more information and to manage your subscription, see HERE.

Fundamental API characteristics

• Search Tweets API is an HTTP-based RESTful API that returns responses encoded in JSON.
• All requests require a query parameter that contains filtering syntax for matching Tweets of interest.
• Query syntax is made up of operators that match on various Tweet and user attributes such as keywords, hashtags, URLs.
• Queries can be up to 1,024 characters long (256 with 30-Day Sandbox tier, 128 with Full Archive Sandbox tier).
• Provides both data and counts endpoint:
  • Data endpoint returns Tweet arrays.
  • Counts endpoint returns time-series counts of those Tweets (at Premium tier).
• Provides data and counts from the previous 30 days or Tweets from as early as 2006.
• Returns up to 500 Tweets per response (100 with Sandbox tier), and supports Tweet data pagination by providing ‘next’ tokens.
• Supports both GET and POST requests formats:
  • GET request parameters are URL encoded.
  • POST request parameters are JSON encoded and sent as a data body.

Available operators

Premium search API supports rules with up to 1,024 characters. The Search Tweets APIs support the premium operators listed below. See our Premium operators guide for more details.

Matching on Tweet contents:

• keyword
• "quoted phrase"
• #
• @
• url:
• lang:
   

Matching on accounts of interest:

• from:
• to:
• retweets_of:
   

Tweet attributes*:

• is:retweet
  
• has:mentions
• has:hashtags
• has:media
• has:videos
• has:images
• has:links
• is:verified
  

      * Can not be used in a standalone fashion, must be combined with additional filtering logic.
 

Geospatial operators:

• bounding_box:[west_long south_lat east_long north_lat]
• point_radius:[lon lat radius]
• has:geo
• place:
• place_country:
• has:profile_geo
• profile_country:
• profile_region:
• profile_locality:

Data availability / important date

When using the Full-archive endpoint, keep in mind that the Twitter platform has continued to evolve since 2006. As new features were added, the underlying JSON objects have had new metadata added to it. For that reason it is important to understand when Tweet attributes were added that search operators match on. Below are some of the more fundamental 'born on' dates of important groups of metadata. To learn more about when Tweet attributes were first introduced, see this guide.  

• First Tweet: 3/21/2006
• First Native Retweets: 11/6/2009
• First Geo-tagged Tweets: 11/19/2009
• URLs first indexed for filtering: 8/27/2011
• Enhanced URL expansion metadata (website titles and descriptions): 12/1/2014
• Profile Geo enrichment metadata and filtering: 2/17/2015

Data updates and mutability

With the premium search APIs, some of the data within a Tweet is mutable, i.e. can be updated or changed after initial archival to values current at the time of the request.

This mutable data falls into two categories:

• User object metadata:
  • User’s @handle (numeric ID does not ever change)
  • Bio description
  • Counts: statuses, followers, friends, favorites, lists
  • Profile location
  • Other details such as time zone and language
• Tweet statistics - i.e. anything that can be changed on the platform by user actions (examples below):
  • Favorites count
  • Retweet count

In most of these cases, the search APIs will return data as it exists on the platform at query-time, rather than Tweet generation time. However, in the case of queries using select operators (e.g. from, to, @, is:verified), this may not be the case. Data is updated in our index on a regular basis, with an increased frequency for most recent timeframes. As a result, in some cases, the data returned may not exactly match the current data as displayed on Twitter.com, but matches data at the time it was last indexed.

Note, this issue of inconsistency only applies to queries where the operator applies to mutable data. One example is filtering for usernames, and the best workaround would be to use user numeric IDs rather than @handles for these queries.

Next steps

• Continue to the premium search API reference
• Learn more about premium search operators
• See an example Python client library
• See an example Ruby client library