API Documentation

Endpoint: https://api.podcast.de/
Introduction Click to show

Dear developer,

thank you for your interest in the podcast.de API. Our new REST like API provides functionality to access data and services around podcasting.

Authentication

You´ll find two kinds of actions: private and public ones.

For private actions you will need a special partner key which we only hand out to certified partners.

Public actions are accessible for all API users but are secured if not otherwise stated. You need to authenticate your calls by either providing a combination of valid username/password credentials (HTTP Basic Auth over SSL) or by authenticating with a valid OAuth (OAuth 1.0a or OAuth 2 Bearer) token (preferred way). See oauth/request_token / oauth2/token for details on how to obtain your consumer token.

Languages

We are starting to make all content available and selectable. You´ll find a few actions where you can pass the lang parameter to filter for specific languages. We support the following languages (en = English, ge = German, es = Spanish, fr = French, ru = Russian, ja = Japanese). You might be lucky with other languages as well.

Request limits

A maximum of 200 results is enforced for all calls to ensure platform stability and best performance for all users. We have no other limits at the moment.

Contact

Please do not hesitate to get in touch with me. Email me if you have any questions regarding the API in English or German at: (api [at] podcast [dot] de).

Updates

  • 16.03.2014: Added /comment to retrieve and post comments for channels and shows; increased the maximum number of channels in the charts to 500; Added the possibility to import subscriptions with an OPML file
  • 24.11.2013: Added OAuth2 authentification. Restricted to certified partners as of now.
  • 11.04.2013: Switched signatures of /report method so URLs can be submitted as well.
  • 28.09.2013: Added /autolist , /firehose and /report , fixed count on favorites & added fields (channel_*) for playlist results
  • 22.03.2013: Added the lang parameter for channels selected by a category (/category/)

Public actions

Autolist /autolist

Parameters

Name Required
limit -
offset -

Get the newest shows for the channels a user has subscribed to.

GET: Retrieve a list of shows

Example call for an autolist

https://api.podcast.de/autolist.json?limit=1&offset=15

returns a structure like:


{
    "head": [{
            "limit": 1,
            "offset": 15,
            "count": 200
        }
    ],
    "episodes": [{
            "show_id": "293",
            "title": "tagesschau 20:00 Uhr, 16.01.2013",
            "description": "Themen der Sendung: Aufsichtsratssitzung BER, Mali-Konflikt, Deutsche Beteiligung in Mali, DGB-Bundesvorstandsklausur, Amtsu00fcbergabe Rheinland-Pfalz, Jahreswirtschaftsbericht, Waffenrecht in den USA, Dreamliner-Probleme, Neuer Bayern-Trainer, Handball WM, Die Lottozahlen, Das Wetter",
            "media_link": "http://media.tagesschau.de/video/2013/0116/TV-20130116-2025-5201.h264.mp4",
            "pod_link": "http://www.podcast.de/episode/293/",
            "author": null,
            "rating": "0",
            "votes": "0",
            "image": "http://static.podcastcms.de/images/Feed/Channel/1358/2/1358.png",
            "copyright": "Copyright 2009, tagesschau.de, ARD-aktuell",
            "type": "2",
            "date": "2013-01-16 20:00:00",
            "channel_id": "1358",
            "channel_link": "http://www.podcast.de/podcast/1358/",
            "channel_title": "Tagesschau Video-Podcast"
        }
    ]
}

You can than use any of the shows to mark as a favorite or add to a playlist.

Categories /categories

This action is only available to certified partners.

GET: Returns the complete category tree.

The url to retrieve the category tree in JSON format would look like:

https://api.podcast.de/categories.json

This is what a shortened version of the JSON output may look like:


{
  "categories": {
    "39": {
      "id": "39",
        "title": "Musik",
        "subcategories": {
        "168": {
          "id": "168",
            "title": "Stile",
            "subcategories": {
            "214": {
              "id": "214",
                "title": "Rock",
                "subcategories": {
                "752": {
                  "id": "752",
                    "title": "Punkrock",
                    "subcategories": {
                    "753": {
                      "id": "753",
                        "title": "Deutschpunk",
                        "subcategories": []
                    }
                  }
                },
                  "209": {
                  "id": "209",
                    "title": "Progressive Rock",
                    "subcategories": []
                }
              }
            },
              "165": {
              "id": "165",
                "title": "Instrumente",
                "subcategories": []
            }
          }
        }
      }
    }
  }
}
Category /category/:category_id

