Recent API changes and new fields

[Matt Harris]

Hey everyone, 

This week we rolled out a couple of new data fields for the status and user objects. For a while it has been difficult for you to get the number of lists a user is listed in, or the number of times a Tweet has been retweeted. You were also finding it hard to know if the user had retweeted the status themselves or not. The feature requests you filed and the messages on the developer mailing list showed this is a pain point for many of you as it uses up many of your hourly API requests.

These fields are live now and many of you have already seen them in our API responses. We intended to tell you about these changes before they were live, and in the future for things like this we will, but this time around our system for doing that didn't work. The good news is we know what went wrong and have made the necessary improvements needed to ensure you are notified before the changes happen.

The recent changes which have been made affect the user and status objects. In both cases we have added fields:

To the user object:

---------------------------

listed_count

represents the number of public lists a user is listed in. This field is an integer. As this is a new field it is possible some users will not have a listed_count value yet.

follow_request_sent

representing whether the user you are authenticating as has requested to follow the user you are viewing. This will be false unless the friendship request is pending. The field is a boolean and will be true or false.

To the status object:

-----------------------------

retweet_count

represents the number of times a status has been retweeted using the Twitter retweet action. This field is an integer. There will not be a value for this field when the feature is turned off, or the Tweet was created before we added retweet_count support.

retweeted

represents whether the user you are authenticating as has retweeted this status or not. The field is a boolean and can be true or false. 

Changes to existing methods

------------------------------------------

users/show

When requesting data for suspended users the user/show used to return an HTTP 404 status code - it now returns HTTP 403.

This change is in response to number of users who were asking if there was a way to know if a user they were getting data for had been deleted or was instead suspended. The change means the API agrees with the twitter.com in that we confirm a user exists, but that you may not see their information because they are suspended.

If you call /users/show on a suspended user the API response will include the error message "User has been suspended."

Please remember we sometimes turn features off to maintain site stability. We recommend you always check a field exists before attempting to use it and be prepared for the value to be empty. This will help ensure your code stays stable if we have to turn features off. We'll also be adding this information to the main API documentation soon.

Best,

Matt Harris
Developer Advocate, Twitter
http://twitter.com/themattharris

[@IDisposable]

> listed_count
> represents the number of public lists a user is listed in. This field is an
> integer. As this is a new field it is possible some users will not have a
> listed_count value yet.

Very nice, thanks... I assume this will be correctly set when doing
the mass-lookup of users by screen name?

> To the status object:
> -----------------------------
> retweet_count
> represents the number of times a status has been retweeted using the Twitter
> retweet action. This field is an integer. There will not be a value for this
> field when the feature is turned off, or the Tweet was created before we
> added retweet_count support.

How accurate will this be in results returned from
search.twitter.com? Will it be in those tweets at all for the json or
atom feed?

> When requesting data for suspended users the user/show used to return an
> HTTP 404 status code - it now returns HTTP 403.

This is AWESOME! Thank you!!! How is this reflected when doing a
mass-lookup by screenname?

Thanks,
Marc

[arian]

Status.retweet_count!!!
this is perfect!!!
this is exactly what I need. it makes my life easier.

But, I'm testing it right now and I can't find a status where
"retweet_count" is not blank.

1. There will not be a value for this field when the feature is turned
off
-- how should I know if the feature is turned off or not?

2. the Tweet was created before we added retweet_count support.
-- when exactly this feature was enabled? I'm trying with fresh tweets
but they are all blank yet.

Arian

[Cameron Kaiser]

> Status.retweet_count!!!
> this is perfect!!!
> this is exactly what I need. it makes my life easier.
>
> But, I'm testing it right now and I can't find a status where
> "retweet_count" is not blank.

Neither can I. Is this turned on?

--
------------------------------------ personal: http://www.cameronkaiser.com/ --
Cameron Kaiser * Floodgap Systems * www.floodgap.com * cka...@floodgap.com
-- I'm in Pittsburgh. Why am I here? -- Harold Urey, Nobel laureate -----------

[Joe]

will we see this in both search and stream API?

[Matt Harris]

Hey everyone,

Thanks for the questions. I'll try and answer them all in this message.

1) are the counts turned on?
This weekend the counts were turned off and have remained off. This is
because of some bugs we found in the way the value was calculated.
I'll let you know when we have this resolved.

2) Will these fields show up in the Search and Streaming API?
The fields are already in the Streaming API but be aware the
'retweeted' field is not meaningful here. This is because the streamed
status knows nothing of the connected user.
The search API does not include this information.

