doc/api/reference/directory.rst

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