Parameters

Name Required
lang -

This action is only available to certified partners.

GET: Provides a list of channels in the requested category.

A call to the API with JSON results would look like:

https://api.podcast.de/category/753.json

and result in:


{
  "head": [{
    "title": "Musik/Stile/Rock/Punkrock/Deutschpunk",
    "limit": 50,
    "offset": 0,
    "count": 2
  }],
  "channels": [{
    "channel_id": "14677",
    "title": "Rockland Radio Podcast",
    "description": "Der Rockland Radio Podcast bietet Ihnen die Aktuellsten News und Interviews.",
    "pod_link": "http://www.podcast.de/podcast/14677/",
    "image": "http://static.podcastcms.de/images/Feed/Channel/14677/2/14677.png",
    "channel_type": "1",
    "rating": "4",
    "votes": "1",
    "lang": "ge"
  }, {
    "channel_id": "7230",
    "title": "Radio1977 alias punkster!",
    "description": "Erster offizieller Podcast aus Rottweil rund um die Punk'n'Roll-Szene in Deutschland in selbiger Sprache.",
    "pod_link": "http://www.podcast.de/podcast/7230/",
    "image": "http://static.podcastcms.de/images/Feed/Channel/7230/2/7230.png",
    "channel_type": "2",
    "rating": "1.16000003814697",
    "votes": "5",
    "lang": "ge"
  }]
}
Channel /channel/:channel_id

Parameters

Name Required
limit -
offset -
channel_id

This action needs no authorization.

A channel (aka podcast) is a series of shows (aka episodes) by an individual, a group of people or an organisation.

GET: Returns detailled information and the list of shows. With limit and offset you control the number and position of shows returned for this channel. count indicates how many shows are actually available alltogether for this channel.

A JSON-call for channel 14677 with a maximum of 50 shows has to look like this:

https://api.podcast.de/channel/14677.json?limit=50

The JSON result will have the following fields:


{
  "head": [{
    "limit": 50,
    "offset": 0,
    "count": 45
  }],
  "channel": {
    "channel_id": "14677",
    "title": "Rockland Radio Podcast",
    "subtitle": null,
    "description": "Der Rockland Radio Podcast bietet Ihnen die Aktuellsten News und Interviews.",
    "pod_link": "http://www.podcast.de/podcast/14677/",
    "image": "http://static.podcastcms.de/images/Feed/Channel/14677/2/14677.png",
    "channel_type": "1",
    "rating": "4",
    "votes": "1",
    "copyright": "2009 Rockland Radio",
    "date": "2009-12-27 21:51:31",
    "episodes": [{
      "show_id": "1446934",
      "title": "Doro bei Rockland Radio 4",
      "description": "Der Buschmann trifft DORO.",
      "media_link": "http://www.rockland.de/podcast/Doro%20bei%20Rockland%20Radio%204.mp3",
      "pod_link": "http://www.podcast.de/episode/1446934/",
      "author": null,
      "rating": "1",
      "votes": "4",
      "copyright": "2009 Rockland Radio",
      "type": "1",
      "date": "2009-12-27 21:51:32"
    }, {
      "show_id": "1446933",
      "title": "Doro bei Rockland Radio 3",
      "description": "Der Buschmann trifft DORO.",
      "media_link": "http://www.rockland.de/podcast/Doro%20bei%20Rockland%20Radio%203.mp3",
      "pod_link": "http://www.podcast.de/episode/1446933/",
      "author": null,
      "rating": "1.75",
      "votes": "2",
      "copyright": "2009 Rockland Radio",
      "type": "1",
      "date": "2009-12-27 21:51:32"
    }]
  }
}
Charts /charts/:chart_id

Parameters

Name Required
type -
limit -
offset -
lang -

GET: Provides a list of channels by chart_id which can be:

  • climber or
  • newcomer or
  • subscribers (default)

You can filter by type ("audio" or "video") to get only audio or video channels.

The result set for the call:

https://api.podcast.de/charts/subscribers.json?limit=2

would look like this:


