Home ›
API ›
Stories API

Stories API

The Stories API allows access to TweetMeme’s data about particular stories that we have collected from Twitter.

Methods

(optional) count: int how many results to return per page, in the range 1-100, default 10
(optional) category: string an optional category to filter results by, default none
(optional) media: string a filter of media type (news/video/image) with default of all
(optional) page: int the page of results you would like, in the range 1-100 with default 1

Returns: a list of stories with associated properties

title: string the title of the page
url: string the final URL of the page
media_type: string the media type of the content (news/image/video)
created_at: datetime the date and time of the first tweet posted containing this URL
url_count: int the number of times this link has been tweeted
comment_count: int the number of comments the story has on TweetMeme
retweet: string a tweet to send in order to retweet this story (Note: the TweetMeme attribution must remain in place if you use this API call – see the API guidelines) Currently deprecated – more information on how to get this coming soon.

Example Requests:

http://api.tweetmeme.com/stories/popular.xml
http://api.tweetmeme.com/stories/popular.xml?media=news
http://api.tweetmeme.com/stories/popular.xml?media=video&count=20
http://api.tweetmeme.com/stories/popular.xml?page=2

Example Output (in XML)

<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>success</status>
	<stories>
		<story>
			<url>http://online.wsj.com/article/SB10001424052970203803904574431151489408372.html</url>
			<media_type>news</media_type>
			<title>The End of the Email Era - WSJ.com</title>
			<created_at>2009-10-11 23:13:36</created_at>
			<url_count>745</url_count>
			<comment_count>0</comment_count>
			<alias>http://bit.ly/40GKxw</alias>
			<retweet>RT @tweetmeme The End of the Email Era - WSJ.com http://bit.ly/40GKxw</retweet>
		</story>
		...
	</stories>
</result>

Recent

Returns the most recent stories found by TweetMeme

URL: http://api.tweetmeme.com/stories/recent.format

Formats: xml, json, php

Parameters:

(optional) count: int how many results to return per page, in the range 1-100, default 10
(optional) category: string an optional category to filter results by, default none
(optional) media: string a filter of media type (news/video/image) with default of all
(optional) page: int the page of results you would like, in the range 1-100 with default 1

Returns: a list of the most recent stories discovered by TweetMeme

title: string the title of the page
url: string the final URL of the page
media_type: string the media type of the content (news/image/video)
created_at: datetime the date and time of the first tweet posted containing this URL
url_count: int the number of times this link has been tweeted
comment_count: int the number of comments the story has on TweetMeme
retweet: string a tweet to send in order to retweet this story (Note: the TweetMeme attribution must remain in place if you use this API call – see the API guidelines) Currently deprecated – more information on how to get this coming soon.

Example Requests:

http://api.tweetmeme.com/stories/recent.xml
http://api.tweetmeme.com/stories/recent.xml?media=news
http://api.tweetmeme.com/stories/recent.xml?media=video&count=20
http://api.tweetmeme.com/stories/recent.xml?page=2

Example Output (in XML)

<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>success</status>
	<stories>
		<story>
			<url>http://mashable.com/2009/10/11/the-fun-theory/</url>
			<media_type>news</media_type>
			<title>The Fun Theory: Volkswagen Masters the Viral Video</title>
			<created_at>2009-10-12T02:30:12+00:00</created_at>
			<url_count>973</url_count>
			<comment_count>3</comment_count>
			<alias>http://retwt.me/PLSR</alias>
			<retweet>RT @tweetmeme The Fun Theory: Volkswagen Masters the Viral Video http://retwt.me/PLSR</retweet>
		</story>
		...
	</stories>
</result>

Categories

Returns a list of categories down to the specified depth, optionally filtered by a parent category.

URL: http://api.tweetmeme.com/stories/categories.format

Formats: xml, json, php

Parameters:

(optional) filter: string a string to filter the categories by (default is empty string)
(optional) depth: int the depth of categories to return (range 1-10, default 1)

Returns: list of categories down to the specified depth, optionally filtered by filter

display: string the display name of the category
name: string the internal name of the category

Example Requests:

http://api.tweetmeme.com/stories/categories.xml
http://api.tweetmeme.com/stories/categories.xml?depth=2
http://api.tweetmeme.com/stories/categories.xml?filter=technology&depth=0

Example Output (in XML)

<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>success</status>
	<categories>
		<category>
			<display>Comedy</display>
			<name>comedy</name>
			<categories>
				<category>
					<display>Animals</display>
					<name>comedy.animals</name>
				</category>
				<category>
					<display>Fail</display>
					<name>comedy.fail</name>
				</category>
			</categories>
		</category>
	</categories>
</result>

Notes

The depth specifies the levels of children, relative to the filter, to return. By default, only the first level of children will be returned.
Specifying a depth of 0 will return only the category specified by the filter. If the filter is empty, a depth of 0 will return an error.
The filter must be in the format of the “name” parameter from the result. e.g. “technology.apple”, “comedy” and “sports.soccer” are all valid filters.

Tweets

Returns 10 tweets for the specified URL.

URL: http://api.tweetmeme.com/stories/tweets.format

Formats: xml, json, php

Parameters:

url: string the URL of the page you want tweets for
from_id: int the last Tweet UUID you have (it will return tweets after but not including this Tweets UUID)

Returns: list of a maximum of 10 tweets for the specified URL offset by the specified page.

user: a user object with data about the user who tweeted the story
- tweeter: string the Twitter username of the user
- Note: the rest of this User object is currently in development and fields may appear/disappear over the coming weeks. Please do not rely on data it provides.
tweet: string the tweet text
created_at: datetime the date and time the tweet was posted at
source: string the source of the tweet, excluding the usual <a> link from the Twitter API
id: string the Twitter ID of the tweet

Example Requests:

http://api.tweetmeme.com/v2/url/tweets.json?url=http://tweetmeme.com
http://api.tweetmeme.com/v2/url/tweets.json?url=http://tweetmeme.com&from_id=0a3d48003c7611dfba23000000000000

Example Output (in XML) Note: This example has been trimmed, there were actually 10 <tweet> elements in the response to this request.

<?xml version="1.0" encoding="UTF-8"?>
<result>
    <status>success</status>
    <tweets>
        <tweet>
            <id>4808464354</id>
            <uuid>0a3d48003c7611dfba23000000000000</uuid>
            <user>
            <tweeter>fabricemassin</tweeter>
            </user>
            <tweet>Deezer Raises $9.5 Million More For Free Music Search And Streaming Service http://bit.ly/2SgfQT by @robinwauters (via @TechCrunch)</tweet>
            <created_at>2009-10-12 13:31:43</created_at>
            <source>Tweetie</source>
        </tweet>
        ...
    </tweets>
</result>

Notes

The tweets are ordered in descending date order – that is, the first tweet will be the most recent.
As a real-time service, we only store tweets for any given URL for 7 days. Therefore, if you wish to maintain a list of all tweets for a particular URL, you will need to periodically query our API and store the results yourself. This does not affect the tweet count returned by the url_info Core API method, which always tracks the total tweets ever made against that URL.

(9 votes, average: 3.78 out of 5)

Search

Categories

Sign In

Stories API

Methods

Popular

Recent

Categories

Tweets

Related Articles

Search

Categories

Sign In

Stories API

Methods

Popular

Recent

Categories

Tweets