List Stories

 

  1. List Stories
    1. Example Request
    2. Example Responses
      1. XML
      2. JSON
      3. PHP
    3. Endpoints
    4. Arguments

 

Fetches a list of stories from Digg.

 

Example Request

 

Retrieve three most recent stories from the Apple topic:

 

http://services.digg.com/stories/topic/apple?count=3&appkey=http%3A%2F%2Fexample.com%2fapplication

 

Example Responses

 

XML

 

<?xml version="1.0" encoding="utf-8" ?>
<stories timestamp="1196894147" min_date="1194302130" total="2636" offset="0" count="3">
 <story id="4368401" link="http://maxsangalli.altervista.org/?p=45" submit_date="1196891534" diggs="1" comments="0" status="upcoming" media="news" href="http://digg.com/linux_unix/Jukebox_con_Linux">
  <title>Jukebox con Linux</title>
  <description>Jukebox with Linux</description>
  <user name="ilsanga" icon="http://digg.com/img/udl.png" registered="1196891377" profileviews="0" />
  <topic name="Linux/Unix" short_name="linux_unix" />
  <container name="Technology" short_name="technology" />
  <thumbnail originalwidth="390" originalheight="387" contentType="image/jpeg" src="http://digg.com/linux_unix/Jukebox_con_Linux/t.jpg" width="80" height="80" />
 </story>
 <story id="4367880" link="http://www.itsyourip.com/ip-tools/arping-ping-using-address-resolution-protocolarp/" submit_date="1196888736" diggs="2" comments="0" status="upcoming" media="news" href="http://digg.com/linux_unix/ARPing_Ping_using_Address_Resolution_Protocol_ARP">
  <title>ARPing - Ping using Address Resolution Protocol(ARP)</title>
  <description>ARPing is an utility that can be used to ping using Address Resolution Protocol (ARP) requests instead of using Internet Control Message Protocol (ICMP) as used in standard Ping utility. ARPing can be used for Duplicate Address Detection (DAD)</description>
  <user name="rbkumaran" icon="http://digg.com/users/rbkumaran/l.png" registered="1151050300" profileviews="42" />
  <topic name="Linux/Unix" short_name="linux_unix" />
  <container name="Technology" short_name="technology" />
 </story>
 <story id="4367579" link="http://linuxdevices.com/news/NS9372729455.html" submit_date="1196887377" diggs="5" comments="0" status="upcoming" media="news" href="http://digg.com/linux_unix/EMF_changes_tune_hails_embedded_Linux">
  <title>EMF changes tune, hails embedded Linux </title>
  <description>Embedded Market Forecasters has issued a report claiming that embedded Linux is as dependable as other real time operating systems (RTOSs). The independently funded report appears to recant EMF's controversial Microsoft-funded report in 2003 that claimed that embedded Windows OSes were far faster and cheaper than embedded Linux. ...</description>
  <user name="gadgeek" icon="http://digg.com/img/udl.png" registered="1131035306" profileviews="1717" />
  <topic name="Linux/Unix" short_name="linux_unix" />
  <container name="Technology" short_name="technology" />
  <thumbnail originalwidth="125" originalheight="76" contentType="image/gif" src="http://digg.com/linux_unix/EMF_changes_tune_hails_embedded_Linux/t.gif" width="80" height="80" />
 </story>
</stories>

 

JSON

 

