API Documentation

The Retwt.me 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.

You can request data in the following 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.

Rate Limiting

Clients are allowed 5000 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 Retwt.me API, please send a request to tweetmemedev and we will get back to you.

Error Messages

When the Retwt.me 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>

Methods

Shorten

Takes the given long URL and shortens it to a Retwt.me Short URL.

URL: http://api.retwt.me/shorten.format

Formats: xml, json, php

Parameters:

  • longUrl: string (the long URL to shorten)

Returns: a shortened URL in the requested format:

  • http://api.retwt.me/shorten?longUrl=http://tweetmeme.com
  • http://api.retwt.me/shorten.json?longUrl=http://tweetmeme.com

Example Output (in XML)

<?xml version="1.0" encoding="UTF-8"?>
<result>
	<shortUrl>http://retwt.me/1</shortUrl>
	<longUrl>http://tweetmeme.com</longUrl>
	<status>success</status>
</result>

Expand

Returns the long URL to which a Retwt.me Short URL points to

URL: http://api.retwt.me/expand.format

Formats: xml, json, php

Parameters:

  • shortUrl: string (the Retwt.me Short URL to expand)

Returns: a expanded URL in the requested format:

  • http://api.retwt.me/expand?shortUrl=http://retwt.me/1
  • http://api.retwt.me/expand.json?shortUrl=http://retwt.me/1

Example Output (in XML)

<?xml version="1.0" encoding="UTF-8"?>
<result>
	<shortUrl>http://retwt.me/1</shortUrl>
	<longUrl>http://tweetmeme.com</longUrl>
	<status>success</status>
</result>

Stats

Returns clicks and referrer data about the Short URL. All totals are totals over the entire lifetime of the Short URL.

URL: http://api.retwt.me/stats.format

Formats: xml, json, php

Parameters:

  • shortUrl: string (the Retwt.me Short URL to get stats for)

Returns: click and referrer data about the URL:

  • http://api.retwt.me/stats?shortUrl=http://retwt.me/1
  • http://api.retwt.me/stats.json?shortUrl=http://retwt.me/1

Example Output (in XML)

<?xml version="1.0" encoding="UTF-8"?>
<result>
	<status>success</status>
	<shortUrl>http://retwt5.me/1</shortUrl>
	<clicks>120</clicks>
	<referrers>
		<referrer>
			<domain>tweetmeme.com</domain>
			<clicks>60</clicks>
			<paths>
				<path>
					<path>/story</path>
					<clicks>30</clicks>
				</path>
				<path>
					<path/>
					<clicks>30</clicks>
				</path>
			</paths>
		</referrer>
	</referrers>
</result>
© 2010 favorit Ltd