From gPodderWiki

This is the specification of Version 2 of the public API for the gpodder.net Web Services.

There are two different APIs for different target audiences:

The Simple API targets developers who want to write quick integration into their existing applications
The Advanced API targets developers who want tight integration into their applications (with more features)

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].

[edit] Reference Implementation

See Client Library API Reference.

[edit] API Parametrization

Since 2.7

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.

[edit] Device IDs

Device IDs 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.

[edit] Simple API

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

Synchronization of episode status fields is not supported
This API uses more bandwith than the advanced API
The client can be stateless
The client can be low-powered - subscribe/unsubscribe events are calculated on the server-side

[edit] Formats

Most of the resources are offered in several different formats

OPML
JSON
JSONP with an option function name that wraps the result (since 2.8)
plain text with one URL per line
XML a custom XML format (see example, since 2.9)

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>

[edit] Subscription Lists

[edit] Download

Request: GET /subscriptions/{username}/{device_id}.opml
Request: GET /subscriptions/{username}/{device_id}.json
Request: GET /subscriptions/{username}/{device_id}.jsonp?jsonp={function-name} (since 2.8)
Request: GET /subscriptions/{username}/{device_id}.txt
Requires HTTP authentication
Since 1.0

Get a list of subscribed podcasts for the given user. The first variant returns the content as OPML feed, the second variant as list of feed URLs in JSON format. The third variant returns the list of URLs (one per line) as simple plaintext.

