This is the specification of Version 2 of the public API for the gpodder.net Web Services.
Please consult the Integration Guide before integrating the gpodder.net API in your application.
There are two different APIs for different target audiences:
The API is versioned so that changes in the major version number indicate backwards incompatible changes. All other changes preserve backwards compatibility. See Web Services/API History for a list of changes. The current version is 2.11. This versioning scheme has been introduced in [1].
Protocol: The API can be accessed via http and https. https is preferable from a security / privacy point of view and should be used by all clients. gpodder.net also seems to be blocked in China via plain http.
Contents |
| Function | Description | Formats | Requires Auth |
|---|---|---|---|
| Directory | |||
| Podcast Toplist | get the most-subscribed podcasts | OPML, JSON, JSONP, TXT, XML | no |
| Podcast Search | search for podcasts | OPML, JSON, JSONP, TXT, XML | no |
| Get Top Tags | get the top tags of the podcast directory | JSON | no |
| Get Podcasts for Tag | get top podcasts for a tag in the podcast directory | JSON | no |
| Get Podcast Data | get data for a feed URL | JSON | no |
| Get Episode Data | get data for a media URL | JSON | no |
| Suggestions | |||
| Podcast Suggestions | get suggestion podcasts based on the user's subscriptions | OPML, JSON, JSONP, TXT, XML | yes |
| Subscriptions | |||
| Upload | Upload the subscriptions of one client | OPML, JSON, JSONP, TXT, XML | yes |
| Get | Get the subscriptions of one client | OPML, JSON, JSONP, TXT, XML | yes |
| Get All | Get the (combined) subscriptions of all of the user's devices | JSON | yes |
| Upload Changes | Upload changes to the subscriptions of one client (added 1 subscription, removed 2 subscriptions) | JSON | yes |
| Get Changes | Get changes to the subscriptions of one client since a specific timestamp (added 1 subscriptions, removed 2 subscriptions) | JSON | yes |
| Episode Actions | |||
| Upload | Upload episode-related events (eg downloaded, played) | JSON | yes |
| Get | Get episode-related events since a specific timestamp (eg downloaded, played) | JSON | yes |
| Devices | |||
| List | List of of the user's devices (clients) | JSON | yes |
| Configure | Set the name and type of the user's devices (clients) | JSON | yes |
| Get Updates | get aggregated updates for a user's device (new episodes, episode actions, etc) | JSON | yes |
| Settings | |||
| Save | store arbitrary JSON values per user account, device, podcast or episode | JSON | yes |
| Get | get arbitrary JSON values per user account, device, podcast or episode | JSON | yes |
| Favorites | |||
| Get Favorite Episodes | get all of the user's favorited episode | JSON | yes |
| Authentication | |||
| Login | login a user | JSON | yes |
| Logout | logout | JSON | yes |
| Device Sync | |||
| Status | get information about synchronized devices | JSON | yes |
| Start / Stop | synchronize devices or stop synchronization | JSON | yes |
| Podcast Lists | |||
| Create | create a list of related podcasts for sharing | JSON | yes |
| List | get a list of all podcast lists of a user | JSON | yes |
| Get | get a podcast list of a user | OPML, JSON, JSONP, TXT, XML | no |
| Update | update a podcast list | OPML, JSON, JSONP, TXT, XML | yes |
| Delete | delete a podcast list | OPML, JSON, JSONP, TXT, XML | yes |
Clients should retrieve and process clientconfig.json before making requests to the webservice. If a client can not process the configuration, it can assume the default configuration given in the clientconfig.json documentation.
Devices are used throughout the API to identify a device / a client application. A device ID can be any string matching the regular expression "[\w.-]+". The client application MUST generate a string to be used as its device ID, and SHOULD ensure that it is unique within the user account. A good approach is to combine the application name and the name of the host it is running on.
If two applications share a device ID, this might cause subscriptions to be overwritten on the server side. While it is possible to retrieve a list of devices and their IDs from the server, this SHOULD NOT be used to let a user select an existing device ID.
Most of the resources are offered in several different formats
JSON
[
{
"website": "http://sixgun.org",
"description": "The hardest-hitting Linux podcast around",
"title": "Linux Outlaws",
"url": "http://feeds.feedburner.com/linuxoutlaws",
"position_last_week": 1,
"subscribers_last_week": 1943,
"subscribers": 1954,
"mygpo_link": "http://gpodder.net/podcast/11092",
"logo_url": "http://sixgun.org/files/linuxoutlaws.jpg",
"scaled_logo_url": "http://gpodder.net/logo/64/fa9fd87a4f9e488096e52839450afe0b120684b4.jpg"
},
# more podcasts here
]
XML
<podcasts> <podcast> <title>Linux Outlaws</title> <url>http://feeds.feedburner.com/linuxoutlaws</url> <website>http://sixgun.org</website> <mygpo_link>http://gpodder.net/podcast/11092</mygpo_link> <description>The hardest-hitting Linux podcast around</description> <subscribers>1954</subscribers> <subscribers_last_week>1943</subscribers_last_week> <logo_url>http://sixgun.org/files/linuxoutlaws.jpg</logo_url> <scaled_logo_url>http://gpodder.net/logo/64/fa9fd87a4f9e488096e52839450afe0b120684b4.jpg</scaled_logo_url> </podcast> </podcasts>
The Simple API provides a way to upload and download subscription lists in bulk. This allows developers of podcast-related applications to quickly integrate support for the web service, as the only
The Advanced API provides more flexibility and enhanced functionality for applications that want a tighter integration with the web service. A reference implementation will be provided as part of the gPodder source code (and gPodder will make use of that reference implementation).