{
  "head": [{
    "title": "subscribers",
    "limit": 2,
    "offset": 0,
    "type": "all",
    "count": 10463
  }],
  "channels": [{
    "channel_id": "4187",
    "title": "WDR - Quarks & Co",
    "description": "Quarks & Co: Das Wissenschaftsmagazin",
    "rating": "4.87059",
    "votes": "170",
    "channel_type": "2",
    "copyright": "Copyright 2011, WDR",
    "date": "2006-08-10 23:53:25",
    "pod_link": "http://www.podcast.de/podcast/4187/",
    "image": "http://static.podcastcms.de/images/Feed/Channel/4187/2/4187.png"
  }, {
    "channel_id": "13063",
    "title": "ARD - Radio Tatort",
    "description": "In dem Gemeinschaftsprojekt ARD Radio Tatort sorgen spannende und unterhaltende Originalhu00f6rspiele prominenter Autorinnen und Autoren fu00fcr akustischen Nervenkitzel. Zu hu00f6ren sind die Folgen der Hu00f6rfunk-Krimireihe einmal monatlich innerhalb von fu00fcnf Tagen auf den beteiligten Sendern der neun Landesrundfunkanstalten. Der ARD Radio Tatort - jetzt auch als Podcast sieben Tage lang abrufbar, jeden Monat neu.",
    "rating": "4.13115",
    "votes": "61",
    "channel_type": "1",
    "copyright": "Copyright 2009 ARD",
    "date": "2009-04-02 01:05:25",
    "pod_link": "http://www.podcast.de/podcast/13063/",
    "image": "http://static.podcastcms.de/images/Feed/Channel/13063/2/13063.png"
  }]
}
Comment /comment

Parameters

Name Required
id
type
name -
comment -
limit -
offset -
order -

The

GET: Retrieve a list of comments for a specific type (channel OR show)

A request is called like this:

https://api.podcast.de/comment.json?id=4187&type=channel&limit=2&order=ASC
  • type can be channel OR show
  • order can be ASC (aufsteigend nach Veröffentlichungsdatum) OR DESC (absteigend)

A successful query returns a list of comments like this:


[{
    "comment_id": "2602",
    "name": "Werner",
    "comment": "Diesen Podcast höre ich mir immer wieder gerne an.",
    "date_created": "2013-11-16 13:07:56"
}, {
    "comment_id": "3411",
    "name": "Podcast-Lover",
    "comment": "Supergeil! Mehr brauche ich nicht zu sagen.",
    "date_created": "2014-03-10 18:58:33"
}]

POST: Add a comment to a channel or a show

This method additionally requires the parameters name and comment which may not be empty. If the comment is from a logged-in user the parameter name should be the username.

A successful post returns:


{
    "comment_id": 3454,
    "name": "Friedrich",
    "comment": "Das geht ab.",
    "success": 1
}
Favorite /favorite/:show_id

Parameters

Name Required
list_id -

Mark a show as a favorite to find specific shows more easily.

GET: Get details on a favorite show:

https://api.podcast.de/favorite/92792903.json

will return:


{
    "favorite": [{
            "show_id": "92792903",
            "media_link": "http:\/\/download.www.arte.tv\/podcast\/buchmesse2010_d\/videos\/09-1300_scheck_pc.mp4",
            "title": "Tag 5: Inseln des Guten, Sch\u00f6nen, Wahren im Meer des Irrsinns",
            "description": "Nirgends ist das Angebot so erdr\u00fcckend wie auf der Buchmesse. Denis Scheck hilft: Welche B\u00fccher lohnen sich zu lesen? Wovon l\u00e4sst man lieber die Finger? Am ARTE-Stand gibt der Literaturkritiker seine ganz pers\u00f6nlichen Leseempfehlungen.",
            "date": "2010-10-10 00:00:00",
            "type": "audio\/mpeg",
            "channel_id": "78044",
            "author": "ARTE",
            "votes": "1",
            "rating": "4",
            "pod_link": "http:\/\/www.podcast.de\/episode\/92792903\/",
            "channel_link": "http:\/\/www.podcast.de\/podcast\/78044\/",
            "channel_title": "Schecks Buchmesse 2010",
            "copyright": null,
            "image": "http:\/\/static.podcastcms.de\/images\/Feed\/Channel\/78044\/2\/78044.png",
            "favorite": "1",
            "listened": "0",
            "position": null
        }
    ],
    "success": 1
}

Optionally get a favorite from a specific playlist with parameter list_id as provided by action Playlists.

POST: Mark a show as favorite. Marks as favorite in all playlists if show is in several playlists.