Example: GET /subscriptions/bob/asdf.opml (Download bob's list for device ID asdf as OPML)

In case of errors, the following HTTP status codes are used:

401 Invalid user
404 Invalid device ID
400 Invalid format (e.g. broken OPML)

[edit] Download All

Request: GET /subscriptions/{username}.opml
Request: GET /subscriptions/{username}.json
Request: GET /subscriptions/{username}.jsonp?jsonp={function-name} (since 2.8)
Request: GET /subscriptions/{username}.txt
Requires HTTP authentication
Since 2.11

Get a list of all subscribed podcasts for the given user. The first variant returns the content as OPML feed, the second variant as list of feed URLs in JSON format. The third variant returns the list of URLs (one per line) as simple plaintext.

Example: GET /subscriptions/bob.opml (Download all of bob's subscriptions as OPML)

This can be used to present the user a list of podcasts when the application starts for the first time.

In case of errors, the following HTTP status codes are used:

401 Invalid user
400 Invalid format (e.g. broken OPML)

[edit] Upload

Request: PUT /subscriptions/{username}/{device_id}.opml
Request: PUT /subscriptions/{username}/{device_id}.json
Request: PUT /subscriptions/{username}/{device_id}.txt
Requires HTTP authentication
Since 1.0

Upload the current subscription list of the given user to the server. The data should be provided either in OPML, JSON or plaintext (one URL per line) format, and should be uploaded just like a normal PUT request (i.e. in the body of the request).

For successful updates, the implementation always returns the status code 200 and the empty string (i.e. an empty HTTP body) as a result, any other string should be interpreted by the client as an (undefined) error.

Defined errors are as follows (in this case, the body that is received from the server might be a user-friendy description of the error):

401 Invalid user
400 Invalid format (cannot parse OPML or JSON)

In case the device does not exist for the given user, it is automatically created. If clients want to determine if a device exists, you have to to a GET request on the same URL first and check for a the 404 status code (see above).

Example: PUT /subscriptions/john/e9c4ea4ae004efac40.txt (Upload john's list for that device as text file)

[edit] Podcast Toplist

Request: GET /toplist/{number}.opml
Request: GET /toplist/{number}.json
Request: GET /toplist/{number}.jsonp?jsonp={function-name} (since 2.8)
Request: GET /toplist/{number}.txt
Request: GET /toplist/{number}.xml
Does not require authentication (public content)
Since 1.0

The number field might be any value in the range 1..100 (inclusive both boundaries). An example request looks like:

GET /toplist/50.json - Get the top 50 list in JSON format

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.

Download a list of podcasts, sorted in descending order (more popular podcasts first) in different formats. 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:

[
 {
   "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"
 }]

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.

[edit] Podcast Suggestions

Request: GET /suggestions/{number}.opml
Request: GET /suggestions/{number}.json
Request: GET /suggestions/{number}.json?jsonp={function-name} (since 2.8)
Request: GET /suggestions/{number}.txt
Requires HTTP authentication
Since 1.0

The number field might be any value in the range 1..100 (inclusive both boundaries). An example request looks like:

GET /suggestions/10.opml - Get 10 suggestions in OPML format

Download a list of podcasts that the user has not yet subscribed to (by checking all server-side subscription lists) and that might be interesting to the user based on existing subscriptions (again on all server-side subscription lists).

The TXT format is a simple URL list (one URL per line), and the OPML file is a "standard" OPML feed. The JSON format looks as follows:

[
  {
   "website": "http://www.linuxgeekdom.com", 
   "mygpo_link": "http://gpodder.net/podcast/64439", 
   "description": "Linux Geekdom", 
   "subscribers": 0, 
   "title": "Linux Geekdom", 
   "url": "http://www.linuxgeekdom.com/rssmp3.xml", 
   "subscribers_last_week": 0, 
   "logo_url": null
 }, 
 {
   "website": "http://goinglinux.com", 
   "mygpo_link": "http://gpodder.net/podcast/11171", 
   "description": "Going Linux", 
   "subscribers": 571, 
   "title": "Going Linux", 
   "url": "http://goinglinux.com/mp3podcast.xml", 
   "subscribers_last_week": 571, 
   "logo_url": "http://goinglinux.com/images/GoingLinux80.png"
 }]

The server does not specify the "relevance" for the podcast suggestion, and the client application SHOULD filter out any podcasts that are already added to the client application but that the server does not know about yet (although this is just a suggestion for a good client-side UX).

[edit] Podcast Search

Request: GET /search.opml?q={query}
Request: GET /search.json?q={query}
Request: GET /search.jsonp?q={query}&jsonp={function-name} (since 2.8)
Request: GET /search.txt?q={query}
Request: GET /search.xml?q={query}
Does not require authentication (public content)
Since 2.0

Carries out a service-wide search for podcasts that match the given query. Returns a list of podcasts. See Formats for details on the response formats.

Parameter	Values	Default Value	Usage	Changes
query	an url-encoded string	none	The search string, can be quoted for exact search
jsonp	a string consisting only of letters, digits and underscores	none	used to wrap the JSON results in a function call (JSONP); the value of this parameter is the name of the function	since 2.8
scale_logo	integer in range [1; 256]	64	when set, the results (only JSON and XML formats) include links to the podcast logos that are scaled to the requested size. The links are provided in the scaled_logo_url field.	since 2.9

[edit] Advanced API

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).

The client has to persist the synchronization state locally
Only changes to subscriptions are uploaded and downloaded
Synchronization of episode status fields is supported in this API
Only JSON is used as the data format to ease development

[edit] Subscriptions

[edit] Update

Request: POST /api/2/subscriptions/{username}/{device_id}.json
Requires HTTP authentication
Since 2.0

Update the subscription list for a given device. Only deltas are supported here. Timestamps are not supported, and are issued by the server.

Example JSON upload data:

 {
  "add": ["http://example.com/feed.rss", "http://example.org/podcast.php"],
  "remove": ["http://example.net/foo.xml"]
 }

Possible Responses

Adding and removing the same Feed in one request is not possible. Status code 400 Bad Request will be returned for such requests.
200 OK If the subscriptions have been updated

In positive responses the server returns a timestamp/ID that can be used for requesting changes since this upload in a subsequent API call. In addition, the server sends a list of URLs that have been rewritten (sanitized, see bug:747) as a list of tuples with the key "update_urls". The client SHOULD parse this list and update the local subscription list accordingly (the server only sanitizes the URL, so the semantic "content" should stay the same and therefore the client can simply update the URL value locally and use it for future updates.

 {
  "timestamp": 1337,
  "update_urls": 
   [
    [
     "http://feeds2.feedburner.com/LinuxOutlaws?format=xml",
     "http://feeds.feedburner.com/LinuxOutlaws"
    ],
    [
     "http://example.org/podcast.rss ",
     "http://example.org/podcast.rss"
    ]
   ]
 }

URLs that are not allowed (currently all URLs that don't start with either http or https) are rewritten to the empty string and are ignored by the Webservice.

[edit] Retrieve Changes

Request: GET /api/2/subscriptions/{username}/{device_id}.json?since={timestamp}
Requires HTTP authentication
Since 2.0

This API call retrieves the subscription changes since the timestamp provided in the since parameter. Its value SHOULD be timestamp value from the previous call to this API endpoint. If there has been no previous call, the cliend SHOULD use 0.

The response format is the same as the upload format: A dictionary with two keys "add" and "remove" where the value for each key is a list of URLs that should be added or removed. The timestamp SHOULD be stored by the client in order to provide it in the since parameter in the next request.

In case nothing has changed, the server returns something like the following JSON content.

 {
   "add": [], 
   "remove": [], 
   "timestamp": 12347
 }

[edit] Episode Actions

[edit] Upload

Request: POST /api/2/episodes/{username}.json
Requires HTTP authentication
Since 2.0

Upload changed episode actions. As actions are saved on a per-user basis (not per-device), the API endpoint is the same for every device. For logging purposes, the client can send the device ID to the server, so it appears in the episode action log on the website.

Example JSON upload data:

 [
  {
   "podcast": "http://example.com/feed.rss",
   "episode": "http://example.com/files/s01e20.mp3",
   "device": "gpodder_abcdef123",
   "action": "download",
   "timestamp": "2009-12-12T09:00:00"
  },
  {
   "podcast": "http://example.org/podcast.php",
   "episode": "http://ftp.example.org/foo.ogg",
   "action": "play",
   "started": 15,
   "position": 120,
   "total":  500
  }
 ]

Allowed Attributes

Attribute	Mandatory	Description
podcast	yes	The URL to the podcast feed the episode belongs to
episode	yes	The download URL of the episode
devices	no	The device ID on which the action has taken place
action	yes	One of: download, play, delete, new
timestamp	no	A UTC timestamp when the action took place, in ISO 8601 format
started	no	Only valid for "play". the position (in seconds) at which the client started playback (requires "position" to be set)
position	no	Only valid for "play". the position (in seconds) at which the client stopped playback
total	no	Only valid for "play". the total length of the file in seconds (requires "position" to be set)

The return value is a JSON dictionary containing the timestamp and a list of URLs that have been rewritten (sanitized, see bug:747 and bug:862) as a list of tuples with the key "update_urls". The client SHOULD parse this list and update the local subscription and episode list accordingly (the server only sanitizes the URL, so the semantic "content" should stay the same and therefore the client can simply update the URL value locally and use it for future updates. An example result with update_urls:

 {"timestamp": 1337,
  "update_urls": [
   ["http://feeds2.feedburner.com/LinuxOutlaws?format=xml",
    "http://feeds.feedburner.com/LinuxOutlaws"],
   ["http://example.org/episode.mp3 ",
    "http://example.org/episode.mp3"]]}

URLs that are not allowed (currently all URLs that contain non-ASCII characters or don't start with either http or https) are rewritten to the empty string and are ignored by the Webservice.

[edit] Retrieve

Request: GET /api/2/episodes/{username}.json
Requires HTTP authentication
Since 2.0

Parameters

Parameter	Values	Default Value	Usage	Changes
podcast	The URL of a Podcast feed	None	If set, only actions for episodes of the given podcast are returned
device	A Device ID	None	If set, only actions for the given device are returned
since	Timestamp	0	Only episode actions since the given timestamp are returned
aggregated	true, false	false	If true, only the latest actions is returned for each episode	added in 2.1

Timestamps: The result is a list of all episode actions that were uploaded since the timestamp given in the since parameter (regardless of the action timestamp itself). The timestamp SHOULD be the value returned by the previous episode retrieve request. If no since value is given, ALL episode actions for the given user are returned. Please note that this could be a potentially long list of episode actions, so clients SHOULD provide a since value whenever possible (e.g. when uploads have been taken place before).

Response: The format of the action list is the same as with the action upload request, but the format is a bit different so that the server can send the new timestamp (that the client SHOULD save and use for subsequent requests):

   {"actions": (list of episode actions here - see above for details),
    "timestamp": 12345}

Client implementation notes: A client can make use of the device variant of this request when it is assigned a single device id. When adding a podcast to the client (without synching the subscription list straight away), the variant with the podcast URL can be used. The first variant (no parameters at all) can be used as a kind of "burst" download of all episode actions, but should be used as little as possible (e.g. after a re-install, although even then, the device-id parameter could be more useful).

[edit] Devices

[edit] Configuration

Request: POST /api/2/devices/{username}/{device-id}.json
Requires HTTP authentication
Since 2.0

Sets the name and type of the device. The device ID is generated by the client application to identify itself in API requests. The name is used to display a human readable identifier to the user on the webservice. Only the keys that are supplied will be updated.

Example Request Data

 {
   "caption": "gPodder on my Lappy",
   "type": "laptop"
 }

Possible Attributes

Attribute	Mandatory	Description
caption	no	The new human readable label for the device
type	no	The type of the device. Possible values: desktop, laptop, mobile, server, other

[edit] List

Request: GET /api/2/devices/{username}.json
Requires HTTP authentication
Since 2.0

Returns the list of devices that belong to a user. This can be used by the client to let the user select a device from which to retrieve subscriptions, etc..

 [
  {
   "id": "abcdef",
   "caption": "gPodder on my Lappy",
   "type": "laptop",
   "subscriptions": 27
  },
  {
   "id": "09jc23caf",
   "caption": "",
   "type": "other",
   "subscriptions": 30
  },
  {
   "id": "phone-au90f923023.203f9j23f",
   "caption": "My Phone",
   "type": "mobile",
   "subscriptions": 5
  }
 ]

[edit] Podcast Directory

[edit] Retrieve Top Tags

Request: GET /api/2/tags/{count}.json
Does not require authentication
Since 2.2

Returns a list of the count most used tags.

[
  {"tag": "Technology",
   "usage": 530 }.
  {"tag": "Society & Culture".
   "usage": 420 },
  {"tag": "Arts".
   "usage": 400},
  {"tag": "News & Politics".
   "usage": 320}
]

[edit] Retrieve Podcasts for Tag

Request: GET /api/2/tag/{tag}/{count}.json
Does not require authentication
Since 2.2

Returns the count most-subscribed podcasts that are tagged with tag.

[
 {"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/"}
]

[edit] Retrieve Podcast Data

Request: GET: /api/2/data/podcast.json?url={url}
No authentication required
Since 2.2

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

{
 "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"
}

[edit] Retrieve Episode Data

Request: GET /api/2/data/episode.json?podcast={podcast-url}&url={episode-url}
Does not require authentication
Since 2.2 (added released in 2.6)

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

{
 "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"
}

[edit] Retrieve Updates for a Device

Request GET /api/2/updates/<username>/<device>.json?since=<timestamp>
Parameter include_actions=(true|false) (Default: false, since 2.10)
Requires Authentication
Since 2.3

With this query you can retrieve episode and subscription updates for the given device.

The response will have the following form and will contain

a list of subscriptions to be added, with URL, title and descriptions
a list of URLs to be unsubscribed
a list of updated episodes
the current timestamp; for retrieving changes since the last query
If include_actions is set to true, each updated episode (with a state other than new) will contain an additional property action which includes the user's latest episode action reported for this episode. The actions have the same format as in the #Retrieving episode actions API endpoint [2].

 {"add":     [
    {
       "title": "PaulDotCom Security Weekly", 
       "url": "http://pauldotcom.com/podcast/psw.xml", 
       "description": "PaulDotCom Security Weekly Podcast with Paul, Larry, Mick, Carlos, and special guests!", 
       "subscribers": 93, 
       "logo_url": "http://pauldotcom.com/images/psw-logo-sm.png"
       "website": "http://pauldotcom.com/", 
       "mygpo_link": "http://gpodder.net/podcast/11194", 
    }
  ],

  "remove":  ["<URL3>"],

  "updates": [
    {
      "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", 
      "mygpo_link": "http://gpodder.net/episode/1046492"
      "released":   """2009-12-12T09:00:00"
      "status":        "(new|play|download|delete)"
     }
    ],

   "timestamp":   <timestamp>
  }

[edit] Settings

Clients can store settings and retrieve settings as key-value-pairs, which are attached to either account, device, podcast or episode.

Keys are the names of the settings and are supposed to be strings. Values can be any valid JSON objects.

[edit] Known Settings

Although settings are primarily used to exchange settings between clients, some of them also trigger some behavior on the website.

Account
- public_profile: when set to False, sets all podcasts to private (as on http://gpodder.net/account/privacy, currently deactivated via API)

Episode
- is_favorite: flags the episode as favorite (can be done on any episode-page)

Podcast
- public_subscription: when set to False, sets the subscription to this podcast to private (as on http://gpodder.net/account/privacy or any podcast-page, currently deactivated via API)

[edit] Save

Request: POST /api/2/settings/<username>/(account|device|podcast|episode).json?<scope-specification>

scope, together with the scope-specification specifies to which object a setting is attached
- podcast: Parameter: podcast=<feed-url>
- account: no parameters needed
- device: Parameter: device=<device-id>
- episode: Parameters: podcast=<feed-url>&episode=<media-url>
Requires Authentication
Since 2.4

Post-Data

{
 "set": {"setting1": "value1", "setting2": "value2"},
 "remove": ["setting3", "setting4"] 
}

set is a dictionary of settings to add or update; remove is a list of keys that shall be removed from the scope.

The response contains all settings that the scope has after the update has been carried out.

{
 "setting1": "value1",
 "setting2": "value"
}

[edit] Retrieve

Request GET /api/2/settings/<username>/(account|device|podcast|episode).json?<scope-specification>
Scope and specification as above
Requires Authentication
Since 2.4

The response contains all settings that the scope currently has

{"setting1": "value1", "setting2": "value2"}

[edit] Favorite Episodes

Request GET /api/2/favorites/<username>.json
Requires Authentication
Since 2.4 (added released in 2.6)

The response is a list of all favorite episodes, as they can be seen on http://gpodder.net/favorites/

[
   {
     "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"
    }
]

[edit] Authentication

[edit] Login / Verify Login

Request POST /api/2/auth/username/login.json
since 2.10

Log in the given user for the given device via HTTP Basic Auth.

If a method other than POST is used, 405 Method not allowed is returned
If the URL is accessed without login credentials provided, 401 Unauthorized is returned.
If the client provides a cookie, but for a different username than the one given, 400 Bad Request is returned.
Otherwise a 200 OK is returned and the response headers have a Cookie set. The cookie is named sessionid.

The client can use this URL with the cookie in the request header to check if the cookie is still valid. If it is, a 200 is returned. Otherwise, 401 is returned.

[edit] Logout

Request POST /api/2/auth/username/logout.json
since 2.10

Log out the given user. Removes the session ID from the database.

If a method other than POST is used, 405 Method not allowed is returned
If the client doesn't send a cookie, the user is already logged and 200 OK is returned
If the client provides a cookie, but for a different username than the one given, 400 Bad Request is returned.
Otherwise 200 OK is returned and the client is logged out.

[edit] Device Synchronisation

[edit] Synchronisation Status

Request GET /api/2/sync-devices/<username>.json
requires authentication
since 2.10

Returns the synchronisation status

{
  "synchronized": [
       ["notebook", "n900"],
       ["pc-home", "pc-work"],
    ],
  "not-synchronized": [
       "test-pc", "netbook"
    ]
}

[edit] Start / Stop Synchronization

Request POST /api/2/sync-devices/<username>.json
requires authentication
since 2.10

{
  "synchronize": [
       ["notebook", "netbook"]
     ],
  "stop-synchronize": ["pc-work"]
}

Sets up / stops synchronization between devices. The synchronization status is sent as a response

{
  "synchronized": [
       ["notebook", "netbook", "n900"]
   ],
  "not-synchronized": [
       "test-pc", "pc-work", "pc-home"
   ]
}

[edit] Podcast Lists

[edit] Create

Request POST /api/2/lists/<username>/create.<format>?title=<url-encoded title>
The list content is sent in the request body, in the format indicates by the format extension
requires authenticaton
since 2.10

The server then generates a short name for the list from the title given in the Request. For example, from the title "My Python Podcasts" the name "my-python-podcasts" would be generated.

Possible Responses

409 Conflict: if the the user already has a podcast list with the (generated) name
303 See Other: the podcast list has been created at the URL given in the Location header

[edit] List User's Lists

Request GET /api/2/lists/<username>.json
since 2.10

Possible Responses

200 OK, the list of lists in the format given below

[
 {"title": "My Python Podcasts", "name": "my-python-podcasts", "web": "http://gpodder.net/user/<username>/lists/my-python-podcasts" }
]

[edit] Retrieve

Request GET /api/2/lists/<username>/list/<list-name>.<format>
since 2.10

Possible Responses

404 Not Found if there is no list with the given name
200 OK and the podcast list in the given format

[edit] Update

Request PUT /api/2/lists/<username>/list/<list-name>.<format>
requires authentication
since 2.10

Possible Responses

404 Not Found if there is no list with the given name
204 No Content If the podcast list has been created / updated

[edit] Delete

Request DELETE /api/2/lists/<username>/list/<list-name>.<format>
requires authentication
since 2.10

Possible Responses

404 Not Found if there is no podcast list with the given name
204 No Content if the list has been deleted.

Web Services/API 2

From gPodderWiki

Contents

[edit] Reference Implementation

[edit] API Parametrization

[edit] Device IDs

[edit] Simple API

[edit] Formats

[edit] Subscription Lists

[edit] Download

[edit] Download All

[edit] Upload

[edit] Podcast Toplist

[edit] Podcast Suggestions

[edit] Podcast Search

[edit] Advanced API

[edit] Subscriptions

[edit] Update

[edit] Retrieve Changes

[edit] Episode Actions

[edit] Upload

[edit] Retrieve

[edit] Devices

[edit] Configuration

[edit] List

[edit] Podcast Directory

[edit] Retrieve Top Tags

[edit] Retrieve Podcasts for Tag

[edit] Retrieve Podcast Data

[edit] Retrieve Episode Data

[edit] Retrieve Updates for a Device

[edit] Settings

[edit] Known Settings

[edit] Save

[edit] Retrieve

[edit] Favorite Episodes

[edit] Authentication

[edit] Login / Verify Login

[edit] Logout

[edit] Device Synchronisation

[edit] Synchronisation Status

[edit] Start / Stop Synchronization

[edit] Podcast Lists

[edit] Create

[edit] List User's Lists

[edit] Retrieve

[edit] Update

[edit] Delete

Views

Personal tools

Navigation

Search

Toolbox

LANGUAGES

Toolbox

Search