{
    "timestamp" : 1196894234,
    "min_date" : 1194302220,
    "total" : "2636",
    "offset" : 0,
    "stories" : [
            {
                "id" : "4368401",
                "link" : "http://maxsangalli.altervista.org/?p=45",
                "submit_date" : 1196891534,
                "diggs" : 1,
                "comments" : 0,
                "title" : "Jukebox con Linux",
                "description" : "Jukebox with Linux",
                "status" : "upcoming",
                "media" : "news",
                "user" : {
                            "name" : "ilsanga",
                            "icon" : "http://digg.com/img/udl.png",
                            "registered" : 1196891377,
                            "profileviews" : 0
                         },
                            "topic" : {
                                        "name" : "Linux/Unix",
                                        "short_name" : "linux_unix"
                                      },
                            "container" : {
                                            "name" : "Technology",
                                            "short_name" : "technology"
                                          },
                            "thumbnail" : {
                                            "originalwidth" : 390,
                                            "originalheight" : 387,
                                            "contentType" : "image/jpeg",
                                            "src" : "http://digg.com/linux_unix/Jukebox_con_Linux/t.jpg",
                                            "width" : 80,
                                            "height" : 80
                                          },
                            "href" : "http://digg.com/linux_unix/Jukebox_con_Linux"
             },
             {
                    "id" : "4367880",
                    "link" : "http://www.itsyourip.com/ip-tools/arping-ping-using-address-resolution-protocolarp/",
                    "submit_date" : 1196888736,
                    "diggs" : 2,
                    "comments" : 0,
                    "title" : "ARPing - Ping using Address Resolution Protocol(ARP)",
                    "description" : "ARPing is an utility that can be used to ping using Address Resolution Protocol (ARP) requests instead of using Internet Control Message Protocol (ICMP) as used in standard Ping utility. ARPing can be used for Duplicate Address Detection (DAD)",
                    "status" : "upcoming",
                    "media" : "news",
                    "user" : {
                                "name" : "rbkumaran",
                                "icon" : "http://digg.com/users/rbkumaran/l.png",
                                "registered" : 1151050300,
                                "profileviews" : 42
                              },
                    "topic" : {
                                "name" : "Linux/Unix",
                                "short_name" : "linux_unix"
                              },
                    "container" : {
                                    "name" : "Technology",
                                    "short_name" : "technology"
                                  },
                    "href" : "http://digg.com/linux_unix/ARPing_Ping_using_Address_Resolution_Protocol_ARP"
                },
                {
                    "id" : "4367579",
                    "link" : "http://linuxdevices.com/news/NS9372729455.html",
                    "submit_date" : 1196887377,
                    "diggs" : 5,
                    "comments" : 0,
                    "title" : "EMF changes tune, hails embedded Linux ",
                    "description" : "Embedded Market Forecasters has issued a report claiming that embedded Linux is as dependable as other real time operating systems (RTOSs). The independently funded report appears to recant EMF's controversial Microsoft-funded report in 2003 that claimed that embedded Windows OSes were far faster and cheaper than embedded Linux. ...",
                    "status" : "upcoming",
                    "media" : "news",
                    "user" : {
                                "name" : "gadgeek",
                                "icon" : "http://digg.com/img/udl.png",
                                "registered" : 1131035306,
                                "profileviews" : 1717
                              },
                    "topic" : {
                                "name" : "Linux/Unix",
                                "short_name" : "linux_unix"
                              },
                    "container" : {
                                    "name" : "Technology",
                                    "short_name" : "technology"
                                   },
                    "thumbnail" : {
                                    "originalwidth" : 125,
                                    "originalheight" : 76,
                                    "contentType" : "image/gif",
                                    "src" : "http://digg.com/linux_unix/EMF_changes_tune_hails_embedded_Linux/t.gif",
                                    "width" : 80,
                                    "height" : 80
                                   },
                    "href" : "http://digg.com/linux_unix/EMF_changes_tune_hails_embedded_Linux"
                    }
            ],
    "count":3
}

 

PHP

 

