• Home ›
  • ›
  • API ›
  • API Documentation

API Documentation

The Tweetmeme API attempts to conform to the design principles of Representational State Transfer (REST). You’ll find that you can simply change the file extension on most any request to get results in the format of your choice. Tweetmeme presently supports the following data formats: XML, JSON, and PHP

Parameters

Some API methods take optional or requisite parameters. Where applicable, we’ve documented those parameters. Remember to convert to UTF-8 and URL encode parameters that take complex strings. Please note that the page parameter begins at 1, not 0.

Rate Limiting

Clients are allowed 250 requests per 60 minute time period, starting from their first request. Whenever any API call is made, the headers `X-RateLimit-Limit` and `X-RateLimit-Remaining` will be set with the total limit and the number of API calls remaining in the current 60 minute period. If you exceed the rate limit for a particular 60 minute period, all API calls will fail, responding with a 403 Forbidden status code and an error message detailing that you have exceeded your limit, in the format requested. If you are developing an application that requires more frequent requests to the TweetMeme API, please fill in our Whitelist form and we will get back to you.

Error Messages

When the Tweetmeme API returns error messages, it does so in your requested format. For example, an error from an XML method might look like this:

<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>failure</status>
	<reason>unknown method</reason>
</result>

Return Formats

The API is flexible in the data formats that it offers. You can switch between them by changing the extension on the API call, for example:

http://api.tweetmeme.com/url_info.js?url=http://tweetmeme.com – JS format (see below)

http://api.tweetmeme.com/url_info.xml?url=http://tweetmeme.com – XML format (see below)

XML

Returns data in compliant XML format. For example:

<result>
	<status>success</status>
	<story>
		<title>Tweetmeme - Hottest Stories on Twitter</title>
		<url>http://www.tweetmeme.com/</url>
		<media_type>news</media_type>
		<created_at>2009-02-19 03:06:36</created_at>
		<url_count>3141</url_count>
		<tm_link>http://tweetmeme.com/story/26054116</tm_link>
		<comment_count>115</comment_count>
		<excerpt>RT @tweetmeme Tweetmeme - Hottest Stories on Twitter http://bit.ly/151Dl1</excerpt>
	</story>
</result>

PHP

Returns data in PHP object serialisation. For example:

a:2:{s:6:"status";s:7:"success";s:5:"story";a:8:{s:5:"title";s:38:"Tweetmeme - Hottest Stories on Twitter";s:3:"url";s:25:"http://www.tweetmeme.com/";s:10:"media_type";s:4:"news";s:10:"created_at";s:19:"2009-02-19 13:06:36";s:9:"url_count";i:3141;s:7:"tm_link";s:35:"http://tweetmeme.com/story/26054116";s:13:"comment_count";i:115;s:7:"excerpt";s:73:"RT @tweetmeme Tweetmeme - Hottest Stories on Twitter http://bit.ly/151Dl1";}}

Javascript

There are 3 ways of obtaining JSON data out of the API.

First of all, use the json extension to get just the raw json data. For example:

{"status":"success","story":{"title":"Tweetmeme - Hottest Stories on Twitter","url":"http:\/\/www.tweetmeme.com\/","media_type":"news","created_at":"2009-02-19 13:06:36","url_count":3141,"tm_link":"http:\/\/tweetmeme.com\/story\/26054116","comment_count":115,"excerpt":"RT @tweetmeme Tweetmeme - Hottest Stories on Twitter http:\/\/bit.ly\/151Dl1"}}

Or you can use the js extension, which returns the same JSON data but wrapped in a callback parameter “tweetmemedata”, like this:

tweetmemedata({"status":"success","story":{"title":"Tweetmeme - Hottest Stories on Twitter","url":"http:\/\/www.tweetmeme.com\/","media_type":"news","created_at":"2009-02-19 13:06:36","url_count":3141,"tm_link":"http:\/\/tweetmeme.com\/story\/26054116","comment_count":115,"excerpt":"RT @tweetmeme Tweetmeme - Hottest Stories on Twitter http:\/\/bit.ly\/151Dl1"}});

Finally, if you want to specify your own callback parameter, you can do so by using the jsonc extension, and the callback query parameter, like this:

http://api.tweetmeme.com/url_info.jsonc?url=http://tweetmeme.com&callback=myCallback

myCallback({"status":"success","story":{"title":"Tweetmeme - Hottest Stories on Twitter","url":"http:\/\/www.tweetmeme.com\/","media_type":"news","created_at":"2009-02-19 13:06:36","url_count":3141,"tm_link":"http:\/\/tweetmeme.com\/story\/26054116","comment_count":115,"excerpt":"RT @tweetmeme Tweetmeme - Hottest Stories on Twitter http:\/\/bit.ly\/151Dl1"}});

This is particularly useful for making cross-domain requests for data from the client side.

Value Formats

The API returns a number of formats of data, some of which need clarification.

  • Timestamps are returned in the format yyyy-mm-dd hh:mm:ss in the GMT timezone

The API

We have split the API up into 4 sections which correspond to particular features of TweetMeme. Click the links below to view the methods, parameters and expected responses for API calls in that feature set.

We also have a list of libraries you can download to access the API. Check those out here.

1 Star2 Stars3 Stars4 Stars5 Stars (59 votes, average: 4.10 out of 5)