Optionally set position in a specific playlist with parameter list_id as provided by action Playlists.

DELETE: Remove favorite marker for a show. Remove marker in all playlists by default.

Optionally remove favorite marker in a specific playlist with parameter list_id as provided by action Playlists.

HEAD: Check if a show is marked as favorite.

Optionally check for a specific playlist with parameter list_id as provided by action Playlists.

Favorites /favorites

Parameters

Name Required
list_id -
limit -
offset -

GET: Retrieve a list of shows which are marked as favorites. Listed by most recently published show descending:

https://api.podcast.de/favorites.json

Optionally retrieve favorites only from a specific playlist by providing the list_id parameter.

The output looks like this:


{
    "head": [{
            "limit": 2,
            "offset": 0,
            "count": 6
        }
    ],
    "shows": [{
            "show_id": "92792903",
            "title": "Tag 5: Inseln des Guten, Schu00f6nen, Wahren im Meer des Irrsinns",
            "description": "Nirgends ist das Angebot so erdru00fcckend wie auf der Buchmesse. Denis Scheck hilft: Welche Bu00fccher lohnen sich zu lesen? Wovon lu00e4sst man lieber die Finger? Am ARTE-Stand gibt der Literaturkritiker seine ganz persu00f6nlichen Leseempfehlungen.",
            "media_link": "http://download.www.arte.tv/podcast/buchmesse2010_d/videos/09-1300_scheck_pc.mp4",
            "date": "2010-10-10 00:00:00",
            "type": "2",
            "channel_id": "78044",
            "author": "ARTE",
            "votes": "1",
            "rating": "4",
            "pod_link": "http://www.podcast.de/episode/92792903/",
            "channel_link": "http://www.podcast.de/podcast/78044/",
            "channel_title": "Schecks Buchmesse 2010",
            "copyright": null,
            "image": "http://static.podcastcms.de/images/Feed/Channel/78044/2/78044.png",
            "favorite": "1",
            "listened": "0",
            "position": null
        }, {
            "show_id": "1589032",
            "title": "Nur ein Ohrenblick: Pinguinparade",
            "description": "Die Pinguinparade auf Phillip Island in Australien, bei der die Pinguine in Reih und Glied u00fcber den Strand marschieren, lockt regelmu00e4u00dfig hunderte von Touristen an. Ich belausche das Wechselspiel zwischen Touristen und Pinguinen. Hintergrundinformationen",
            "media_link": "http://ohrenblicke.podspot.de/files/ohrenblicke046_pinguin1.mp3",
            "date": "2010-05-02 18:38:16",
            "type": "1",
            "channel_id": "4280",
            "author": null,
            "votes": "3",
            "rating": "5",
            "pod_link": "http://www.podcast.de/episode/1589032/",
            "channel_link": "http://www.podcast.de/podcast/4280/",
            "channel_title": "Ohrenblicke",
            "copyright": "u00a9 2006 - 2011 by Jens Wenzel - www.ohrenblicke.de",
            "image": "http://static.podcastcms.de/images/Feed/Channel/4280/2/4280.png",
            "favorite": "1",
            "listened": "0",
            "position": null
        }
    ]
}
Ping /ping

Parameters

Name Required
url -

This action needs no authorization.

GET: Check if url is known in system. Returns a 200 if channel is known and the ID of the channel as channel_id.

A call like:

https://api.podcast.de/ping.json?url=http://feeds2.feedburner.com/VideopodcastKinoAktuell

will in case of success return:


{
  "channel_id": "12816",
  "success": 1
}

in case the url is not yet known in the system you will get an error message:


{
  "errors": [{
    "message": "The url is not known",
    "name": "NOT_FOUND",
    "at": ""
  }]
}

HEAD: Check if url is known in system. Returns a HTTP Status Code 200 if channel is known, a 404 otherwise.

Playlist /playlist/:list_id

Parameters

Name Required
label -
show_id -
limit -
offset -

A playlist is a collection of shows.

GET: Retrieve items in a playlist.

You can limit the number of results with the optional parameter limit. You can page through the results with offset.

See action playlists on how to GET the user´s playlists to start with.

Example call for playlist number 52

https://api.podcast.de/playlist/52.json

returns a structure like:


