is the granddaddy of social bookmarking sites; in fact, it’s the site that kicked off the whole folksonomic craze. Its web site is at

The main objects of importance in are bookmarks, that is, URLs. You can associate tags with a given URL. You can look at an individual’s collection of URLs and the tags they use. Let’s look again at the URL structures by browsing through the site and noting the corresponding URLs.

You can look at the public bookmarks for a specific user (for example, for rdhyee) by using this:

You can see all the bookmarks tagged NYTimes by rdhyee by using this:

You can see all the URLs that people have tagged with NYTimes by using this:

And you can see just the popular ones by using this:

Here are today’s popular items:

Or here are just the fresh popular ones:

Now, correlating a URL to a page is a bit trickier. Consider the following URL:

You can reference this from here:

How do you get 53113b15b14c90292a02c24b55c316e5 from TheEcstasyOfInfluence.html? Answer—it’s an md5 hash. In Python the following yields 53113b15b14c90292a02c24b55c316e5:"").hexdigest().

Note that the following does work:

It redirects to this location:

Using the API

From the documentation for the API ( you can learn the following:

  • All API calls must be sent over HTTPS.

  • All calls require ­HTTP-­Auth—that means there are no API keys per se, but all API calls are tied to a specific user account.

  • You need to watch for the 503 HTTP error (which would mean that your calls are being throttled and that you need to slow down the rate of your calls).


 This implies you can work on your own references but not on others unless they give you their credentials. All API calls to are made in the context of a specific user. There are no unauthenticated calls as there are on Flickr.

There are four major sections of the API:[225]

Update: Check to see when a user last posted an item.

Tags: Get a list of tags, and rename them.

Posts: Get a list of posts, add, and delete.

Bundles: Get bundles, create, and delete.

In the following sections, I’ll give you a flavor of the capabilities of the API, but I won’t comprehensively document it.


You can find the documentation for the update method here:

The update method tells you the last time a user updated his posts.

Let’s look at three ways to work through various methods listed in the API. The first is to use a web browser, while the second and third use curl. Let’s use the update method as an example:

  • With a web browser, go to the following location, and when prompted, enter your username and password:

  • With curl, you would run the following where USER and PASSWORD are your username and password:

    curl -u USER:PASSWORD

  • Finally, you can embed the username and password into the URL:

    curl "https://{user}:{password}"


curl "https://{user}:{password}"

In any of these cases, if your username and password are correct, you should get a response like the following:

               <?xml version='1.0' standalone='yes'?>
               <update time="2007-04-29T22:49:55Z" />

 For the following examples, we will use the second method only.


To get the complete list of tags used by a user and the number of times a given tag is used, use this:


To rename the tag FEDORA to fedora, use this:

curl -u USER:PASSWORD ""


The posts method has several submethods: get, recent, all, dates, and delete.[226]

The get Submethod

You can use the get submethod with the optional parameters tag, dt (for the date in ?CCYY-MM-DDThh: mm:ssZ format), and url to return posts matching the arguments:

For example, to get posts with the tag mashup, use this:


You can use this submethod to figure out the number of times an article has been posted. Consider the following scenario. Say you’ve posted the following URL to

and want to track the number of times it has been posted to You do so through this:

                  curl -u USER:PASSWORDÂ

which returns the following:

                  <?xml version="1.0" standalone="yes"?>
                  <posts dt="2007-04-26" tag="" user="rdhyee">
                    <post href="" 
                          description="ALA | Changing Roles of Academic and Research Libraries" 
                          hash="fa5be4b4401acf147ff6c8634b55cdda" others="49" 
                          tag="library2.0 libraries academic future" time="2007-04-26T19:45:56Z"/>

The others attribute in the post tag gives 49, which means that 49 users have added the URL to their collection of bookmarks.

If I don’t have the URL in the library, it returns this:

                  <?xml version='1.0' standalone='yes'?>
                  <posts dt="" tag="" user="rdhyee">

You need to add a URL to your library to inquire about a given URL in the API. Another way to calculate the number of users who have a given URL in their collection of bookmarks is to note the number of rdf:item elements in the RSS feed for the URL. As I describe in a moment, you can access the RSS feed for a given URL here:{url}

For example:


The major advantages of this method are that you don’t need to authenticate yourself to access the RSS feed and that you don’t need to have the URL in your own set of bookmarks.

The recent Submethod

The recent submethod returns a list of the user’s recent posts (up to 100), filtered by the optional arguments tag and count:

For example, the following returns the last five posts:


The all Submethod

The all submethod returns all your posts. You are advised to use this call sparingly (since it can generate a lot of data) and use the update function to see whether you need to do this call at all. You can filter by tag, such as in the following call (to get all posts with the tag architecture):


The add Submethod

You can use add to add posts to It has two required parameters:

  • &url (required) is the URL of the item.

  • &description (required) is the description of the item.

The rest of its parameters are optional:

  • &extended (optional) is notes for the item.

  • &tags (optional) is tags for the item (space delimited).

  • &dt (optional) is a date stamp of the item (with the format CCYY-MM-DDThh:mm:ssZ). It requires a literal T and Z as in ISO8601 at This is an example: 1984-09-01T14:21:31Z.

  • &replace=no (optional) doesn’t replace post if the given URL has already been posted.

  • &shared=no (optional) makes the item private.

Let’s set the description to be ALA | Changing Roles of Academic and Research Libraries and the tags to library 2.0 academic ACRL technology:

                  curl -u USER:PASSWORD "Â

This command returns this:

                  <?xml version='1.0' standalone='yes'?>
                  <result code="done" />
The dates Submethod

The dates submethod returns a list of dates, along with the number of posts for each date. You can optionally filter the search with a tag.

For instance, the following:


returns something like this:

                  <?xml version='1.0' standalone='yes'?>
                  <dates tag="mashup" user="rdhyee">
                    <date count="1" date="2007-09-20" />
                    <date count="1" date="2007-05-28" />
The delete Submethod

To delete a post with a given URL, issue the following GET:

                  curl -u USER:PASSWORD "Â

If the action is successful, then the result will be as follows:

                  <?xml version='1.0' standalone='yes'?>
                  <result code="done" />


When using, you may quickly accumulate many tags. Bundles allow you to group tags into organizational sets, which you can manipulate through the API. I’ll now illustrate how to use the API to control bundles through some examples.

The following request retrieves all the bundles for a user:


To create a bundle called Google to group the tags GoogleMaps and GoogleEarth, you can issue the following command:

               curl -u USER:PASSWORD "Â

You can delete the Google bundle with this:

               curl -u USER:PASSWORD "Â


In addition to the API, you can get RSS 1.0 feeds from

Don’t overlook them in your mashup work. Currently, the API returns information about the bookmarks of the authenticating user only. The RSS feeds, on the other hand, give you public information about bookmarks and how they are used by all users. Accessing RSS feeds does not require any authentication. However, you should observe the admonition to not access any given RSS feed more than once every 30 minutes.

The "hotlist" is at:

The most recent postings (that have at least two posters) is here:

Popular posts are here:

You can get recent postings by a user here:{user}

The RSS feed for a given tag is here:{tag}

For example, to get the RSS feed for the tag mashup, use this:

You can get a feed for posts that are tagged with both mashup and computer using this:

You can a feed for a specific tag and user using this:{user}/{tag}

For example:

Finally, you can track the history of postings for a given URL here:{url}

For example:


You can track this feed also here:

noting that fa5be4b4401acf147ff6c8634b55cdda is the md5 hash of

Several RSS feeds are not in the official documentation. Posting for a user’s subscription is available here:{user}

A feed of a user’s network (which has private information) is accessible here:{user}?private={private-key}

where the private-key is discoverable through the user interface for the authenticated user. Similarly, a feed for the “links for me” feature is here:{user}?private={private-key}

In addition to these RSS feeds, you can get some feeds in JSON format, which is convenient for JavaScript programming:

There are JSON analogs to the RSS feeds to get a user’s list of posts and list of tags and details about the posting history for a given URL. Moreover, there are JSON feeds that present information about a user’s social network that’s not available in the RSS feeds:

  • A listing of the names of people in a user’s network at{user}. That is, the list of people being tracked by the user.

  • A user’s fans at{user}. That is, the list of people tracking the user.

With these JSON feeds, you can visualize the graph of social networks in such as done by the tools here:

Third-Party Tools for

You can find a useful reference for what others have done with the API here:

Of the various tools, I find useful these three useful:

  • The official Firefox ­add-­on for (, which enables you to access your bookmarks and tags from a browser sidebar.

  • MySQLicious (, a PHP library for copying your bookmarks to a MySQL database. You download the code and follow the instructions. What you end up with is a MySQL database containing all the data for your bookmarks. The documentation says PHP 4—but it works for PHP 5 in my experience.

  • (, a utility to check your links and prune your bookmarks.

Third-Party API Kits

Here are some of the ­third-­party API kits listed at

To give you a sense of how PHPDelicious works, the following is the code to crawl through your bookmarks and tag each bookmark with the hostname of the URL (for example, Once you have such tags, you can look at all of your bookmarks from a specific domain.

            # a file storing DELICIOUS_USER and DELICIOUS_PASSWORD
            $del_obj = new PhpDelicious(DELICIOUS_USER, DELICIOUS_PASSWORD);
            # get all your bookmarks (and check for errors in the request)
            #$aPosts = $del_obj->GetAllPosts();
            if (!$aPosts = $del_obj->GetAllPosts()){
              echo $del_obj->LastError(), $del_obj->LastErrorString();
            # go through them and extract the hostname.
            # set a limit for the number of links the program does -- for debugging
            $maxcount = 5;
            $count = 0;
            $hosts = array();
            foreach ($aPosts as $post) {
              $count += 1;
              if ($count > $maxcount) {
              $url = $post['url'];
              $tags = $post['tags'];
              $url_parts = parse_url($url);
              $host = $url_parts['host'];
              # make a new tag
              $host_tag = "host:" . $host;
              echo $url, " ", $host_tag, "\n";
              # add the post with the new tag
              # parameters of a post
              $sUrl = $post['url'];
              $aTags = $post['tags'];
              # add host_tag to it
              $aTags[] = $host_tag;
              # track hosts that we are seeing
              if (isset($hosts[$host_tag])) {
                $hosts[$host_tag] += 1;
              } else {
                $hosts[$host_tag] = 1;
              $sDescription = $post['desc'];
              $sNotes = $post['notes'];
              $sDate = $post['updated'];
              $bReplace = true;
              echo $sUrl, $sDescription, " ", $sNotes, " ", $sDate, " ", $bReplace;
              print_r (array_unique($aTags));
              print "\n";
              if ($del_obj->AddPost($sUrl, $sDescription, $sNotes, array_unique($aTags), $sDate, 
            $bReplace)) {
                print "added $sUrl successfully\n";
              } else {
                print "problem in adding $sUrl\n";

To give you a flavor for Pydelicious, the following is a code snippet to delete all bookmarks with a certain tag (in this example, FlickrFavorite):

            USER = '[USER]'
            PASSWORD = '[PASSWORD]'
            import pydelicious
            pyd = pydelicious.apiNew(USER,PASSWORD)
            posts = pyd.posts_all(tag='FlickrFavorite')
            for post in posts['posts']:
                print post['href'], "\n"