Directory API

Retrieve Top Tags

GET /api/2/tags/(int: count).json
  • Does not require authentication
  • Since 2.2

Example response:

HTTP/1.1 200 OK

[
  {
   "title": "Technology",
   "tag": "technology",
   "usage": 530
  },
  {
   "title": "Society & Culture",
   "tag": "society-culture",
   "usage": 420
  },
  {
   "title": "Arts",
   "tag": "arts",
   "usage": 400
  },
  {
   "title": "News & Politics",
   "tag": "News & Politics",
   "usage": 320
  }
]
Parameters:
  • count – number of tags to return

Retrieve Podcasts for Tag

GET /api/2/tag/(tag)/(int: count).json
  • Does not require authentication
  • Since 2.2

Example response:

HTTP/1.1 200 OK

[
 {"url": "http://leo.am/podcasts/floss",
  "title": "FLOSS Weekly",
  "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.",
  "subscribers": 1138,
  "logo_url: "http://leoville.tv/podcasts/coverart/floss144audio.jpg",
  "website": "http://twit.tv/",
  "mygpo_link": "http://gpodder.net/podcast/12925"},

 {"url": "http://leo.am/podcasts/twit",
  "title": "this WEEK in TECH - MP3 Edition",
  "description": "Your first podcast of the week is the last word in tech. [...]",
  "subscribers": 895,
  "logo_url": "http://leoville.tv/podcasts/coverart/twit144audio.jpg",
  "website": "http://thisweekintech.com/",
  "mygpo_link": "http://thisweekintech.com/"}
]
Parameters:
  • tag – URL-encoded tag
  • count – maximum number of podcasts to return

Retrieve Podcast Data

GET /api/2/data/podcast.json

Returns information for the podcast with the given URL or 404 if there is no podcast with this URL.

  • No authentication required
  • Since 2.2
HTTP/1.1 200 OK

{
 "website": "http://coverville.com",
 "mygpo_link": "http://www.gpodder.net/podcast/16124",
 "description": "The best cover songs, delivered to your ears two to three times a week!",
 "subscribers": 19,
 "title": "Coverville",
 "url": "http://feeds.feedburner.com/coverville",
 "subscribers_last_week": 19,
 "logo_url": "http://www.coverville.com/art/coverville_iTunes300.jpg"
}

::query url: the feed URL of the podcast

Retrieve Episode Data

GET /api/2/data/episode.json

Returns information for the episode with the given {episode-url} that belongs to the podcast with the {podcast-url}

  • Does not require authentication
  • Since 2.2 (added released in 2.6)

Example response:

HTTP/1.1 200 OK

{
 "title": "TWiT 245: No Hitler For You",
 "url": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3",
 "podcast_title": "this WEEK in TECH - MP3 Edition",
 "podcast_url": "http://leo.am/podcasts/twit",
 "description": "[...]",
 "website": "http://www.podtrac.com/pts/redirect.mp3/aolradio.podcast.aol.com/twit/twit0245.mp3",
 "released": "2010-12-25T00:30:00",
 "mygpo_link": "http://gpodder.net/episode/1046492"
}

::query podcast-url: feed URL of the podcast to which the episode belongs ::query episode-url: media URL of the episode

Podcast Toplist

GET /toplist/(int: number).(format)
  • Does not require authentication (public content)
  • Since 1.0

Example request:

GET /toplist/50.json

Example response:

HTTP/1.1 200 OK

[
 {
   "website": "http://linuxoutlaws.com/podcast",
   "description": "Open source talk with a serious attitude",
   "title": "Linux Outlaws",
   "url": "http://feeds.feedburner.com/linuxoutlaws",
   "position_last_week": 0,
   "subscribers_last_week": 1736,
   "subscribers": 1736,
   "mygpo_link": "http://www.gpodder.net/podcast/11092",
   "logo_url": "http://linuxoutlaws.com/files/albumart-itunes.jpg"
 },
 {
   "website": "http://syndication.mediafly.com/redirect/show/d581e9b773784df7a56f37e1138c037c",
   "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.",
   "title": "FLOSS Weekly Video (large)",
   "url": "http://feeds.twit.tv/floss_video_large",
   "position_last_week": 0,
   "subscribers_last_week": 50,
   "subscribers": 50,
   "mygpo_link": "http://www.gpodder.net/podcast/31991",
   "logo_url": "http://static.mediafly.com/publisher/images/06cecab60c784f9d9866f5dcb73227c3/icon-150x150.png"
 }]
Query Parameters:
 
  • jsonp – a functionname on which the response is wrapped (only valid for format jsonp; since 2.8)
  • scale_logo – returns logo URLs to scaled images, see below.
Parameters:
  • number – maximum number of podcasts to return
  • format – see Formats

The number field might be any value in the range 1..100 (inclusive both boundaries).

For the JSON and XML formats, an optional paramter scale_logo={size} can be passed, which provides a link to a scaled logo (scaled_logo_url) for each podcast. size has to be a positive number up to 256 and defaults to 64.

The OPML and TXT formats do not add any information about the (absolute and relative) popularity for each podcast, only the ordering can be considered. The JSON format includes a more detailed list, usable for clients that want to display a detailed toplist or post-process the toplist:

All shown keys must be provided by the server. The description field may be set to the empty string in case a description is not available. The title field may be set to the URL in case a title is not available. The subscribers_last_week field may be set to zero if no data is available. The client can use the subscribers_last_week counts to re-sort the list and get a ranking for the last week. With this information, a relative “position movement” can also be calculated if the developer of the client decides to do so.