{
  "head": [{
    "limit": 50,
    "offset": 0,
    "count": 1
  }],
  "episodes": [{
    "show_id": "235570",
    "title": "Reichstag Berlin",
    "description": "Reichstag Berlin",
    "media_link": "http://RolloTV.de.nyud.net:8080/kurzeFilme/RolloTV/C65D19CB-C3BC-47D6-9416-753C9102D745_files/02%20Reichstag%20Berlin.mp4",
    "pod_link": "http://www.podcast.de/episode/235570/",
    "author": null,
    "rating": "5.0000",
    "votes": "1",
    "channel_id": "5887",
    "image": "http://static.podcastcms.de/images/Feed/Channel/5587/2/5587.png",
    "copyright": null,
    "type": "2",
    "date": "2006-11-22 23:01:52"
  }]
}

PUT: Change the title (label) of the playlist.

Requires label

POST: Add an item to the playlist.

Requires show_id

DELETE: Remove an item from the playlist.

Requires show_id

HEAD: Check if 'playlist' is known in system. Returns a 200 if playlist is known, a 404 otherwise.

Requires list_id

Playlists /playlists

Parameters

Name Required
list_id -
label -

Each user can have multiple playlists. A playlist is a collection of shows.

GET: Retrieve the user´s list of playlists.

Make the call:

https://api.podcast.de/playlists.json

to get:


[{
  "list_id": "52",
  "label": "Berlin",
  "privacy_status": "0",
  "privacy_hash": null,
  "is_standard": "0",
  "is_quicklist": "0"
}, {
  "list_id": "15801",
  "label": "Quickliste",
  "privacy_status": "0",
  "privacy_hash": "123ezV0rNgenszjY",
  "is_standard": "0",
  "is_quicklist": "1"
}]

PUT: Add a playlist.

Allows label as optional parameter to give the playlist a name.

DELETE: Delete a playlist by passing the list id.

Requires list_id to indicate which playlist is to be deleted.

Position /position/:show_id

Parameters

Name Required
list_id -

Mark the play position of a show. The following formats for position are accepted:

  • In seconds as Integer: 32456
  • As minutes with seconds: 03:45
  • As hours with minutes and seconds: 01:10:59

GET: Get maximum position for a show in seconds.

If the show is in at least one playlist and a position is set the following call with:

https://api.podcast.de/position/235570.json

for show 235570 will return:


{
  "position": "15",
  "success": 1
}

otherwise you will get an error message:


{
  "errors": [{
    "message": "Could not get position for this show",
    "name": "NOT_FOUND",
    "at": ""
  }]
}

Optionally get position in a specific playlist with parameter list_id as provided by action Playlists otherwise it takes the highest/latest position it can find.

POST: Set position for a show. Sets position in all playlists if show is in several playlists.

Optionally set position in a specific playlist with parameter list_id as provided by action Playlists.

DELETE: Reset position for a show. Resets position in all playlists by default.

Optionally reset position in a specific playlist with parameter list_id as provided by action Playlists.

HEAD: Check if show is in a playlist.

Optionally check for a specific playlist with parameter list_id as provided by action Playlists.

Rating /rating

Parameters

Name Required
type
id
points -

Users can rate channels and shows. Use this call to vote and retrieve votes.

Requires the parameter id as provided for channels by Charts, Category or Search and provided for shows by all *lists (Autolist, Playlist) and Favorites.

Requires the parameter type with type=channel for channels and type=show for shows.

GET: Get rating for a channel or a show

The call:

https://api.podcast.de/rating.json?type=channel&id=123456

will return the following if there is a result


{"votes":"1","rating":"4.0000"}

otherwise an empty list.

POST: Add a rating for a channel or a show

Additionally to the parameters id and type this requires the parameter points with valid points being a number between 1 and 5.

Each client is only allowed to vote for every entity once every 24 hours. Votes by guests are allowed.

Search /search

Parameters

Name Required
q
limit -
offset -

This action is public and needs no authorization.

GET: Returns a list of channels matching the query.

A search request for the term Berlin which is limited to two results and starts at the fifth results would like:

https://api.podcast.de/search.json?q=berlin&limit=2&offset=5

and the result would have the following structure:


