#newtwitter and the API

4177 views
Skip to first unread message

Matt Harris

unread,
Sep 22, 2010, 4:06:14 PM9/22/10
to twitter-deve...@googlegroups.com
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

EastSideDev

unread,
Sep 22, 2010, 5:22:04 PM9/22/10
to Twitter Development Talk
As app developers, do we need to re-register for the new #newtwitter?

Taylor Singletary

unread,
Sep 22, 2010, 5:25:33 PM9/22/10
to twitter-deve...@googlegroups.com
Hi EastSideDev,

#newtwitter is being rolled out gradually to all users; it's not really possible to predict when you'll receive it, though we're adding new users every day. You don't need to re-register your apps, your account, or anything else to be granted access. Some day, at some time, you'll log into Twitter and see a banner at the top of the screen informing you that you now have access.

Access tokens belonging to users who currently have #newtwitter have permission to access the API features that require #newtwitter. 

Taylor

On Wed, Sep 22, 2010 at 2:22 PM, EastSideDev <easts...@gmail.com> wrote:
As app developers, do we need to re-register for the new #newtwitter?

--
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

themattharris

unread,
Sep 22, 2010, 5:34:40 PM9/22/10
to Twitter Development Talk
No new registration is needed, #newtwitter is being rolled out
gradually and at random.
For the API, only the related_results method requires you to have
access to #newtwitter.

Hope that helps,
@themattharris

Dewald Pretorius

unread,
Sep 22, 2010, 5:53:35 PM9/22/10
to Twitter Development Talk
Is the URL format
http://twitter.com/themattharris
earmarked to be phased out at some point in the medium future?

In many places in my app the @username is linked to
http://twitter.com/username
and I will have to modify all those URLs to
http://twitter.com/#!/username
if the old format is going to disappear.

M. Edward (Ed) Borasky

unread,
Sep 22, 2010, 5:53:51 PM9/22/10
to twitter-deve...@googlegroups.com, Matt Harris
Thanks!! A somewhat philosophical question, with some practical
overtones. I've got a blog (self-hosted WordPress) and a LinkedIn
profile and, of course, a Twitter account. With #newtwitter, I'm
beginning to think I can ditch the blog and replace it with my Twitter
page - my "microblog", as it were.

So I'm wondering how much "customization" someone can do to their
Twitter page now, and how much we might be able to expect in the
future? For openers, when I look at a Twitter page in #newtwitter,
there's a huge blank space on the lower right. Is there any way I can
use that space, either static or dynamic, without violating the TOS or
causing strain on the servers? Is there some way we'd be able to get
the kind of analytics from our Twitter pages that we can get from a
self-hosted WordPress blog?

--
M. Edward (Ed) Borasky
http://borasky-research.net http://twitter.com/znmeb

"A mathematician is a device for turning coffee into theorems." - Paul Erdos


Quoting Matt Harris <themat...@twitter.com>:

Robert McGovern

unread,
Sep 22, 2010, 5:55:49 PM9/22/10
to Twitter Development Talk
Regarding:

On Sep 22, 10:06 pm, Matt Harris <thematthar...@twitter.com> wrote:
> 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.

I presume this doesn't mean that any actions they do on the website
will be counted against their available API requests?

Rob

Tom van der Woerdt

unread,
Sep 22, 2010, 6:05:04 PM9/22/10
to twitter-deve...@googlegroups.com, Twitter Development Talk
Which makes me wonder: does the API limit apply to the web version? ^^

Tom

Brian Medendorp

unread,
Sep 23, 2010, 8:51:46 AM9/23/10
to Twitter Development Talk
> 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.

Is there any chance that this could be included in the search API?

Damon Clinkscales

unread,
Sep 23, 2010, 12:55:15 PM9/23/10
to twitter-deve...@googlegroups.com
Brian,

Thanks for the info.

> 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.

What does "when enabled" mean?

I have a couple of tweets for which I am trying to find out the
absolute count of retweets. All I know is that the Twitter UI says
"100+ retweets".

But when I pull the status objects, <retweet_count> is blank. These
tweets are from 2 days ago.

Can someone point me to the best way to find out?

Thanks!
/damon

Matt Harris

unread,
Sep 23, 2010, 1:52:51 PM9/23/10
to twitter-deve...@googlegroups.com
Thanks for all the questions and feedback everyone. Hopefully my
comments below will answer your questions.

Robert/Tom: The API limit for #newtwitter applies the same as other
applications so the requests are deducted from the authenticated users
rate limit.
Ed: There are plans to allow more customisation than currently exists
on twitter.com. With the new design many users may want to update
their images to work with the new padding and width though. The space
in the lower right is empty at the moment, but like twitter before,
new features/enhancements may occupy or use it. Analytics wise there
are no plans to do something like this - if it was a project what kind
of things would you find useful?
Dewald: The default format of http://twitter.com/themattharris is not
being phased out. We just wanted to let you know the new format (with
/#!) is expected, and is something apps may find users giving them.
You don't need to update the links in your application unless you wish
to.
Brian: We intend to have entities support in results from the Search
API. At the moment they are not yet supported there.
Damon: the retweet and retweet_count fields are currently disabled.
Some issues were identified soon after they were released which we are
working through.

Best,
@themattharris

Yusuke

unread,
Dec 15, 2010, 1:15:36 AM12/15/10
to Matt Harris, twitter-deve...@googlegroups.com
Hi,

Is there any plan to make these new API methods available in the
official document?

Thanks,
Yusuke

On Sep 24, 2:52 am, Matt Harris <thematthar...@twitter.com> wrote:
> Thanks for all the questions and feedback everyone. Hopefully my
> comments below will answer your questions.
>
> Robert/Tom: The API limit for #newtwitter applies the same as other
> applications so the requests are deducted from the authenticated users
> rate limit.
> Ed: There are plans to allow more customisation than currently exists
> on twitter.com. With the new design many users may want to update
> their images to work with the new padding and width though. The space
> in the lower right is empty at the moment, but like twitter before,
> new features/enhancements may occupy or use it. Analytics wise there
> are no plans to do something like this - if it was a project what kind
> of things would you find useful?

> Dewald: The default format ofhttp://twitter.com/themattharrisis not

Taylor Singletary

unread,
Dec 15, 2010, 9:57:20 AM12/15/10
to twitter-deve...@googlegroups.com, Matt Harris
Hi Yusuke,

We'll probably graduate the majority of these APIs to the official documentation next month. A number of them are still in active iteration.

Thanks,
Taylor

Yusuke Yamamoto

unread,
Dec 15, 2010, 9:58:54 AM12/15/10
to twitter-deve...@googlegroups.com, Matt Harris
Got it.

Thanks!
-- 
Yusuke Yamamoto
yus...@mac.com

this email is: [x] bloggable/tweetable [ ] private
follow me on : http://twitter.com/yusukeyamamoto
subscribe me at : http://samuraism.jp/

Yusuke Yamamoto

unread,
Feb 22, 2011, 11:55:15 AM2/22/11
to twitter-deve...@googlegroups.com, Matt Harris
Hi,
Any estimation of the #newtwitter API doc availability?
-- 
Yusuke Yamamoto
yus...@mac.com

this email is: [x] bloggable/tweetable [ ] private
follow me on : http://twitter.com/yusukeyamamoto
subscribe me at : http://samuraism.jp/

Reply all
Reply to author
Forward
0 new messages