Delicious

Question 1

What are Delicious Feeds?

Answer

For most pages within Delicious, there are associated read-only data feeds for bookmarks and other information displayed in a browser. These feeds come in several formats — including RSS and JSON — and offer windows onto what's going on at Delicious that you can use in news readers, blogs, or your own third-party applications.

Answer

RSS is a format used by many news sites and blogs to publish content on the web. Using RSS to publish content enables news readers and personalized start pages to pull new stuff all into one place. Applications that understand RSS can do the footwork and provide a one-stop shop to help readers keep on top of things without needing to surf all over the web in person.

Accordingly, Delicious offers links to companion RSS feeds on most Profile pages to help you keep track of links from other users. Look for the "rss" link just under a user's profile picture.

In addition, many web browsers — such as Firefox, Safari, and Internet Explorer — automatically detect RSS feeds associated with pages and offer convenient ways to subscribe.

Answer

JSON, which stands for JavaScript Object Notation, is a lightweight data-interchange format easily used in browser-based mashups, blog badges, and other scenarios including server-side and desktop applications.

You can use feeds at Delicious in JSON format to fetch, remix, and mashup a variety of data for use in your own custom applications and browser-based hacks.

Answer

Since feeds at Delicious see quite a bit of high-volume use, it's not practical to offer immediately fresh results at all times. In particular, RSS feeds may not be updated more than twice an hour, and JSON feeds are likely to show a degree of staleness at times as well. Polling feeds more often will not yield better data, and may result in HTTP 503 Unavailable errors indicating either that your application has been blocked or the servers are otherwise temporarily throttling your requests.

Answer

Feeds at Delicious all share the following base URL prefix:

http://feeds.delicious.com/v2/{format}/

The placeholder {format} specifies the output format for the feed, which currently includes the values rss and json.

All feed formats accept the following query-string parameters:

?count={1..100} = Limit the results to the given number, between 1 and 100 (default 15)

For RSS format feeds, Delicious performs user-agent detection and, for certain news readers, includes enhanced HTML content in items while minimizing the amount of machine-readable metadata. This feature can be intentionally switched on or disabled with the following URL query-string parameters:

?plain = Disable enhanced item HTML content.
?fancy = Enable enhanced item HTML content.

To help enable JSON-based mashups, there are a few URL query-string parameters to tweak the JSON output:

?callback={js call} = Allows the inclusion of a wrapper function call around the JSON data. The value is filtered by a whitelist consisting of these characters: 0-9 a-z A-Z ()[],._-+=/|\~?!#$^*: '"

The following feed URL patterns use these placeholders:

{format} = replaced with either "rss" or "json"
{username} = replaced with a user's login name on delicious
{tag[+tag+...+tag]} = replaced with a tag or an intersection of tags.
{url md5} = is intended for the MD5 hash of a URL
{key} = a security key for the feed, which can be found via the page associated with the feed (eg. inbox, network or bookmarks). Allows visibilty to otherwise private data.

Answer

Recent bookmarks:

http://feeds.delicious.com/v2/{format}/recent

Recent bookmarks by tag:

http://feeds.delicious.com/v2/{format}/tag/{tag[+tag+...+tag]}

Bookmarks for a specific user:

http://feeds.delicious.com/v2/{format}/{username}

Private bookmarks for a specific user:

http://feeds.delicious.com/v2/{format}/{username}?private={key}

Bookmarks for a specific user by tag(s):

http://feeds.delicious.com/v2/{format}/{username}/{tag[+tag+...+tag]}

Private bookmarks for a specific user by tag(s):

http://feeds.delicious.com/v2/{format}/{username}/{tag[+tag+...+tag]}?private={key}

Public summary information about a user:

http://feeds.delicious.com/v2/{format}/userinfo/{username}

A list of all public tags for a user:

http://feeds.delicious.com/v2/{format}/tags/{username}

A list of related public tags for a user tag comination:

http://feeds.delicious.com/v2/{format}/tags/{username}/{tag[+tag+...+tag]}

Bookmarks from a user's subscriptions:

http://feeds.delicious.com/v2/{format}/subscriptions/{username}

Private feed for a user's inbox bookmarks from others:

http://feeds.delicious.com/v2/{format}/inbox/{username}?private={key}

Bookmarks from members of a user's network:

http://feeds.delicious.com/v2/{format}/network/{username}

Bookmarks from members of a user's network by tag:

http://feeds.delicious.com/v2/{format}/network/{username}/{tag[+tag+...+tag]}

A list of a user's network members:

http://feeds.delicious.com/v2/{format}/networkmembers/{username}

Recent bookmarks for a URL:

http://feeds.delicious.com/v2/{format}/url/{url md5}

Summary information about a URL:

http://feeds.delicious.com/v2/json/urlinfo/{url md5}

Question 2

What is RSS?

Question 3

What is JSON?

Question 4

How fresh are the feeds?

Question 5

What API Feeds are available at Delicious?

Question 6

Finally, what are URL patterns for feeds at Delicious?

Question 7

https://api.del.icio.us/v1/posts/update - Check to see when a user last posted an item.

Answer

Returns the last update time for the user, as well as the number of new items in the user's inbox since it was last visited.

Use this before calling posts/all to see if the data has changed since the last fetch.

example response

<update time="2005-03-28T17:25:52Z" inboxnew="0" />

Question 8

https://api.del.icio.us/v1/posts/add? - add a new bookmark

Answer

Add a post to Delicious.

arguments

&url={URL}
(required) the url of the item.

&description={...}
(required) the description of the item.
    
&extended={...}
(optional) notes for the item.

&tags={...}
(optional) tags for the item (comma delimited).

&dt={CCYY-MM-DDThh:mm:ssZ}
(optional) datestamp of the item (format "CCYY-MM-DDThh:mm:ssZ").
Requires a LITERAL "T" and "Z" like in ISO8601 at 
http://www.cl.cam.ac.uk/~mgk25/iso-time.html for example: "1984-09-01T14:21:31Z"

&replace=no
(optional) don't replace post if given url has already been posted.
    
&shared=no
(optional) make the item private

example response

If the post was successful:

<result code="done" />

If the post failed:

<result code="something went wrong" />

Question 9

https://api.del.icio.us/v1/posts/delete? - delete an existing bookmark

Answer

Delete a post from Delicious

arguments

&url={URL}
(required) the url of the item.

example response

<result code="done" />

Question 10

https://api.del.icio.us/v1/posts/get? - get bookmark for a single date, or fetch specific items

Answer

Returns one or more posts on a single day matching the arguments. If no date or url is given, most recent date will be used.

arguments

&tag={TAG}+{TAG}+...+{TAG}
(optional) Filter by this tag.

&dt={CCYY-MM-DDThh:mm:ssZ}
(optional) Filter by this date, defaults to the most recent date on which bookmarks were saved.

&url={URL}
(optional) Fetch a bookmark for this URL, regardless of date.  Note: Be sure to URL-encode 
the argument value.

&hashes={MD5}+{MD5}+...+{MD5}
(optional) Fetch multiple bookmarks by one or more URL MD5s regardless of date, separated by 
URL-encoded spaces (ie. '+').

&meta=yes
(optional) Include change detection signatures on each item in a 'meta' attribute.  Clients 
wishing to maintain a synchronized local store of bookmarks should retain the value of this 
attribute - its value will change when any significant field of the bookmark changes.

example

$ curl https://user:passwd@api.del.icio.us/v1/posts/get?tag=webdev&meta=yes
<?xml version="1.0" encoding="UTF-8"?>
<posts dt="2005-11-28" tag="webdev" user="user">
  <post href="http://www.howtocreate.co.uk/tutorials/texterise.php?dom=1"
      description="JavaScript DOM reference"
      extended="dom reference"
      hash="c0238dc0c44f07daedd9a1fd9bbdeebd"
      meta="92959a96fd69146c5fe7cbde6e5720f2"
      others="55" tag="dom javascript webdev" time="2005-11-28T05:26:09Z" />
</posts>

$ curl https://user:passwd@api.del.icio.us/v1/posts/get?url=http%3A%2F%2Fwww.yahoo.com%2F
<?xml version="1.0" encoding="UTF-8"?>
<posts user="user" dt="2007-12-11" tag="">
  <post href="http://www.yahoo.com/"
      hash="2f9704c729e7ed3b41647b7d0ad649fe"
      description="Yahoo!"
      extended="My favorite site ever"
      tag="yahoo web search" time="2007-12-11T00:00:07Z" others="433" />