{
  "head": [{
    "title": "berlin",
    "limit": 2,
    "offset": 5,
    "count": 538
  }],
  "channels": [{
    "channel_id": 75529,
    "title": "Tresor.Cast",
    "description": "The Official Podcast for Tresor Berlin",
    "pod_link": "http://www.podcast.de/podcast/75529/",
    "image": "http://static.podcastcms.de/images/Feed/Channel/75529/2/75529.png",
    "channel_type": 1,
    "rating": 5,
    "votes": 1
  }, {
    "channel_id": 696,
    "title": "berlin von unten",
    "description": "eine bestatterin erzaehlt alltagsgeschichten",
    "pod_link": "http://www.podcast.de/podcast/696/",
    "image": "http://static.podcastcms.de/images/Feed/Channel/696/2/696.png",
    "channel_type": 1,
    "rating": 4.75,
    "votes": 1
  }]
}
Subscriptions /subscriptions

Subscriptions are the user´s favorite channels. It is a collection of podcasts.

GET: Get user´s subscriptions

The call:

https://api.podcast.de/subscriptions.json?limit=2

will get a result like:


{
  "head": [{
    "limit": 2,
    "offset": 0,
    "count": 20
  }],
  "subscriptions": [{
    "title": "dailycoffeebreak",
    "description": "Jeden Morgen, z. B. zum ersten Kaffee in der Strau00dfenbahn oder im Bu00fcro, ein kleiner Audioausflug mit einer handvoll Stories mit u201cNew Mediau201d Fokus. Bequem abonnierbar - auch auf Deinem mobilen Endgeru00e4t. Durch Kapitelmarken und Soundcloud Kommentare jederzeit nur einen Klick/Touch vom angesprochenen Inhalt entfernt.",
    "channel_id": "19879",
    "feed_link": "http://feeds.feedburner.com/dailycoffeebreakpodcast",
    "pod_link": "http://www.podcast.de/podcast/19879/",
    "image": "http://static.podcastcms.de/images/Feed/Channel/19879/2/19879.png",
    "rating": "5",
    "votes": "7",
    "channel_type": "1",
    "copyright": "dailycoffeebreak.de mit u2665 unter CC BY 3.0",
    "date": "2012-11-12 10:28:20"
  }, {
    "title": "Der Killer Club (Krimipodcast)",
    "description": "Internationale Krimi- und Thriller-Autoren schreiben einen Fortsetzungsroman u2013 und Sie lauschen den spannenden Geschichten exklusiv im Podcast-Format.",
    "channel_id": "9766",
    "feed_link": "http://www.krimi-podcast.de/category/killerclub/feed",
    "pod_link": "http://www.podcast.de/podcast/9766/",
    "image": "http://static.podcastcms.de/images/Feed/Channel/9766/2/9766.png",
    "rating": "5.39",
    "votes": "22",
    "channel_type": "1",
    "copyright": "u00a9Droemer Knaur ",
    "date": "2012-11-12 10:20:33"
  }]
}

POST: Add a channel to user´s subscriptions

Requires the parameter channel_id as provided by Charts, Category or Search

Alternatively accepts an OPML file with a list of podcast feed-urls provided as xmlUrl attribute.

HEAD: Check if a channel is subscribed

Requires the parameter channel_id as provided by Charts, Category or Search

DELETE: Remove a channel from user´s subscriptions

Requires the parameter channel_id as provided by Charts, Category or Search

Private actions

Firehose /firehose

Get a list of the 50 newest shows in the database.

GET: Retrieve list of shows

A call with:

https://api.podcast.de/firehose.json

should return a result as follows:


