doc/api/reference/directory.rst

   1 Directory API
   2 =============
   3
   4 Retrieve Top Tags
   5 -----------------
   6
   7 ..  http:get:: /api/2/tags/(int:count).json
   8     :synopsis: Returns a list of the count most used tags.
   9
  10     * Does not require authentication
  11     * Since 2.2
  12
  13     **Example response**:
  14
  15     .. sourcecode:: http
  16
  17         HTTP/1.1 200 OK
  18
  19         [
  20           {
  21            "title": "Technology",
  22            "tag": "technology",
  23            "usage": 530
  24           },
  25           {
  26            "title": "Society & Culture",
  27            "tag": "society-culture",
  28            "usage": 420
  29           },
  30           {
  31            "title": "Arts",
  32            "tag": "arts",
  33            "usage": 400
  34           },
  35           {
  36            "title": "News & Politics",
  37            "tag": "News & Politics",
  38            "usage": 320
  39           }
  40         ]
  41
  42     :param count: number of tags to return
  43
  44
  45 Retrieve Podcasts for Tag
  46 -------------------------
  47
  48 ..  http:get:: /api/2/tag/(tag)/(int:count).json
  49     :synopsis: Returns the most-subscribed podcasts that are tagged with tag.
  50
  51     * Does not require authentication
  52     * Since 2.2
  53
  54     **Example response**:
  55
  56     .. sourcecode:: http
  57
  58         HTTP/1.1 200 OK
  59
  60         [
  61          {"url": "http://leo.am/podcasts/floss",
  62           "title": "FLOSS Weekly",
  63           "description": "Each Thursday we talk about Free Libre and Open Source Software with the people who are writing it. Part of the TWiT Netcast Network.",
  64           "subscribers": 1138,
  65           "logo_url: "http://leoville.tv/podcasts/coverart/floss144audio.jpg",
  66           "website": "http://twit.tv/",
  67           "mygpo_link": "http://gpodder.net/podcast/12925"},
  68
  69          {"url": "http://leo.am/podcasts/twit",
  70           "title": "this WEEK in TECH - MP3 Edition",
  71           "description": "Your first podcast of the week is the last word in tech. [...]",
  72           "subscribers": 895,
  73           "logo_url": "http://leoville.tv/podcasts/coverart/twit144audio.jpg",
  74           "website": "http://thisweekintech.com/",
  75           "mygpo_link": "http://thisweekintech.com/"}
  76         ]
  77
  78     :param tag: URL-encoded tag
  79     :param count: maximum number of podcasts to return
  80
  81
  82 Retrieve Podcast Data
  83 ---------------------
  84
  85 .. http:get:: /api/2/data/podcast.json
  86
  87     Returns information for the podcast with the given URL or 404 if there is
  88     no podcast with this URL.
  89
  90     * No authentication required
  91     * Since 2.2
  92
  93     .. sourcecode:: http
  94
  95         HTTP/1.1 200 OK
  96
  97         {
  98          "website": "http://coverville.com",
  99          "mygpo_link": "http://www.gpodder.net/podcast/16124",
 100          "description": "The best cover songs, delivered to your ears two to three times a week!",
 101          "subscribers": 19,
 102          "title": "Coverville",
 103          "url": "http://feeds.feedburner.com/coverville",
 104          "subscribers_last_week": 19,
 105          "logo_url": "http://www.coverville.com/art/coverville_iTunes300.jpg"
 106         }
 107
 108     ::query url: the feed URL of the podcast
 109
 110
 111 Retrieve Episode Data
 112 ---------------------
 113
 114 .. http:get:: /api/2/data/episode.json
 115
 116     Returns information for the episode with the given {episode-url} that
 117     belongs to the podcast with the {podcast-url}
 118
 119     * Does not require authentication
 120     * Since 2.2 (added released in 2.6)
 121
 122     **Example response**:
 123
 124     .. sourcecode:: http
 125
 126         HTTP/1.1 200 OK
 127
 128         {
 129          "title": "TWiT 245: No Hitler For You",
 130          "url": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3",
 131          "podcast_title": "this WEEK in TECH - MP3 Edition",
 132          "podcast_url": "http://leo.am/podcasts/twit",
 133          "description": "[...]",
 134          "website": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3",
 135          "released": "2010-12-25T00:30:00",
 136          "mygpo_link": "http://gpodder.net/episode/1046492"
 137         }
 138
 139     ::query podcast-url: feed URL of the podcast to which the episode belongs
 140     ::query episode-url: media URL of the episode
 141
 142
 143 Podcast Toplist
 144 ---------------
 145
 146 ..  http:get:: /toplist/(int:number).(format)
 147     :synopsis: Get list of most popular podcasts
 148
 149     * Does not require authentication (public content)
 150     * Since 1.0
 151
 152     **Example request**:
 153
 154     .. sourcecode:: http
 155
 156         GET /toplist/50.json
 157
 158     **Example response**:
 159
 160     .. sourcecode:: http
 161
 162         HTTP/1.1 200 OK
 163
 164         [
 165          {
 166            "website": "http://linuxoutlaws.com/podcast",
 167            "description": "Open source talk with a serious attitude",
 168            "title": "Linux Outlaws",
 169            "url": "http://feeds.feedburner.com/linuxoutlaws",
 170            "position_last_week": 0,
 171            "subscribers_last_week": 1736,
 172            "subscribers": 1736,
 173            "mygpo_link": "http://www.gpodder.net/podcast/11092",
 174            "logo_url": "http://linuxoutlaws.com/files/albumart-itunes.jpg"
 175          },
 176          {
 177            "website": "http://syndication.mediafly.com/redirect/show/d581e9b773784df7a56f37e1138c037c",
 178            "description": "We're not talking dentistry here; FLOSS all about Free Libre Open Source Software. Join hosts Randal Schwartz and Leo Laporte every Saturday as they talk with the most interesting and important people in the Open Source and Free Software community.",
 179            "title": "FLOSS Weekly Video (large)",
 180            "url": "http://feeds.twit.tv/floss_video_large",
 181            "position_last_week": 0,
 182            "subscribers_last_week": 50,
 183            "subscribers": 50,
 184            "mygpo_link": "http://www.gpodder.net/podcast/31991",
 185            "logo_url": "http://static.mediafly.com/publisher/images/06cecab60c784f9d9866f5dcb73227c3/icon-150x150.png"
 186          }]
 187
 188     :query jsonp: a functionname on which the response is wrapped (only valid
 189                   for format ``jsonp``; since 2.8)
 190     :query scale_logo: returns logo URLs to scaled images, see below.
 191     :param number: maximum number of podcasts to return
 192     :param format: see :ref:`formats`
 193
 194
 195     The number field might be any value in the range 1..100 (inclusive both
 196     boundaries).
 197
 198     For the JSON and XML formats, an optional paramter scale_logo={size} can be
 199     passed, which provides a link to a scaled logo (scaled_logo_url) for each
 200     podcast. size has to be a positive number up to 256 and defaults to 64.
 201
 202     The OPML and TXT formats do not add any information about the (absolute and
 203     relative) popularity for each podcast, only the ordering can be
 204     considered. The JSON format includes a more detailed list, usable for
 205     clients that want to display a detailed toplist or post-process the
 206     toplist:
 207
 208     All shown keys must be provided by the server. The description field may be
 209     set to the empty string in case a description is not available. The title
 210     field may be set to the URL in case a title is not available. The
 211     subscribers_last_week field may be set to zero if no data is available. The
 212     client can use the subscribers_last_week counts to re-sort the list and get
 213     a ranking for the last week. With this information, a relative "position
 214     movement" can also be calculated if the developer of the client decides to
 215     do so.
 216
 217
 218 Podcast Search
 219 --------------
 220
 221 .. http:get:: /search.(format)
 222
 223     Carries out a service-wide search for podcasts that match the given query.
 224     Returns a list of podcasts. See :ref:`formats` for details on the response
 225     formats.
 226
 227     * Does not require authentication (public content)
 228     * Since 2.0
 229
 230     :query q: search query
 231     :query jsonp: used to wrap the JSON results in a function call (JSONP); the
 232                    value of this parameter is the name of the function; since
 233                    2.8
 234     :query scale_logo: when set, the results (only JSON and XML formats)
 235                        include links to the podcast logos that are scaled to
 236                        the requested size. The links are provided in the
 237                        scaled_logo_url field; since 2.9
 238     :param format: see :ref:`formats`