The gpodder.net Feed-Service is a webservice for parsing podcast feeds and
returning the simplified contents as JSON.
curl --header "Accept: application/json" "$SERVER?url=http://feeds.feedburner.com/linuxoutlaws&inline_logo=1&scale_logo=30" #^
curl --header "Accept: application/json" "$SERVER?url=http://youtube.com/rss/user/TEDtalksDirector/videos.rss" #^
curl --header "Accept: application/json" "$SERVER?url=http://soundcloud.com/scheibosan" #^
curl --header "Accept: application/json" "$SERVER?url=http://onapp1.orf.at/webcam/fm4/fod/soundpark.xspf" #^
curl --header "Accept: application/json" "$SERVER?url=http://leo.am/podcasts/floss&url=http://feeds.twit.tv/floss_video_large" #^
curl --header "Accept: application/json" "$SERVER?url=http://www.dancarlin.com/cswdc.xml&process_text=strip_html" #^
curl --header "Accept: application/json" -d "url=http://feeds.feedburner.com/linuxoutlaws" $SERVER #^
Parameters to /parse (either GET or POST as application/x-www-form-urlencoded)
- url: The URL of the feed that should be parsed (required). This parameter can be repeated multiple times. The values can be URL-encoded.
- inline_logo: If set to 1, the (unscaled) logos are included in the response as data URIs (default 0).
- scale_logo: If inline_logo is set to 1, scales the included logo down to the given size. The resulting image is fitted into a square with the given side-length. If the given size is greater than the original size, the image won't be scaled at all.
- logo_format: If inline_logo is set to 1, the inlined image is converted to the specified format (either png or jpeg). If this option is not used, the original format is preserved.
- process_text: Is used to remove HTML from texts. Can be either none (does nothing, default if omitted), strip_html (removes HTML and inserts newlines, bullet points, etc) or markdown (converts HTML to Markdown).
- use_cache: Feeds are cached by the service according to the feed's caching headers. If use_cache is set to 1 (default) feeds are retrieved from the cache if possible. If set to 0, feeds are always fetched from their URL. Do not use 0 as a default value in your application.
Headers to /parse
- If-Modified-Since: Time when all requested feeds have been accessed the last time. The response will only contain podcasts that have been modified in the meantime.
- User-Agent: Clients should send a descriptive User-Agent string. In case of abuse of the service, misbehaving and/or generic user-agents might be blocked.
- Accept: Clients should send Accept: application/json to indicate that they are prepared to receive JSON data. If you send a different Accept header, you will receive a HTML formatted response.
- Accept-Encoding: Include "gzip" in both headers to ensure gzip compression.
- Each response contains a list of feeds, at least one for each url-Parameter
- HTTP-Redirects are followed automatically (this is reflected in the urls field)
- RSS-Redirects are followed by additionally including the new feed in the response
- Each feed contains
- title: the title of the feed
- link: the feeds website
- description: a description of the feed, potentially including HTML characters
- author: the feed's author
- language: the feed's language
- urls: the redirect-chain of the URL passed in the url parameter. This can be used to match the requested URLs to the entries in the response. A permanent redirect is not included here but given in the new_location field, as it indicates that the client should update the feed's location.
- new_location: the referred to location, if the feed uses a permanent HTTP redirect or RSS-Redirects. The new location will also be fetched, parsed and included in the response
- logo: the URL of the feed's logo
- logo_data: the feed's logo as a data URI, if inline_logo has been used. To save bandwidth, the logo is not included if it changed since the date sent in If-Modified-Since
- content_types: the content types of the feed, either audio, video or image
- hub: the endpoint URL of the hub through which the feed is published
- errors: a dictionary of occured errors, where the key contains an error code and the value a string representation.
- warnings: a dictionary of warnings. The key contains an warning code and the value a string representation.
- http_last_modified: the Unix timestamp of the last modification of the feed (according to the HTTP header).
- http_etag: the HTTP E-Tag of the feed
- episodes: the list of episodes
- Each episode contains
- guid: an unique endentifier for the episode (provided by the feed in the GUID property)
- title: the title of the episode
- short_title: the non-repetitive part of the episode title. If an episode number is found, it is also removed and provided separately.
- number: the episode number which is parsed from the title
- description: the description of the episode, potentially including HTML characters
- link: the website link for the episode
- released: the Unix timestamp of the episode's release
- author: the episode's author
- duration: the episode's duration in seconds
- language: the episode's language
- files: a list of all files linked by the episode. Each files is represented by an object containing urls, filesize (in Bytes) and mimetype.
- Current Error Codes
- fetch-feed: The feed could not be retrieved. The URL is given in the urls list
- Current Warning Codes
- fetch-logo: The feed's logo could not be retrieved. Its URL is given in the logo field
- hub-subscription: An error occured while subscribing to the feed's hub for instant updates.
- Last-Modified: The timestamp of the latest change to any of the requested feeds. This value can be used in the If-Modified-Since parameter to subsequent requests. This header is not sent for the HTML formatted response.
- Content-Type: application/json if your request contains Accept: application/json, otherwise the response will contain the HTML representation with text/html.
- Content-Encoding: gzip if the response is compressed. See Accept-Encoding for details.
- Vary: Contains the request headers for which the response can vary. Currently this is Accept, User-Agent, Accept-Encoding.
Using this Instance
If you intend to use this instance of the webservice in your
application, please contact firstname.lastname@example.org beforehand.
The sourcecode is available from https://github.com/gpodder/mygpo-feedservice
under the terms of the AGPLv3. Please report bugs on the bugtracker and mention the exact URL of your failed request.