</posts>

Question 11

https://api.del.icio.us/v1/posts/recent? - fetch recent bookmarks

Answer

Returns a list of the most recent posts, filtered by argument. Maximum 100.

arguments

&tag={TAG}
(optional) Filter by this tag.
&count={1..100}
(optional) Number of items to retrieve (Default:15, Maximum:100).

example response

$ curl https://user:passwd@api.del.icio.us/v1/posts/recent
<posts tag="" user="user">
  <post href="http://www.weather.com/" description="weather.com"
  hash="6cfedbe75f413c56b6ce79e6fa102aba" tag="weather reference"
  time="2005-11-29T20:30:47Z" />
    ...
  <post href="http://www.nytimes.com/"
  description="The New York Times - Breaking News, World News & Multimedia"
  extended="requires login" hash="ca1e6357399774951eed4628d69eb84b"
  tag="news media" time="2005-11-29T20:30:05Z" />
</posts>

Question 12

https://api.del.icio.us/v1/posts/dates?- list dates on which bookmarks were posted

Answer

Returns a list of dates with the number of posts at each date.

arguments

&tag={TAG}
(optional) Filter by this tag

example

<dates tag="" user="user">
  <date count="5" date="2005-11-29" />
  <date count="15" date="2005-11-28" />
  <date count="2" date="2005-11-26" />
  <date count="2" date="2005-11-25" />
  <date count="7" date="2005-11-23" />
  <date count="20" date="2005-11-22" />
  <date count="16" date="2005-11-21" />
  <date count="4" date="2005-11-19" />
</dates>

Question 13

https://api.del.icio.us/v1/posts/all? - fetch all bookmarks by date or index range

Answer

Returns all posts. Please use sparingly. Call the update function to see if you need to fetch this at all.

arguments

&tag={TAG}
(optional) Filter by this tag.

&start={xx}
(optional) Start returning posts this many results into the set.

 &results={xx}
(optional) Return this many results.

&fromdt={CCYY-MM-DDThh:mm:ssZ}
(optional) Filter for posts on this date or later

&todt={CCYY-MM-DDThh:mm:ssZ}
(optional) Filter for posts on this date or earlier

&meta=yes
(optional) Include change detection signatures on each item in a 
'meta' attribute. Clients wishing to maintain a synchronized local 
store of bookmarks should retain the value of this attribute - its 
value will change when any significant field of the bookmark changes.

example

$ curl https://user:passwd@api.del.icio.us/v1/posts/all
<posts tag="" user="user">
  <post href="http://www.weather.com/" description="weather.com"
  hash="6cfedbe75f413c56b6ce79e6fa102aba" tag="weather reference"
  time="2005-11-29T20:30:47Z" />
    ...
  <post href="http://www.nytimes.com/"
  description="The New York Times - Breaking News, World News & Multimedia"
  extended="requires login" hash="ca1e6357399774951eed4628d69eb84b"
  tag="news media" time="2005-11-29T20:30:05Z" />
</posts>

Question 14

https://api.del.icio.us/v1/posts/all?hashes - fetch a change detection manifest of all items

Answer

Returns a change manifest of all posts. Call the update function to see if you need to fetch this at all.

This method is intended to provide information on changed bookmarks without the necessity of a complete download of all post data.

Each post element returned offers a url attribute containing an URL MD5, with an associated meta attribute containing the current change detection signature for that bookmark.

example

$ curl https://user:passwd@api.del.icio.us/v1/posts/all?hashes
<?xml version="1.0" encoding="UTF-8"?>
<posts>
    <post meta="d4b6adc08932f237ec1bfe8021629f4b" url="b14d529834a601567b14f76192e39e96"/>
    <post meta="77e1ec24a43bae61fb67586649683d30" url="2f9704c729e7ed3b41647b7d0ad649fe"/>
    <post meta="9bbc254e930cd5f719c35d97a5180852" url="96bdf631592930d5f540bb962dced0f2"/>
    <post meta="72d92edd9588c3aab5ea8a56d2d79328" url="c5f7ac7a3ec5f014723738c15891a896"/>
    ...
    <post meta="84aea258c8835a2adf226d0d4d439fb7" url="7e2c9d4c49569409d9b455cdf8189a77"/>