3) How do I know if the feature is turned off?
Tweets will contain a retweeted_count if available. If the service is
not enabled newer Tweets will likely be missing their retweeted_count.
The safest thing to do is code to handle missing values. If they are
present use them, if they are not, treat them the same as when the
field didn't exist. This way your code works when the retweeted_count
is both enabled and disabled.

4) When was the feature turned on?
The service was rolled out the week beginning Aug 16th

Hope that answers your questions,
Matt

--

[Zac Bowling]

Is there a time line for the streaming API getting these changes?

Zac Bowling

[Matt Harris]

Hey Zac,

The Streaming API already has these fields included.

Matt

[arian]

Hi Matt

Zac Bowling > Is there a time line for the streaming API getting these
changes?

Information like retweet_count, followers_count and friends_count are
very volatile and change all the time.
would be nice receive this kind of notification when any of these
fields are changed.
but I guess you woudn't build something like this.

Arian

On 24 ago, 21:38, Matt Harris <thematthar...@twitter.com> wrote:
> Hey Zac,
>
> The Streaming API already has these fields included.
>
> Matt
>
>
>
> On Tue, Aug 24, 2010 at 9:38 AM, Zac Bowling <zbowl...@gmail.com> wrote:
> > Is there a time line for the streaming API getting these changes?
>
> > Zac Bowling
>

> > On Mon, Aug 23, 2010 at 11:40 PM, Matt Harris <thematthar...@twitter.com> wrote:
> >> Hey everyone,
>
> >> Thanks for the questions. I'll try and answer them all in this message.
>
> >> 1) are the counts turned on?
> >> This weekend the counts were turned off and have remained off. This is
> >> because of some bugs we found in the way the value was calculated.
> >> I'll let you know when we have this resolved.
>

> >> 2) Will thesefieldsshow up in the Search and Streaming API?
> >> Thefieldsare already in the Streaming API but be aware the

> >> 'retweeted' field is not meaningful here. This is because the streamed
> >> status knows nothing of the connected user.
> >> The search API does not include this information.
>
> >> 3) How do I know if the feature is turned off?
> >> Tweets will contain a retweeted_count if available. If the service is
> >> not enabled newer Tweets will likely be missing their retweeted_count.
> >> The safest thing to do is code to handle missing values. If they are
> >> present use them, if they are not, treat them the same as when the
> >> field didn't exist. This way your code works when the retweeted_count
> >> is both enabled and disabled.
>
> >> 4) When was the feature turned on?
> >> The service was rolled out the week beginning Aug 16th
>
> >> Hope that answers your questions,
> >> Matt
>
> >> On Sat, Aug 21, 2010 at 4:33 PM, Joe <j...@ajcomputers.com> wrote:
> >>> will we see this in both search and stream API?
>
> >>> On Aug 20, 6:45 pm, Matt Harris <thematthar...@twitter.com> wrote:
> >>>> Hey everyone,
>

> >>>> This week we rolled out a couple ofnewdatafieldsfor the status and user

> >>>> objects. For a while it has been difficult for you to get the number of
> >>>> lists a user is listed in, or the number of times a Tweet has been
> >>>> retweeted. You were also finding it hard to know if the user had retweeted
> >>>> the status themselves or not. The feature requests you filed and the
> >>>> messages on the developer mailing list showed this is a pain point for many
> >>>> of you as it uses up many of your hourly API requests.
>

> >>>> Thesefieldsare live now and many of you have already seen them in our API

> >>>> responses. We intended to tell you about these changes before they were
> >>>> live, and in the future for things like this we will, but this time around
> >>>> our system for doing that didn't work. The good news is we know what went
> >>>> wrong and have made the necessary improvements needed to ensure you are
> >>>> notified before the changes happen.
>
> >>>> The recent changes which have been made affect the user and status objects.
> >>>> In both cases we have addedfields:
>
> >>>> To the user object:
> >>>> ---------------------------
>
> >>>> listed_count
> >>>> represents the number of public lists a user is listed in. This field is an

> >>>> integer. As this is anewfield it is possible some users will not have a

[Mark McBride]

This is exactly what userstreams allows you to do.

   ---Mark

http://twitter.com/mccv

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

[Ryan W]

Has retweet_count been turned on yet? Is there a live example of a
call with it present in the response, and not null?

Also, when it's on, is it enabled wherever a tweet is returned.
Specifically, will it be in the list statuses:

http://api.twitter.com/1/%/lists/%/statuses.json

?