Most popular tweets in the search API
803 views
Skip to first unread message
Taylor Singletary
Mar 19, 2010, 10:37:18 AM3/19/10
to twitter-development-talk, twitter-api-announce
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 +0000",
"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":"<a href="http://www.atebits.com/" rel="nofollow">Tweetie</a>",
"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 +0000",
"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":"<a href="http://www.atebits.com/" rel="nofollow">Tweetie</a>",
"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 +0000",
"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":"<a href="http://www.atebits.com/" rel="nofollow">Tweetie</a>",
"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 +0000",
"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":"<a href="http://www.atebits.com/" rel="nofollow">Tweetie</a>",
"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 just pass the "result_type" parameter with a value of "recent" along with your request and they'll never be included.
In the case that you are displaying them, you may not want to not redisplay them every time your widget refreshes. Each result payload will include the since_id that you should use in subsequent requests to get the latest results. If you are using this since_id (which all compliant search widgets should) then the popular results will be excluded in subsequent requests. The specific since_id value to pass up to the query string is included in the payload. Here are examples in various formats:
json:
"refresh_url":"?since_id=9290798834&q=i"
atom:
<link type="application/atom+xml" href="http://search.twitter.com/search.atom?q=i&since_id=9290738270" rel="refresh"/>
rss:
<twitter:refresh_url>http://search.twitter.com/search.rss?q=i&since_id=9290775688</twitter:refresh_url>
--- Thanks ---
We're excited about this project and will send updates as we get closer to the release date. We're looking forward to your feedback and questions! Thank you.
Taylor Singletary (on behalf of the platform & search teams at Twitter)
Reply all
Reply to author
Forward
0 new messages