O:14:"DiggAPIStories":6:{s:9:"timestamp";i:1196894225;s:8:"min_date";i:1194302220;s:5:"total";s:4:"2636";s:6:"offset";i:0;s:7:"stories";a:3:{i:0;O:12:"DiggAPIStory":14:{s:2:"id";s:7:"4368401";s:4:"link";s:39:"http://maxsangalli.altervista.org/?p=45";s:11:"submit_date";i:1196891534;s:5:"diggs";i:1;s:8:"comments";i:0;s:5:"title";s:17:"Jukebox con Linux";s:11:"description";s:18:"Jukebox with Linux";s:6:"status";s:8:"upcoming";s:5:"media";s:4:"news";s:4:"user";O:11:"DiggAPIUser":4:{s:4:"name";s:7:"ilsanga";s:4:"icon";s:27:"http://digg.com/img/udl.png";s:10:"registered";i:1196891377;s:12:"profileviews";i:0;}s:5:"topic";O:12:"DiggAPITopic":2:{s:4:"name";s:10:"Linux/Unix";s:10:"short_name";s:10:"linux_unix";}s:9:"container";O:16:"DiggAPIContainer":2:{s:4:"name";s:10:"Technology";s:10:"short_name";s:10:"technology";}s:9:"thumbnail";O:16:"DiggAPIThumbnail":6:{s:13:"originalwidth";i:390;s:14:"originalheight";i:387;s:11:"contentType";s:10:"image/jpeg";s:3:"src";s:50:"http://digg.com/linux_unix/Jukebox_con_Linux/t.jpg";s:5:"width";i:80;s:6:"height";i:80;}s:4:"href";s:44:"http://digg.com/linux_unix/Jukebox_con_Linux";}i:1;O:12:"DiggAPIStory":13:{s:2:"id";s:7:"4367880";s:4:"link";s:83:"http://www.itsyourip.com/ip-tools/arping-ping-using-address-resolution-protocolarp/";s:11:"submit_date";i:1196888736;s:5:"diggs";i:2;s:8:"comments";i:0;s:5:"title";s:52:"ARPing - Ping using Address Resolution Protocol(ARP)";s:11:"description";s:243:"ARPing is an utility that can be used to ping using Address Resolution Protocol (ARP) requests instead of using Internet Control Message Protocol (ICMP) as used in standard Ping utility. ARPing can be used for Duplicate Address Detection (DAD)";s:6:"status";s:8:"upcoming";s:5:"media";s:4:"news";s:4:"user";O:11:"DiggAPIUser":4:{s:4:"name";s:9:"rbkumaran";s:4:"icon";s:37:"http://digg.com/users/rbkumaran/l.png";s:10:"registered";i:1151050300;s:12:"profileviews";i:42;}s:5:"topic";O:12:"DiggAPITopic":2:{s:4:"name";s:10:"Linux/Unix";s:10:"short_name";s:10:"linux_unix";}s:9:"container";O:16:"DiggAPIContainer":2:{s:4:"name";s:10:"Technology";s:10:"short_name";s:10:"technology";}s:4:"href";s:76:"http://digg.com/linux_unix/ARPing_Ping_using_Address_Resolution_Protocol_ARP";}i:2;O:12:"DiggAPIStory":14:{s:2:"id";s:7:"4367579";s:4:"link";s:46:"http://linuxdevices.com/news/NS9372729455.html";s:11:"submit_date";i:1196887377;s:5:"diggs";i:5;s:8:"comments";i:0;s:5:"title";s:39:"EMF changes tune, hails embedded Linux ";s:11:"description";s:334:"Embedded Market Forecasters has issued a report claiming that embedded Linux is as dependable as other real time operating systems (RTOSs). The independently funded report appears to recant EMF's controversial Microsoft-funded report in 2003 that claimed that embedded Windows OSes were far faster and cheaper than embedded Linux. ...";s:6:"status";s:8:"upcoming";s:5:"media";s:4:"news";s:4:"user";O:11:"DiggAPIUser":4:{s:4:"name";s:7:"gadgeek";s:4:"icon";s:27:"http://digg.com/img/udl.png";s:10:"registered";i:1131035306;s:12:"profileviews";i:1717;}s:5:"topic";O:12:"DiggAPITopic":2:{s:4:"name";s:10:"Linux/Unix";s:10:"short_name";s:10:"linux_unix";}s:9:"container";O:16:"DiggAPIContainer":2:{s:4:"name";s:10:"Technology";s:10:"short_name";s:10:"technology";}s:9:"thumbnail";O:16:"DiggAPIThumbnail":6:{s:13:"originalwidth";i:125;s:14:"originalheight";i:76;s:11:"contentType";s:9:"image/gif";s:3:"src";s:70:"http://digg.com/linux_unix/EMF_changes_tune_hails_embedded_Linux/t.gif";s:5:"width";i:80;s:6:"height";i:80;}s:4:"href";s:64:"http://digg.com/linux_unix/EMF_changes_tune_hails_embedded_Linux";}}s:5:"count";i:3;}

 

Endpoints

 

