Basics What's an API? How do I use the Twitter API? I Need Something! How do I get “from [MyApp]” appended to updates sent from my API application? I keep hitting the rate limit. How do I get more requests per hour? How can I reclaim an inactive Twitter account for my project or application? How do I report bugs and request features? My app won't work! What am I doing wrong? Is the Twitter API down? Is my IP banned or blacklisted? Design Patterns How should my bot follow users that follow it or inspect direct messages? How do I keep from running into the rate limit? Where's The API Going? How can I keep up with changes to the Twitter API? When will Twitter support OAuth? When will the firehose be ready? What's the Data Mining Feed and can I have access to it? Are you going to make the REST API and the Search API work the same?

 

Basics

 

What's an API?

The acronym "API" stands for "Application Programming Interface". An API is just a defined way for a program to accomplish a task, usually retrieving or modifying data. In Twitter's case, we provide an API method for just about every feature you can see on our website. Programmers use the Twitter API to make applications, websites, widgets, and other projects that interact with Twitter. Programs talk to the Twitter API over HTTP, the same protocol that your browser uses to visit and interact with web pages.

 

How do I use the Twitter API?

If you want your application to do the sort of things a Twitter user can do, check out the REST API documentation. If you want to search public Twitter updates programmatically, check out the Search API documentation. You don't need to write all the code to talk to the Twitter APIs from scratch, as nice developers have shared open source libraries of code that take care of that. If you want to see examples of complete, working Twitter API projects, there are plenty of open source examples to look through.

 

I Need Something!

 

How do I get “from [MyApp]” appended to updates sent from my API application?

Just fill out this handy form!  Note that you must have a Twitter account and must be signed in to submit the form. We only approve applications and sites that appear legitimate and in the best interest of Twitter, Inc. and our community. We do not approve requests to link to personal sites and weblogs, marketing materials, or anything that rubs us the wrong way.

 

I keep hitting the rate limit. How do I get more requests per hour?

Just fill out this other handy form! Note that you must have a Twitter account and must be signed in as the account you want the rate limits raised for. Please also note that we only approve developers for the whitelist.

 

It may take up to 72 hours for us to get back to you, but we try to respond to requests as fast as possible barring holidays and disasters. Once you're on the whitelist you'll be able to make up to 20,000 requests per hour. Use them wisely!

 

How can I reclaim an inactive Twitter account for my project or application?

Email username@twitter.com and our support staff will get back to you. Not all inactive usernames are available - we do give users a grace period in which they can restore their accounts after they've deleted them. Please be patient: these requests are not the top priority for our support staff and it may take some time before you get a response.

 

How do I report bugs and request features?

You can see the list of existing issues right here.  Please check to be sure your issue hasn't already been reported.  Star an existing issue to vote for it, or add an example to an issue if it describes your bug.  Or, report a new issue if need be.

 

My app won't work!

 

What am I doing wrong?

Chances are good that it's not you, but rather a bug in a HTTP library or Twitter API library that you're using. Try your API request with a known-good, reliable tool like curl. Nine times out of ten, it works with curl. If that doesn't help, use an HTTP proxy like Charles to find out what's going on between your application and the Twitter servers. You absolutely need to provide full HTTP request and response output in order for your fellow Twitter developers to help you out when filing bugs and discussing the API.

 

Is the Twitter API down?

Not likely: Twitter hasn't had more than a couple minutes of downtime in a while. Requests may lag from time to time, but chances are pretty good we're not down. You can always check the Twitter Status log to see what's going on with the site. This log is hosted on a completely different service than Twitter and in a different data center, so it shouldn't be subject to any downtime Twitter might incur.

 

Is my IP banned or blacklisted?

If you made more than your allotment of requests (which is up to 20,000 per hour for whitelisted IPs and accounts), our operations team may very well have blocked your IP or IP  range. We provide our APIs for free and with no guarantees or terms of service. That means we may take steps to ban or block any account, IP, or range of IPs that might be harming our ability to provide Twitter in a timely and reliable way. If you think you've been banned, please email us and we'll sort it out.

 

Design Patterns

 

How should my bot follow users that follow it or inspect direct messages?

By default, Twitter sends an email the first time a user follows you or sends you a direct message.  For your bot-building pleasure, we've added the following headers to those emails:

 

• X-TwitterEmailType - will be 'is_following' or 'direct_message'
• X-TwitterCreatedAt - ex: Thu Aug 07 15:17:15 -0700 2008
• X-TwitterSenderScreenName - ex: 'bob' 
• X-TwitterSenderName - ex: 'Bob Smith' 
• X-TwitterSenderID - ex: 12345
• X-TwitterRecipientScreenName - ex: 'john'
• X-TwitterRecipientName - ex: 'John Doe'
• X-TwitterRecipientID - ex: 67890
• X-TwitterDirectMessageID - ex: 2346346

 

How do I keep from running into the rate limit?

1. Caching. We recommend that you cache API responses in your application or on your site if you expect high-volume usage. For example, don't try to call the Twitter API on every page load of your hugely popular website. Instead, call our API once a minute and save the response on your end, displaying your cached version on your site.
2. Rate limiting by active user. If your site keeps track of many Twitter users (for example, fetching their current status or statistics about their Twitter usage), please consider only requesting data for users who have recently signed in to your site.

 

These are just some example strategies. We're happy to work with you to come up with solutions that keep your application and our API running smoothly. Just shoot api@twitter.com an email.

 

Where's The API Going?

 

How can I keep up with changes to the Twitter API?

There are a number of great ways to follow the changes we make to the Twitter API:

 

• Follow @twitterapi on Twitter.
• Read the low-volume Twitter API Announcements Google group.
• Participate in the conversation on the Twitter Development Talk Google group.
• Check the REST API Changelog right here on the API Wiki or subscribe to its RSS feed.

 

When will Twitter support OAuth?

We'll be launching a private beta in January, 2009 (early February at the very latest). We'll be allowing pretty much anyone who can provide us with cogent and comprehensive bug reports to participate in the private beta. Once we're happy with how OAuth is working, we'll move to a public beta. Once the rest of the bugs are ironed out, OAuth will become the supported authentication system for Twitter, and HTTP Basic Auth will be deprecated after six months.

 

When will the firehose be ready?

By late January, early February 2009. For at least Q1 2009, the "firehose" (the near-realtime stream of all public status updates on Twitter) will only be available to a small group of trusted partners. The firehose is a stream HTTP solution; a client connects to it and the stream begins, ceasing only when the client disconnects. Once we're confident in the stability of the service, we'll add partners on a case-by-case basis. We may allow a wider selection of clients to consume subsets of the public stream (that is, updates from a collection of user IDs or matching specific search terms). We do not intend to allow anonymous, unregulated public access to this stream for any number of legal, financial, and technical reasons.

 

What's the Data Mining Feed and can I have access to it?

The Data Mining Feed is an expanded version of our /statuses/public_timeline REST API method. It returns 600 recent public statuses, cached for a minute at a time. You can request it up to once per minute to get a representative sample of the public statuses on Twitter. We offer this for free (and with no quality of service guarantees) to researchers and hobbyists. All we ask is that you provide a brief description of your research or project and the IP address(es) you'll be requesting the feed from to api@twitter.com. Note that this is not intended to provide a contiguous feed of all public updates on Twitter; please see above for more information on the forthcoming "firehose" solution.

 

Are you going to make the REST API and the Search API work the same?

Yup! That's one of our major goals for 2009.