Device API

Update Device Data

POST /api/2/devices/(username)/(deviceid).json
  • Requires HTTP authentication
  • Since 2.0

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:

POST /api/2/devices/a-user/somedevice-123.json

{
    "caption": "gPodder on my Lappy",
    "type": "laptop"
}
Parameters:
  • username – the username for which device data should be updated
  • deviceid – see Devices
Request JSON Object:
 
  • caption (string) – The new human readable label for the device
  • type (string) – he type of the device. Possible values: desktop, laptop, mobile, server, other

List Devices

POST /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..

Example response:

HTTP/1.1 200 OK

[
  {
   "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
  }
]
Parameters:
  • username – the username for which the devices should be returned

Get Device Updates

GET /api/2/updates/(username)/(deviceid).json
  • Requires Authentication
  • Since 2.3

Example response:

HTTP/1.1 200 OK

{
    "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>
}
Query Parameters:
 
  • sincetimestamp when updates have last been retrieved
  • include_actions (bool) – Default: false, since 2.10

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 Episode Action Types.