GET /stories
All stories.
GET /stories/popular
Popular stories.
GET /stories/upcoming
Upcoming stories.
GET /stories/top
Top stories.
GET /stories/hot
Hot stories.
GET /stories/container/{container name}
All stories from a given container.
404 Not Found if the container does not exist.
GET /stories/container/{container name}/popular
Popular stories from a given container.
404 Not Found if the container does not exist.
GET /stories/container/{container name}/upcoming
Upcoming stories from a given container.
404 Not Found if the container does not exist.
GET /stories/container/{container name}/top
Top stories from a given container.
404 Not Found if the container does not exist.
GET /stories/container/{container name}/hot
Hot stories from a given container.
404 Not Found if the container does not exist.
GET /stories/topic/{topic name}
All stories from a given topic.
404 Not Found if the topic does not exist.
GET /stories/topic/{topic name}/popular
Popular stories from a given topic.
404 Not Found if the topic does not exist.
GET /stories/topic/{topic name}/upcoming
Upcoming stories from a given topic.
404 Not Found if the topic does not exist.
GET /stories/topic/{topic name}/top
Top stories from a given topic.
404 Not Found if the topic does not exist.
GET /stories/topic/{topic name}/hot
Hot stories from a given topic.
404 Not Found if the topic does not exist.
GET /story/{story id}
Identified story.
404 Not Found for non-existent story.
GET /stories/{comma-separated list of story ids}
A list of stories with the given ids. (E.g., GET /stories/984,1489,8575,174)
403 Forbidden with explanatory message for more than 100 ids.
GET /story/{story clean title}
Identified story.
The "clean title" is the story's title as it appears in the story's URL on digg.com. The clean title is assigned by digg.com when the story is submitted. It is formed as follows:
  1. Characters other than A through Z and 0 through 9 are replaced with spaces.
  2. Leading and trailing spaces are discarded.
  3. Each instance of one or more spaces is replaced by a single underscore.
  4. If the resulting clean title is already used by another story, an underscore and a number are appended.

Generally, this endpoint is used to obtain the details of a story for which the URL on digg.com is known.

404 Not Found for non-existent story.
GET /user/{user name}/submissions
Stories submitted by given user.
404 Not Found indicates that the given user does not exist.
GET /user/{user name}/popular
Popular stories submitted by given user.
404 Not Found indicates that the given user does not exist.
GET /user/{user name}/upcoming
Upcoming stories submitted by given user.
404 Not Found indicates that the given user does not exist.
GET /user/{user name}/dugg
Stories dugg by given user, sorted most recent digg first.
404 Not Found indicates that the given user does not exist.
GET /user/{user name}/commented
Stories commented on by a given user, sorted most recent comment first.
404 Not Found indicates that the given user does not exist.
GET /user/{user name}/friends/submissions
Stories submitted by given user friends.
404 Not Found indicates that the given user does not exist.
GET /user/{user name}/friends/popular
Popular stories submitted by given user friends.
404 Not Found indicates that the given user does not exist.
GET /user/{user name}/friends/upcoming
Upcoming stories submitted by given user friends.
404 Not Found indicates that the given user does not exist.
GET /user/{user name}/friends/dugg
Stories dugg by given user friends, sorted most recent digg first.
404 Not Found indicates that the given user does not exist.
GET /user/{user name}/friends/commented
Stories commented by given user friends, sorted most recent digg first.
404 Not Found indicates that the given user does not exist.

 

Arguments

 

Additional query string parameters to endpoints above. See also Response Types and Application Keys.

 

min_submit_date, max_submit_date
Get stories submitted within a given time period.
  • Not valid for these endpoints:
    • /user/{username}/dugg
    • /user/{username}/commented
    • /user/{user name}/friends/dugg
    • /user/{user name}/friends/commented
  • Values: Unix epoch integer.
  • Limit:
    • No limit, in the following cases:
      • If a username is specified.
      • If one or more story IDs are specified.
      • If a domain is specified.
      • If a story clean title is specified.
      • If a link argument is specified.
      • If upcoming or popular is specified.
    • Otherwise: 30 days.
  • Defaults:
    • All time, in the following cases:
      • If a username is specified.
      • If one or more story IDs are specified.
      • If a domain is specified.
      • If a story clean title is specified.
      • If a link argument is specified.
      • If upcoming or popular is specified.
    • Otherwise:
      • If both omitted: The 30 days before the request.
      • If only min_submit_date specified: 30 days starting at the min_submit_date.
      • If only max_submit_date specified: The 30 days preceding the max_submit_date.
