The contents of the FAQ
If you are starting with the API, please familiarize yourself with the API FAQ and know that it exists.
There are actually three APIs
The Twitter API currently consists of two discrete REST APIs and a Streaming API. Most application developers mix and match the APIs to produce their application. The separation of the REST and Search APIs is less than ideal and it is entirely due to history It is in our pipeline to ameliorate Twitter’s API by combining the Search and REST pieces as development cycles allow. The API Overview portion of the Getting Started series explains the history. The Streaming API provides low-latency high-volume access to Tweets.
There are limits to how many calls and changes you can make in a day
The API is entirely HTTP-based
Methods to retrieve data from the Twitter API require a
GET request. Methods that submit, change, or destroy data require a
DELETE request is also accepted for methods that destroy data. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct one. HTTP Response Codes are meaningful.
The API is a RESTful resource
With the exception of the Streaming API, the Twitter API attempts to conform to the design principles of Representational State Transfer (REST). Simply change the format extension a request to get results in the format of your choice. The documentation notes which formats are available for each method. The API presently supports the following data formats: XML, JSON, and the RSS and Atom syndication formats, with some methods only accepting a subset of these formats.
Parameters have certain expectations
Some API methods take optional or requisite parameters. Two things to keep in mind when making requests with parameters:
- Parameter values should be converted to UTF-8 and URL encoded.
pageparameter begins at 1, not 0.
There are two special parameters in the Twitter API:
callback: Used only when requesting JSON formatted responses, this parameter wraps your response in a callback method of your choice. For example, appending
callback=myFancyFunctionto your request will result in a response body of:
myFancyFunction(...). Callbacks may only contain alphanumeric characters and underscores; any invalid characters will be stripped.
suppress_response_codes: If this parameter is present, all responses will be returned with a
Where noted, some API methods will return different results based on HTTP headers sent by the client. Where the same behavior can be controlled by both a parameter and an HTTP header, the parameter will take precedence.
There are pagination limits
Rest API Limit
Clients may access a theoretical maximum of 3,200 statuses via the
count parameters for the user_timeline REST API methods. Other timeline methods have a theoretical maximum of 800 statuses. Requests for more than the limit will result in a reply with a status code of 200 and an empty result in the format requested. Twitter still maintains a database of all the tweets sent by a user. However, to ensure performance of the site, this artificial limit is temporarily in place.
Search API Limit
Clients may request up to 1,500 statuses via the
rpp parameters for the search method. The response to a request exceeding this limit will be a status code of 403 and the error message
page parameter out of range in the format requested. This artificial limit is in place to ensure the performance of the search system. We also restrict the size of the search index by placing a date limit on the updates we allow you to search. This limit varies depending on the number of Tweets being created and the relevance of the results.
There are Twitter API libraries for almost any language
The community has created numerous Twitter API libraries. If you know of others we haven’t got let us know.