{
    "head": [{
            "limit": 50,
            "offset": 0,
            "count": 50
        }
    ],
    "episodes": [{
            "show_id": "211721887",
            "title": "Jason Campbell Conference Call - 3\/28",
            "description": "Jason Campbell held a conference call with the Cleveland Media on 3\/28",
            "media_link": "http:\/\/prod.video.browns.clubs.nfl.com\/CLE\/audios\/dct\/video_audio\/2013\/03-March\/\/3-28-campbell.mp3",
            "pod_link": "http:\/\/www.podcast.de\/episode\/211721887\/",
            "author": null,
            "rating": "0",
            "votes": "0",
            "image": "http:\/\/static.podcastcms.de\/images\/Feed\/Channel\/53146\/2\/53146.png",
            "copyright": null,
            "type": "1",
            "date": "2013-03-28 18:59:40",
            "channel_id": "53146",
            "channel_link": "http:\/\/www.podcast.de\/podcast\/53146\/",
            "channel_title": "Cleveland Browns Audio Podcasts"
        }, {
            "show_id": "211720211",
            "title": "\u30e9\u30f3\u30d1\u30f3\u30d7\u30b9\u306e\u30cf\u30f3\u30b0\u30aa\u30fc\u30d0\u30fc #70",
            "description": "2013\/3\/28\u30b3\u30fc\u30ca\u30fc\u3078\u306e\u6295\u7a3f\u304a\u5f85\u3061\u3057\u3066\u3044\u307e\u3059\u3002\u300c\u30e9\u30f3\u30ad\u30f3\u30b0\u30c6\u30fc\u30de\u300d\u666e\u901a\u306e\u304a\u4fbf\u308a\u307e\u305f\u756a\u7d44\u306b\u5bfe\u3059\u308b\u3054\u610f\u898b\u3054\u8981\u671b\u304a\u5f85\u3061\u3057\u3066\u3044\u307e\u3059\u3002\u3042\u3066\u5148\u306f\u3053\u3061\u3089\u21d2\u3000R.Hangover@gmail.comTwitter\u306f\u3053\u3061\u3089\u21d2\u3000http:\/\/twitter.com\/rhangover1\u30b3\u30b3\u3092\u30af\u30ea\u30c3\u30af\u3057\u3066\u30e9\u30f3\u30d1\u30f3\u30d7\u30b9\u306e\u30cf\u30f3\u30b0\u30aa\u30fc\u30d0\u30fc\u3092itunes\u306b\u767b\u9332\uff01",
            "media_link": "http:\/\/f12.voiceblog.jp\/data\/rhang\/1364492003.mp3",
            "pod_link": "http:\/\/www.podcast.de\/episode\/211720211\/",
            "author": null,
            "rating": "0",
            "votes": "0",
            "image": "http:\/\/static.podcastcms.de\/images\/Feed\/Channel\/36673\/2\/36673.png",
            "copyright": "Copyright (C) VOICE-BANK Inc. All Rights Reserved",
            "type": "1",
            "date": "2013-03-28 18:34:50",
            "channel_id": "36673",
            "channel_link": "http:\/\/www.podcast.de\/podcast\/36673\/",
            "channel_title": "VOICEBLOG - recent_articles"
        },
        ...
    ]
}
Login /login

Parameters

Name Required
username
password

This action is only available to certified partners.

GET: Checks if the username and password combination is valid.

Relatedtags /tags/related

Parameters

Name Required
tag
limit -
offset -

This action is only available to certified partners.

GET: Get a list of related tags

A call for tags related to Smartphone would look like this:

https://api.podcast.de/tags/related.json?tag=smartphone

and result in:


