Twitfave REST API

Introduction

Twitfave exposes some of the information it gathers from twitter and also adds some extra scoring information that it creates. This page documents the API to gain access to that information.

Wherever possible, the API attempts to be "RESTful". At the moment, only a JSON output is available. Should there be enough demand for other formats, I may consider adding them.

All feature requests, bugs found, etc should be reported via get satisfaction. If you wish to be kept up to date with changes to twitfave, including API changes, you should follow @twitfave on twitter

Usage Limits

Currently, there are no usage limits on the service. However, if in the future API usage causes excess load on our servers, we may employ them. Should this be required, the service will return a 503 Service Unavailable error, with a Retry-After header indicating the number of seconds you should wait before attempting to ask questions of the API again. Your client should be equipped to deal with this.

Timeliness

Because twitfave spiders the twitter API in order to find information about tweets that have been favourited, it often takes a long time to find out about a particular favourite. You shouldn't consider twitfave to provide timely information on all users, as it prioritises the spidering of high scoring individuals and users who follow the twitfave user. Sometimes, this means that a low scoring individuals favourites may not be seen for weeks after the event.

Private Users

Twitfave makes no attempt to store users tweets if the user is marked as private on twitter. If you attempt to query a private user, a user without tweets or a 404 may be returned.

JSON and callbacks

In order to use the data from these JSON calls within javascript from external sites, a callback parameter has been added. Adding ?callback=function_name will wrap the data in a callback function. You can see some examples of using services like this on the Yahoo development network here.

Methods

getting information about a single tweet

In order to get information about a single tweet, you should use the URL pattern listed above. It should be noted that this is the url used to access a single tweet in twitfave itself, just with the extension .json added.

You should expect output similar to the following (which has had whitespace added for clarity):

  [
      {
          "pk": 5941564,
           "model": "faves.tweet",
           "fields": 
          {
              "language": "en",
               "author": 33423,
               "text": "On the one hand,
               vegetarianism is healthy and humane. On the other hand,
               bacon.",
               "created_at": "2007-01-01 00:00:00",
               "source": "<a href=\"http://iconfactory.com/software/twitterrific\">twitterrific</a>",
               "in_reply_to_status_id": null,
               "score": "296.5080",
               "in_reply_to_user_id": null,
               "faved_by": 
              [
                  3796,
                   4902,
                   10343,
                   12098,
                   53993,
                   607653,
                   749863,
                   803479,
                   861201,
                   2487031,
                   2788841,
                   5761072,
                   7404012,
                   8446602,
                   8453632
              ],
               "hotness": "296.5080",
               "found_at": "2008-11-23 09:24:49"
          }
      }
  ]

This has had several fields added from the original twitter api data.

pk

This is the original twitter id field (and represents the id of the tweet)

language

Language code of the tweet. This is not 100% accurate, as it's hard to guess the language of a small piece of text. It's good enough for the purposes of twitfave, but may or may not be for you.

score

This is the internal score that twitfave uses to determine how highly the tweet ranks on classic and user screens. This increases by number and power of faved_by users, and does not decrease over time.

faved_by

This is a list of twitter user id numbers that have favourited this particular tweet.

hotness

This is the internal score that twitter uses to determine how "hot" a tweet is. This score decreases over time (but increases by number and power of faved_by users).

found_at

This is the date and time at which twitfave first found that tweet via spidering.

getting all the tweets of a user which have been favourited

In order to get information about the tweets of a user which have been favourited by other users, use the URL pattern listed above. It should be noted that this is the url used to access a users favourited tweets in twitfave itself, just with the extension .json added.

You should expect similar output to the single tweet method, except multiple tweets in the array. For some users, this file will be quite large - you should cache the result and call this method infrequently for each user. Should this prove popular, additions to this method are planned which will enable you to receive differences only or to only receive the file if there are changes (this will use If-Modified-Since headers, should you wish to plan for it.)

Possible future expansions

If there is reasonable interest in the API or using the API in ways that aren't currently possible, I'm open to adding and expanding methods. My current ideas are:

1. Expanding the JSON methods to include a callback function (JSONP) so that the JSON methods can be used directly in javascript widgets.
2. Expanding the user method so that it's possible to get the differences between one date and another.

If you'd like either of these to happen, or have other ideas, please use get satisfaction. If you wish to be kept up to date with changes to twitfave, including API changes, you should follow @twitfave on twitter.