Overview: Version 1.1 of the Twitter API

Updated on Wed, 2012-09-05 13:36

Version 1.1 of the Twitter API is the first major update of the API since its launch. We're excited about what it means for developers and we've captured all the meaningful changes here so you don't miss a thing.

Improved rate limits

We're dividing the rate limit window into 15 minute chunks per endpoint, with most individual calls allowing for 15 requests in each window. In most cases, you'll now be able to query the API on a per endpoint basis a lot more than you previously could. Other widely used calls will get a boost of 180 requests per window. This will be particularly advantageous for apps making calls such as GET statuses/show/:id, GET users/lookup, GET search/tweets and others. Be sure to read the API v1.1 Rate Limiting documentation as well as review the per method limits available here.

JSON support only

API v1.1 will support JSON only. We've been hinting at this for some time now, first dropping XML support on the Streaming API and more recently on the trends API. We've chosen to throw our support behind the JSON format shared across the platform. Consequently, we've decided to discontinue support for XML, Atom, and RSS, which are infrequently used today. For historical context, when we originally built the API all major languages did not have performant, well vetted libraries supporting JSON — today they do.

Authentication required on all endpoints

In version 1.1, we're requiring applications to authenticate all of their requests with OAuth 1.0a. Not only will this visibility allow us to prevent abusive behavior, but it will also help us to further understand how categories of applications are using the API. We'll apply that understanding to better meet the needs of developers as we continue to evolve the platform. At this time, all authentication requires user context, but in the coming weeks we'll be pushing out support for a form of authentication not requiring a user context.

Updated Developer Rules of the Road

We updated the Developer Rules of the Road and created a summary of the most important policy concepts you should know.

Developer Display Requirements

Our previous Display Guidelines have been updated, and are now considered Display Requirements. You'll want to review these new Developer Display Requirements if you're rendering Tweets or timelines on the web or in a mobile context.

New Twitter client policies

All applications replicating the core Twitter experience, usually called "clients", will have some new restrictions placed on them, including a 100,000 user token limit. To be clear, the 100,000 user token limit applies only to the small number of clients replicating the core Twitter experience - it does not apply to the majority of other applications in the broader ecosystem. These new clauses are outlined in detail in our updated Developer Rules of the Road.

Default entities and retweets

Where applicable, entities and retweets will now be returned by default in v1.1. Entities will be returned as part of Tweet objects unless the include_entities parameter is set to false. Native retweets will be included in timelines unless the include_rts parameter is set to false.

Deprecation of v1.0 of the API

Most developers won't need to do much work to transition from v1.0 to v1.1, but we want to make sure there is ample time to do so. We will be providing a 6 month window before turning off v1.0. Starting March 5th, 2013, the 1.0 endpoints will no longer be available.

dev.twitter.com Updates

The documentation on dev.twitter.com reflects the latest changes and methods available in API v1.1. To better distinguish whether you're viewing docs for v1.0 or v1.1, at the top of each endpoint document you'll notice new blue pills indicating the version.

Feedback and next steps

If you find any issues with the new version of the API, please use the Issue Tracker to report what you're noticing. Lastly, we've created an FAQ for version 1.1 to answer the most common questions. If you don't find the answer in there, you can always post in the discussion thread dedicated to API v1.1 where we'll be available and actively listening to all of your feedback. We look forward to working with you through the evolution to version 1.1 and can't wait to see what everyone builds.