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.
How do I count out 140 characters?
Defining a "character", and then counting out 140 of them is key to any Twitter application. It also can be subtlety hard if you are using characters that are beyond ASCII and UTF-8. We've put together a brief primer on how to count characters properly if you need help.
I Need Something!
How do I get “from [MyApp]” appended to updates sent from my API application?
We now recommend developers use OAuth to perform authentication with the API. When applications use OAuth, Twitter automatically knows the source of status updates. We are therefore able to append source attribution (from "[MyApp]") to tweets. If you would like tweets from your application to recieve a source parameter, please register an application and implement OAuth authentication. We will automatically include your application as the source for any tweets sent from your application.
We originally allowed applications to create a source paramter for non-OAuth use but that has been discontinued. Applications pre-OAuth source parameters will remain active, but new registrations are no longer accepted.
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?
We have a primary help articles which talks about username inactivity at http://help.twitter.com/forums/26257/entries/15362-inactive-usernames. In general, we are unable to transfer usernames for personal use at this time. If you believe a Twitter account may be squatting on your trademark and violating Twitter's Terms of Service, please file a ticket at http://help.twitter.com/requests/new regarding 'Trademark/Brand squatting'.
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.
How can I get my app in the sidebar promotion box?
The apps in the sidebar promotion box work like the editor's pick at the bookstore. They are chosen because they do something remarkably well. There is no form you can fill for your application to be considered. We get our suggestions from users adopting a particular application. So develop something great and when we find out about it, you will find your name in lights.
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.
Why do my image uploads always fail?
The image update methods require multipart form data. They do not accept a URL to an image not do they accept the raw image bytes. They instead require the data to be delivered in the form of a file upload filed as defined in RFC1867. The content-type attribute of the image field is checked for valid image type. If you are using PHP/CURL there is a known bug that has since been fixed in the CVS version of PHP. Most installations are not yet using this version and therefore fail during image upload.
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?
- 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.
- 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 email@example.com an email.
How do I get all replies to a particular status?
For now, there's not a great way to do this. We've heard the requests, though, and we'll be providing a solution for it before too long.
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:
When will Twitter support OAuth?
As of March 2009, OAuth has moved to a public beta. The implementation is stable and can be used for public sites. It is still in beta which means that our implementation's feature set is not yet complete, lacks UX polish, and is still subject to minor changes. Once all of the bugs are ironed out and it supports a better user expereience for the mobile and desktop use cases, OAuth will become the supported authentication system for Twitter, and HTTP Basic Auth will likely be deprecated after a lengthy grace period.
Can I have the Firehose or other Elevated Streaming API Access?
In early 2010 we will provide detail to our data availability announcement at the December 2009 LeWeb conference. In the meantime, some increased access is available on a case-by-case basis by emailing your application use case and a brief organization background to firstname.lastname@example.org. Nearly all use-cases can be satisfied with some creative application of a combination of the public streams on the Streaming API.
Are you going to make the REST API and the Search API work the same?
Yup! That's one of our major goals for 2010.