Hey Everyone, Last week we announced #newtwitter, the new twitter.com built on top of the Twitter API. For the Platform team in particular, this was an important event. With #newtwitter using the API all users will become API consumers, providing valuable feedback about issues they encounter, helping us isolate and fix problems that are found.
When creating #newtwitter the value of this was clear. A heightened level of visibility & communication with our engineers enabled us to reproduce and fix many of the API bugs you’ve encountered and reported to us. #newtwitter makes it easier for us to concretely develop new API features, giving other teams at Twitter an agile environment to experiment with new ideas. All of this combined resulted in many deployed fixes to the API -- and some new features! Many of these have already been announced and are already being used by many of you. Listed below are the various changes and updates that have been made to the API. URL format ---------- The first important change is that URLs now have a new format. This new format is part of the Javascript routing system used by #newtwitter for page management. This means our website URLs now contain a #! like this: http://twitter.com/#!/themattharris instead of: http://twitter.com/themattharris The two formats work on both versions of twitter.com so you don’t need #newtwitter to use them. There is more information about the #! URL format in Google’s article: Making AJAX Applications Crawlable http://code.google.com/web/ajaxcrawling/docs/getting-started.html New methods -------------------- A number of new methods have been added to the API. Some of them can be used now, while others only work if you have access to #newtwitter. Some of these methods may be candidates for feature-specific rate limiting in the future so be aware of the headers we return to you. Like all REST API methods, the new ones live on http://api.twitter.com. If you are not using this host please update your code. The non-versioned API endpoints do not support the new parameters or recent enhancements. GET /1/account/totals.{format} Requires authentication. Returns the current count of friends, followers, updates (statuses) and favorites of the authenticating user. Example: twurl /1/account/totals.json GET /1/account/settings.{format} Requires authentication. Returns the current trend, geo and sleep time information for the authenticating user. Example: twurl /1/account/settings.json GET /1/users/suggestions/:category_slug/members.{format} Does not require authentication. Access the users in a given category of the Twitter suggested user list and return their most recent status if they are not a protected user. Example: twurl /1/users/suggestions/technology/members.json GET /1/direct_messages/show/:id.{format} Requires authentication. Returns a single direct message, specified by an id parameter. Like the /1/direct_messages.{format} request, this method will include the user objects of the sender and recipient. Example: twurl /1/direct_messages/show/12345678.json GET /1/statuses/retweeted_to_user.{format} Does not require authentication, unless the user is protected. Returns the 20 most recent retweets posted by users the specified user follows. The user is specified using the user_id or screen_name parameters. This method is identical to statuses/retweeted_to_me except you can choose the user to view. Example: twurl /1/statuses/retweeted_to_user.json?screen_name=twitterapi GET /1/statuses/retweeted_by_user.{format} Does not require authentication, unless the user is protected. Returns the 20 most recent retweets posted by the specified user. The user is specified using the user_id or screen_name parameters. This method is identical to statuses/retweeted_by_me except you can choose the user to view. Example: twurl /1/statuses/retweeted_by_user.json?screen_name=twitterapi GET /1/friendships/lookup.{format} Requires authentication. Returns the relationship of the authenticating user to the comma separated list of up to 100 screen_names or user_ids provided. Values for connections can be: following, following_requested, followed_by, none. Example: twurl /1/friendships/lookup.json?screen_name=twitter,twitterapi,twittereng POST /1/friendships/update.{format} Requires authentication. Allows you enable or disable retweets and device notifications from the specified user. Valid values for enable are 't','1' or 'true'. All other values are assumed to be false. Example: twurl /1/friendships/update.json -d "screen_name=twitterapi" -d "device=true" -d "retweets=false" GET /1/lists/all.{format} Requires authentication unless requesting for another user. Returns all lists the authenticating or specified user subscribes to, including their own. The user is specified using the user_id or screen_name parameters. If no user is given, the authenticating user is used. Example: twurl /1/lists/all.json?screen_name=twitterapi GET /1/related_results/show/:id.{format} Requires authentication. If available, returns an array of replies and mentions related to the specified Tweet. There is no guarantee there will be any replies or mentions in the response. This method is only available to users who have access to #newtwitter. Example: twurl /1/related_results/show/12345678.json Updated methods ------------------------- Some methods have been given new parameters to control their output or better focus their results. You may already be familiar with some of these parameters from previous announcements. exclude_replies Timeline methods such as /1/statuses/home_timeline, /1/statuses/user_timeline, /1/statuses/friends_timeline now support an exclude_replies parameter. This parameter will prevent replies from appearing in the returned timeline. Using exclude_replies with the count parameter will mean you will receive up-to count tweets - this is because the count parameter retrieves that many tweets before filtering out retweets and replies. contributor_details Timeline methods such as /1/statuses/home_timeline, /1/statuses/user_timeline, /1/statuses/friends_timeline now support a contributor_details parameter. This parameter enhances the contributors element of the status response to include the screen_name of the contributor. By default only the user_id of the contributor is included. include_rts Timeline methods such as /1/statuses/user_timeline and /1/statuses/friends_timeline support an include_rts parameter. When set to either true, t or 1,the timeline will contain native retweets (if they exist) in addition to the standard stream of tweets. The output format of retweeted tweets is identical to the representation you see in home_timeline. Note: If you're using the trim_user parameter in conjunction with include_rts, the retweets will still contain a full user object. include_entities Methods which return statuses support an include_entities parameter. When set to either true, t or 1, each tweet will include a node called "entities,". This node offers a variety of metadata about the tweet in a discreet structure, including: user_mentions, urls, and hashtags. Entities is currently opt-in but will become defaulted to on. trim_user Methods which return statuses support a trim_user parameter. When set to either true, t or 1, each tweet returned in a timeline will include a user object including only the status authors numerical ID. Omit this parameter to receive the complete user object. use The method /1/account/update_profile_background_image now supports the use parameter. This parameter allows you to specify whether to use the upload profile background or not. Valid values for use are 't','1' or 'true'. All other values are assumed to be false. This is an often requested feature for developers specializing in profile customization. lang The method /1/suggestions.{format} and /1/suggestions/:category_slug.{format} now support languages other than English. Currently support lang values are en, fr, de, es, it include_my_retweet Methods which return statuses support an include_my_retweet parameter. When set to either true, t or 1, and if the status is a retweet of the current user, a “current_user_retweet” node will be added. When present this node will contain an ID datapoint set to the ID of the current users retweet. This ID is the status ID to destroy if you want to undo a retweet. Additional data points ------------------------------- Some of the data objects we return have had new fields added to them. show_all_inline_media The user object now includes show_all_inline_media to indicate if the user has chosen to have inline media displayed or not. listed_count The user object now includes a listed_count which returns the number of public lists the user is a member of/listed in. follow_request_sent The user object now includes a follow_request_sent field. This field is true if the authenticating user has requested to follow the user whose object is being displayed. retweet_count The status object now includes a retweet_count field. When enabled this field will indicate the number of times a Tweet has been retweeted using the Twitter retweet function. retweeted The status object now includes a retweeted field. When enabled this field indicates whether the current Tweet has been retweeted by the authenticating user or not. Instead of using this data point consider using the “include_my_retweet” parameter on timelines instead. Summary -------------- Please remember some of these methods are available only to users who have access to #newtwitter. New parameters and methods may be disabled at anytime and you should code defensively in case they are missing from responses, or return non 200 error codes. We hope you find these new API methods, parameters and data points to be useful. Best @themattharris -- Twitter developer documentation and resources: http://dev.twitter.com/doc API updates via Twitter: http://twitter.com/twitterapi Issues/Enhancements Tracker: http://code.google.com/p/twitter-api/issues/list Change your membership to this group: http://groups.google.com/group/twitter-development-talk?hl=en