Hi Developers!
The Search team is working on a beta project that returns the most popular
tweets for a query, rather than only the most recent tweets. This is a beta
project, but an important first step to surface the most popular tweets for
users searching Twitter.
You can expect many improvements as we tune and tweak our algorithms, but we
want to give everyone a heads up so we can go over the implications for
those consuming the search API.
--- New attribute in the payload ---
First of all there will be a new attribute in search result payloads. Since
some tweets are popular for a given query while others are simply the most
recent results that match the query, we are adding a metadata section to
specify the type of result that a given result represents.
So for a popular tweet the result_type in the metadata section will have
the value popular.
Example of a result with a popular tweet:
{
results:
[
{
profile_image_url:
http://a1.twimg.com/profile_images/668144840/Elizabeth_Web_normal.jpg;,
created_at:Mon,15 Feb 2010 19:55:18 +,
from_user:Elizabeth,
to_user_id:null,
text:It's the Griswold family trip to Joshua Tree Park!
@rsarver @Devon @Jess @noradio @kevinweil,
id:9153622261,
from_user_id:106309,
geo:null,
iso_language_code:en,
source:lt;a href=quot;http://www.atebits.com/quot;
rel=quot;nofollowquot;gt;Tweetielt;/agt;,
metadata:
{
result_type: popular
}
}
/* etc ... */
}
Results that are not popular and represent simply recent query matches will
have the result_type in the metadata section with a value of recent.
Example of a recent result:
{
results:
[
{
profile_image_url:
http://a3.twimg.com/profile_images/641350353/TimCheekFinger_normal.jpg;,
created_at:Mon, 15 Feb 2010 23:42:45 +,
from_user:timhaines,
to_user_id:97776,
text:@noradio Nice spot.,
id:9160218997,
from_user_id:159881,
to_user:noradio,
geo:null,
iso_language_code:it,
source:lt;a href=quot;http://www.atebits.com/quot;
rel=quot;nofollowquot;gt;Tweetielt;/agt;,
metadata:
{
result_type: recent
}
},
/* etc ... */
}
--- Results with popular tweets aren't ordered chronologically ---
Until the popular tweet feature all search results have been sorted
chronologically, most recent results at the top. If a search query has any
popular results, those will be returned at the top, even if they are older
than the other results.
Example of a non-chronologically ordered set of results including popular
results:
{
results:
[
{
profile_image_url:
http://a1.twimg.com/profile_images/668144840/Elizabeth_Web_normal.jpg;,
created_at:Mon, 15 Feb 2010 19:55:18 +,
from_user:Elizabeth,
to_user_id:null,
text:It's the Griswold family trip to Joshua Tree Park!
@rsarver @Devon @Jess @noradio @kevinweil,
id:9153622261,
from_user_id:106309,
geo:null,
iso_language_code:en,
source:lt;a href=quot;http://www.atebits.com/quot;
rel=quot;nofollowquot;gt;Tweetielt;/agt;,
metadata:
{
result_type: popular
}
},
{
profile_image_url:
http://a3.twimg.com/profile_images/641350353/TimCheekFinger_normal.jpg;,
created_at:Mon, 15 Feb 2010 23:42:45 +,
from_user:timhaines,
to_user_id:97776,
text:@noradio Nice spot.,
id:9160218997,
from_user_id:159881,
to_user:noradio,
geo:null,
iso_language_code:it,
source:lt;a href=quot;http://www.atebits.com/quot;
rel=quot;nofollowquot;gt;Tweetielt;/agt;,
metadata:
{
result_type: recent
}
}
/* etc ... */
}
--- Only getting popular results ---
If you *only* care about popular results for a given query term, you can
provide a result_type parameter with the value popular. Then only
popular results, if there are any, will be returned. By default, if
result_type isn't provided, all result types will be returned.
--- Never getting popular results ---
Conversely, if you *do not* want to receive popular results, provide a
result_type parameter with the value recent. Then only recent results
will be returned.
--- Dealing with popular tweets for refreshing search widgets ---
For those using client side search widgets, by default the first request
might include popular results. If you want to display these you can use the
result_type attribute to visually differentiate them. If you don't want to
display these you can always