min_promote_date, max_promote_date
Get stories promoted within a given time period, implies status=popular.
  • Not valid for these endpoints:
    • /user/{username}/dugg
    • /user/{username}/commented
    • /user/{user name}/friends/dugg
    • /user/{user name}/friends/commented
  • Values: Unix epoch integer.
  • Limit:
    • No limit, in the following cases:
      • If a username is specified.
      • If one or more story IDs are specified.
      • If a domain is specified.
      • If a story clean title is specified.
      • If a link argument is specified.
      • If upcoming or popular is specified.
    • Otherwise: 30 days.
  • Defaults:
    • All time, in the following cases:
      • If a username is specified.
      • If one or more story IDs are specified.
      • If a domain is specified.
      • If a story clean title is specified.
      • If a link argument is specified.
      • If upcoming or popular is specified.
    • Otherwise:
      • If both omitted: The 30 days before the request.
      • If only min_promote_date specified: 30 days starting at the min_promote_date.
      • If only max_promote_date specified: The 30 days preceding the max_promote_date.
min_date, max_date
Get stories commented on or dugg within a given time period.
  • Valid only for these endpoints:
    • /user/{username}/dugg
    • /user/{username}/commented
    • /user/{user name}/friends/dugg
    • /user/{user name}/friends/commented
  • Values: Unix epoch integer.
  • Limit:
    • No limit, for endpoints /user/{username}/dugg or /user/{username}/commented.
    • Otherwise: 48 hours.
  • Defaults:
    • All time, for endpoints /user/{username}/dugg or /user/{username}/commented.
    • Otherwise:
      • If both omitted: 48 hours before the request.
      • If only min_date specified: 48 hours starting at the min_date.
      • If only max_date specified: The 48 hours preceding the max_date.
sort
How to sort returned stories.
Not valid for these endpoints:
  • /user/{username}/dugg
  • /user/{username}/commented
  • /user/{user name}/friends/dugg
  • /user/{user name}/friends/commented
One of:
promote_date-desc: newest-promoted first (default for popular stories).
promote_date-asc: oldest-promoted first.
submit_date-desc: newest-submitted first (default for everything else).
submit_date-asc: oldest-submitted first.
(Draft) digg_count-desc: highest digg count first.
(Draft) digg_count-asc: lowest digg count first.
count
Number of stories to retrieve.
Story count integer.
Default: 10, Maximum: 100.
403 Forbidden with explanatory message is returned for count > 100.
offset
Offset in complete story list.
Story offset integer.
Default: 0.
domain
Partial domain of linked article.
String, e.g.: nytimes.com matches nytimes.com, www.nytimes.com, etc.
link
URL of linked article.
String, e.g.: http://stamen.com/clients/cabspotting
Note that the URL must be URL-encoded. For example: 
http://services.digg.com/stories?link=http%3A%2F%2Fstamen.com%2Fclients%2Fcabspotting&appkey=http%3A%2F%2Fexample.com%2Fapplication
linkhash
MD5 hash of the URL of linked article.
String, e.g.: baab52e8474e83724d5a00de844fc133 is the MD5 hash of the URL: http://blog.digg.com/?p=130
For example: 
http://services.digg.com/stories?linkhash=baab52e8474e83724d5a00de844fc133&appkey=http%3A%2F%2Fexample.com%2Fapplication
media
Return stories of selected media.
One of:
all: All media (default).
{medium}: The indicated medium.
{comma-separated list of media}: Any of the indicated media.
Each medium in must be the short_name attribute of one of the media returned by the List Media (link) endpoint, e.g. news, videos, or images.
size
For stories with thumbnails, the URL of the thumbnail is included in the response. The size argument specifies the desired size of the thumbnail.
One of:
t: Thumbnail, 80x80 pixels.
a: Sized as for user profile history pages, 30x30 pixels.
s: Small, 48x48 pixels.
m: Medium, 120x120 pixels.
l: Large, 160x160 pixels.
p: Sized as for permalink pages, max 160 pixels in height or width, aspect ratio preserved.
Note that specific pixel sizes may change in future..


Page Information

  • 2 days ago [history]
  • View page source
  • You're not logged in
  • No tags yet learn more

Wiki Information

Recent PBwiki Blog Posts