{
  "head": [{
    "limit": 50,
    "offset": 0,
    "count": 49
  }],
  "tags": [{
    "tag": "android",
    "count": 24
  }, {
    "tag": "iphone",
    "count": 21
  }, {
    "tag": "apple",
    "count": 19
  }, {
    "tag": "apps",
    "count": 14
  }
}
Report /report

Parameters

Name Required
id
type -
status Yu -

Report a show or channel which is not available anymore or moved (in case of a channel). The report will go to a queue. Reported shows/channels will be (re-)checked for their availability.

POST: Submit the ID (as id) OR the url of the show/channel which is not working as a POST field. type indicates if we are dealing with a show (type=show) or channel (type=channel). You can also pass

Example call to report show no. 12345:

https://api.podcast.de/report.json

The call will return the following confirmation if the report was successfully added:


{"success":1}

or an error message if the report was not added. This will most likely happen if there is no show with given id.

Tag /tag

Parameters

Name Required
tag
limit -
offset -
lang -

This action is only available to certified partners.

GET: Retrieve a list of channels which are tagged by the provided keyword ("tag"), e.g. a query for berlin:

https://api.podcast.de/tag.json?tag=berlin

{
  "head": [{
    "limit": 50,
    "offset": 0,
    "count": 460
  }],
  "channels": [{
    "channel_id": "16151",
    "title": "104.6 RTL - Best of Arno & die Morgencrew",
    "pod_link": "http://www.podcast.de/podcast/16151/",
    "image": "http://static.podcastcms.de/images/Feed/Channel/16151/2/16151.png",
    "channel_type": "1",
    "rating": "5",
    "votes": "1",
    "copyright": "Copyright 2010, 104.6 RTL Berlins Hit-Radio",
    "date": "2010-07-14 14:57:24",
    "lang": "ge"
  }, {
    "channel_id": "16217",
    "title": "104.6 RTL - Burhahn Yilmaz",
    "pod_link": "http://www.podcast.de/podcast/16217/",
    "image": "http://static.podcastcms.de/images/Feed/Channel/16217/2/16217.png",
    "channel_type": "1",
    "rating": "6",
    "votes": "1",
    "copyright": "Copyright 2010, 104.6 RTL Berlins Hit-Radio",
    "date": "2010-07-26 10:57:57",
    "lang": "ge"
  }]
}
User /user/:username

Parameters

Name Required
email -

This action is only available to certified partners.

GET: Retrieve information about an user. (disabled as of now)

HEAD: Check if an username exists.

Check the status code of the response:
200 = User(name) exists
404 = User(name) is not in use

https://api.podcast.de/user/fabio.json

Returns empty body.

PUT: Create a new user by providing an username and an email. The response code will be 201 (Created) if the new user is successfully added.

Requires parameter email which needs to be a valid email address

Returns in case of success an automagically generated password:


{
    "success": 1,
    "password": "nksdlfnwerbsdchskbtr",
    "username": "clearexample",
    "email": "clear@example.com"
}

In case an error occurs you get an error message as such:


{
    "errors": [{
        "message": "Username is not available",
        "name": "USERNAME_NOT_AVAILABLE",
        "at": ""
    }]
}

POST: Update user information. (not implemented, yet)

OAuth actions

Oauthaccesstoken /oauth/access_token

Parameters

Name Required
oauth_consumer_key
oauth_nonce
oauth_signature
oauth_signature_method
oauth_timestamp
oauth_token
oauth_verifier
oauth_version -

POST: Used to exchange the User-authorized Request Token for an Access Token

Oauthauthorize /oauth/authorize

Parameters

Name Required
oauth_token -

GET or POST: Used to obtain User authorization for Consumer access

Oauthrequesttoken /oauth/request_token

POST: Used to obtain an unauthorized Request Token as specified in the The OAuth 1.0 Protocol

  1. Register at podcast.de to get an account if you do not have one, yet

  2. Add your app here to get a Consumer key and Consumer secret

  3. Get a get Request token using this action providing the Consumer key and Consumer secret fetched in step 2:

    https://api.podcast.de/oauth/request_token

OAuth2 actions

Oauth2token /oauth2/token

Use OAuth2 to authenticate users with an access token. You´ll need a special client_id and client_secret which is only available to certified partners. If you are interested in partnering up do not hesitate to contact us.

POST: Retrieve an access token for an existing user. Provide grant_type=password , the provided client_id and client_secret and the user´s username and password.

{"access_token":"66792fb48e5cf8c9d680f3f053dc6aeea1f97391","expires_in":3600,"token_type":"Bearer","scope":null,"refresh_token":"216090a9f7198ff97df464c9ff4ef2efb17f418"}

An invalid request will issue an error, e.g.

{"error":"invalid_client","error_description":"The client credentials are invalid"}

All results will be in JSON format.

Errors

401 CREDENTIALS_INCORRECT

Description

The username/password combination you are using is not valid. There could be several reasons for that:

  • The username/email is not known
  • The password is not valid for the user
  • The user account is suspended

If you are certain username and password are a perfect fit and they are still rejected do not hesitate to contact us.

Error Message

The credentials are not correct

404 NOT_FOUND

Description

This error is returned whenever a ressource is not available.

Possible error messages (Action):

  • Could not get position for this show (Position)
  • The playlist is not known (Playlist)
  • The url is not known (Ping)
  • The user was not found (User)

Error Message

The error message depends on the action called. Look for details in the description.

405 NO_POST

Description

This error is returned whenever a resource prevents the use of the POST method.

Error Message

POST calls are not accepted for this request.

405 NO_PUT

Description

This error is returned whenever someone tries to execute a PUT request on a collection or a resource that prevents PUT requests.

Error Message

This method is not accepted for this API call.

409 UNKNOWN_TYPE

Description

Error is returned when a resource accepts requests for different types - mostly channels and shows - and you provide an unknown or unsupported type in your request.

Error Message

The type you passed is not valid.

500 NOT_IMPLEMENTED

Error Message

This method is not available

Output Formats / Mimetypes

json application/json | text/json | text/plain