</posts>

Question 15

https://api.del.icio.us/v1/posts/suggest - fetch popular, recommended and network tags for a specific url

Answer

Returns a list of popular tags, recommended tags and network tags for a user.

This method is intended to provide suggestions for tagging a particular url.

arguments

&url={URL}
(required) URL for which you'd like suggestions

example

$ curl https://user:passwd@api.del.icio.us/v1/posts/suggest?url=http://yahoo.com
<?xml version="1.0" encoding="UTF-8"?>
<suggest>
  <popular>yahoo!</popular>
  <popular>yahoo</popular>
  <popular>web</popular>
  <popular>tools</popular>
  <popular>searchengines</popular>
  <recommended>yahoo!</recommended>
  <recommended>yahoo</recommended>
  <recommended>web</recommended>
  <recommended>tools</recommended>
  <recommended>search</recommended>
  <recommended>reference</recommended>
  <recommended>portal</recommended>
  <recommended>news</recommended>
  <recommended>music</recommended>
  <recommended>internet</recommended>
  <recommended>home</recommended>
  <recommended>games</recommended>
  <recommended>entertainment</recommended>
  <recommended>email</recommended>
  <network>for:Bernard</network>
  <network>for:britta</network>
  <network>for:deusx</network>
  <network>for:joshua</network>
  <network>for:stlhood</network>
  <network>for:theteam</network>
</suggest>

Question 16

https://api.del.icio.us/v1/tags/get - fetch all tags

Answer

Returns a list of tags and number of times used by a user.

example response

<tags>
 <tag count="1" tag="activedesktop" />
 <tag count="1" tag="business" />
 <tag count="3" tag="radio" />
 <tag count="5" tag="xml" />
 <tag count="1" tag="xp" />
 <tag count="1" tag="xpi" />
</tags>

Question 17

https://api.del.icio.us/v1/tags/delete? - delete a tag from all posts

Answer

Delete an existing tag.

arguments

&tag={TAG}
(required) Tag to delete

example response

<result>done</result>

Question 18

https://api.del.icio.us/v1/tags/rename? - rename a tag on all posts

Answer

Rename an existing tag with a new tag name.

arguments

&old={TAG}
(required) Tag to rename.
    
&new={TAG}
(required) New tag name.

example response

<result>done</result>

Question 19

https://api.del.icio.us/v1/tags/bundles/all? - fetch tag bundles

Answer

Retrieve all of a user's bundles.

arguments

&bundle={NAME}
(optional) Fetch just the named bundle.

example response

<bundles>
  <bundle name="music" tags="ipod mp3 music" />
</bundles>

Question 20

https://api.del.icio.us/v1/tags/bundles/set? - assign a set of tags to a bundle

Answer

Assign a set of tags to a single bundle, wipes away previous settings for bundle.

arguments

&bundle={NAME}
(required) Name of the bundle

&tags={TAG}+{TAG}+...+{TAG}
(required) List of tags, space-separated.

example response

If the bundle was created:

<result>ok</result>

If the bundle was not created:

<result>you must supply a bundle name and at least one tag</result>

Question 21

https://api.del.icio.us/v1/tags/bundles/delete? - delete a tag bundle

Answer

Delete a bundle.

arguments

&bundle={NAME}
(required) Name of the bundle

example response

<result>done</result>

Delicious

Developers Resources

RSS & JSON Feeds

Recent bookmarks:

Recent bookmarks by tag:

Bookmarks for a specific user:

Private bookmarks for a specific user:

Bookmarks for a specific user by tag(s):

Private bookmarks for a specific user by tag(s):

Public summary information about a user:

A list of all public tags for a user:

A list of related public tags for a user tag comination:

Bookmarks from a user's subscriptions:

Private feed for a user's inbox bookmarks from others:

Bookmarks from members of a user's network:

Bookmarks from members of a user's network by tag:

A list of a user's network members:

Recent bookmarks for a URL:

Summary information about a URL:

APIs

Authentication

Keep in Mind

Methods

Update

example response

Posts

arguments

example response

arguments

example response

arguments

example

arguments

example response

arguments

example

arguments

example

example

arguments

example

Tags

example response

arguments

example response

arguments

example response

Tag Bundles

arguments

example response

arguments

example response

arguments

example response