Changes coming in Version 1.1 of the Twitter API

At the end of June, I wrote about how we're working to deliver a consistent Twitter experience, and how we would soon introduce stricter guidelines about how the Twitter API is used. I'd like to give you more information about coming changes to the API and the migration plan while offering insights into today's Twitter ecosystem and why we're making these changes.

In the coming weeks we will release version 1.1 of the Twitter API. To help you plan ahead, we're announcing these changes now, before the new version of the API is available. Changes will include:

required authentication on every API endpoint
a new per-endpoint rate-limiting methodology
changes to our Developer Rules of the Road, especially around applications that are traditional Twitter clients.
Authentication required

Currently, in v1.0 of the Twitter API we allow developers access to certain API endpoints without requiring their applications to authenticate, essentially enabling them to access public information from the Twitter API without us knowing who they are. For example, there are many applications that are pulling data from the Twitter API at very high rates (scraping, bots, etc.) where we only know the IP address of the applications. To prevent malicious use of the Twitter API and gain an understanding of what types of applications are accessing the API in order to evolve it to meet the needs of developers, it's important to have visibility into the activity on the Twitter API and the applications using the platform.

In version 1.1, we will require every request to the API to be authenticated. For developers who are already using OAuth when making API requests, all of your authentication tokens will transition seamlessly from v1.0 to v1.1. If your application is currently using the Twitter API without using OAuth, you will need to update your application before March 2013. There's more information about the timing of the transition from v1.0 to v1.1 below.

Per-endpoint rate limiting

Right now, in version 1.0 of the Twitter API we limit the number of authenticated requests applications can make to 350 calls per hour, regardless of the type of information the application was requesting. This "one size fits all" approach has limited our ability to provide developers more access to endpoints that are frequently requested by applications, while continuing to prevent abuse of Twitter's resources.

In version 1.1, we will provide per-endpoint rate limiting on the API. While an application that only accesses one endpoint may be more restricted, applications that use multiple endpoints will run into rate limiting issues less frequently.

Most individual API endpoints will be rate limited at 60 calls per hour per-endpoint. Based on analysis of current use of our API, this rate limit will be well above the needs of most applications built against the Twitter API, while protecting our systems from abusive applications.

There will be a set of high-volume endpoints related to Tweet display, profile display, user lookup and user search where applications will be able to make up to 720 calls per hour per endpoint.

Full documentation of the rate limiting by endpoint will be released with API v1.1.

Changes to the Developer Rules of the Road

In addition to the functional changes outlined above, we will be making changes to our Developer Rules of the Road when we release API v1.1. Those changes include:

Display Guidelines will be Display Requirements

To ensure that Twitter users have a consistent experience wherever they see and interact with Tweets, in v1.1 of the Twitter API we will shift from providing Display Guidelines to Display Requirements, which we will also introduce for mobile applications. We will require all applications that display Tweets to adhere to these. Among them: linking @usernames to the appropriate Twitter profile, displaying appropriate Tweet actions (e.g. Retweet, reply and favorite) and scaling display of Tweets appropriately based on the device. If your application displays Tweets to users, and it doesn't adhere to our Display Requirements, we reserve the right to revoke your application key.

Requiring pre-installed client applications to be certified by Twitter

With v1.1 we will require developers that are building client applications that are pre-installed on mobile handsets, SIM cards, chipsets or other consumer electronics devices to have their application certified by Twitter. Due to the long lead time required to update pre-installed client applications once they're "in the wild", we want to make sure that the developer is providing the best Twitter experience possible — before the application ships. If you ship an application pre-installed without it being certified by Twitter, we reserve the right to revoke your application key.

Requiring developers to work with us directly if you need a large amount of user tokens

One of the key things we've learned over the past few years is that when developers begin to demand an increasingly high volume of API calls, we can guide them toward areas of value for users and their businesses. To that end, and similar to some other companies, we will require you to work with us directly if you believe your application will need more than one million individual user tokens.

Additionally, if you are building a Twitter client application that is accessing the home timeline, account settings or direct messages API endpoints (typically used by traditional client applications) or are using our User Streams product, you will need our permission if your application will require more than 100,000 individual user tokens.

We will not be shutting down client applications that use those endpoints and are currently over those token limits. If your application already has more than 100,000 individual user tokens, you'll be able to maintain and add new users to your application until you reach 200% of your current user token count (as of today) — as long as you comply with our Rules of the Road. Once you reach 200% of your current user token count, you'll be able to maintain your application to serve your users, but you will not be able to add additional users without our permission.

Finally, there may also be additional changes to the Rules of the Road to reflect the functional changes in version 1.1 of the Twitter API that we've outlined here.

API v1.1 migration period

When we release version 1.1 of the API we will simultaneously announce the deprecation of v1.0. From the day of the release, developers will have six months to migrate applications from v1.0 to v1.1. For developers who are already making authenticated calls to the API, this migration will be relatively easy, and should only involve updating the API endpoint, and testing your application's behavior against the new rate limiting policies. For developers whose applications are accessing the API without authenticating, you will need to update your applications to use OAuth.

Today's Twitter ecosystem

Today on Twitter we see a broad and deep variety of individual developers and companies building applications using data and content from the Twitter API. Roughly speaking, we bucket these applications based on their target audience (i.e. consumers or businesses) and their core feature set (i.e. do they enable users to engage with Tweets, or do they use Tweets for data analysis purposes).

With our new API guidelines, we're trying to encourage activity in the upper-left, lower-left and lower right quadrants, and limit certain use cases that occupy the upper-right quadrant.

Let me explain.

On the left side of the grid are applications that are targeted at businesses.

In the lower-left quadrant, we've seen tremendous innovation in applications and services that serve the business market with analytics products based on Twitter content. For example, Crimson Hexagon builds actionable reports for brands, media companies and political campaigns based on the conversation on Twitter; Topsy has built a real-time analytics dashboard to help finance, government, news and brands react to news; and DataMinr provides analytics for the finance industry.
In the upper-left quadrant are providers of tools that help businesses engage with Twitter including social CRM providers like Sprinklr, HootSuite and Radian6 (acquired by salesforce.com), and integration companies like Mass Relevance, which aggregates and filters Tweets for display on TV.
On the right-hand side of the grid are applications that are targeted at consumers.

In the lower-right quadrant are services that use Twitter content for social influence ranking, such as Klout.
In the upper right-hand quadrant are services that enable users to interact with Tweets, like the Tweet curation service Storify or the Tweet discovery site Favstar.fm.
That upper-right quadrant also includes, of course, "traditional" Twitter clients like Tweetbot and Echofon. Nearly eighteen months ago, we gave developers guidance that they should not build client apps that mimic or reproduce the mainstream Twitter consumer client experience." And to reiterate what I wrote in my last post, that guidance continues to apply today.
Looking ahead

Beyond API v1.1, we look forward to creating new ways for developers to not only build applications using data and content from Twitter, but to also build interactive Twitter Cards.

Since we announced Twitter Cards in June for twitter.com (and in July for Twitter for iPhone and Twitter for Android), we have seen tremendous response; more than 400 developers and publishers are participating in the program, distributing content through expanded Tweets. And over the next several quarters we will introduce new ways for developers to build content experiences and applications into Twitter, through Twitter Cards. Finally, we are hard at work on a new set of features for Twitter for Websites, to enable web developers to easily embed real-time Twitter content on their own sites.

We hope that all of this information gives you more clarity around where we are headed with API v1.1. We look forward to sharing more news about additional and new platform capabilities in the very near future.