PodcastIndex

A Ruby client for the podcastindex.org API

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add podcast_index

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install podcast_index

Configuration

Configure the podcastindex.org API credentials before making any requests:

PodcastIndex.configure do |config|
  config.api_key = "<your api key>"
  config.api_secret = "<your api secret>"
end

Additionally, the base url of the API defaults to https://api.podcastindex.org/api/1.0, but can be overridden in the configure block if necessary:

  config.base_url = "<new base url>"

In a Rails app, this configuration would typically be placed in an initializer file.

Usage

This client currently implements the following sections of the API:

• Search
• Podcasts
• Episodes
• Recent
• Value
• Categories
• Stats

These are exposed through the following domain models:

• Episode
• Podcast
• Soundbite
• Value
• Category
• Stats

The intent is to follow ActiveRecord conventions as reasonably possible. Therefore, most of the requests are accessed through the model's .find_by and .where methods.

Examples

Find a podcast by podcastindex id:

podcast = PodcastIndex::Podcast.find(920666)
podcast.title # => "Podcasting 2.0"

When the podcast cannot be found:

begin
  podcast = PodcastIndex::Podcast.find("invalid")
rescue PodcastIndex::PodcastNotFound
  puts "Podcast not found"
end

Find an episode by guid:

episode = PodcastIndex::Episode.find_by(guid: "PC2084", feedurl: "http://mp3s.nashownotes.com/pc20rss.xml")
episode.title # => "Episode 84: All Aboard to On-Board!"

Find a Value block by feed_id:

value = PodcastIndex::Value.find_by(feed_id: 920666)
value.model.type # => "lightning"

Methods that return multiple results are represented as an array of objects:

episodes = PodcastIndex::Episode.where(person: "Adam Curry")
episodes.count # => 57
episodes.first.title # => "Episode #2: A conversation with Adam Curry"

soundbite = PodcastIndex::Soundbite.where(recent: true)
soundbite.first.episode_id # => 15082076307

Supported Methods

# Episode
Episode.find(id, fulltext: nil)
Episode.find_by(guid, feedurl: nil, feedid: nil, fulltext: nil)
Episode.where(feed_id:, since: nil, max: nil, fulltext: nil)
Episode.where(feed_url:, since: nil, max: nil, fulltext: nil)
Episode.where(podcast_guid:, since: nil, max: nil, fulltext: nil)
Episode.where(live: true, max: nil)
Episode.where(itunes_id:, since: nil, max: nil, fulltext: nil)
Episode.where(person:, fulltext: nil)
Episode.where(recent: true, max: nil, exclude_string: nil, before: nil, fulltext: nil)
Episode.sample(max: nil, lang: nil, categories: [], exclude_categories: [], fulltext: nil) # Find a random episode

# Podcast
Podcast.find(id)
Podcast.find_by(feed_url)
Podcast.find_by(guid)
Podcast.find_by(itunes_id)
Podcast.where(tag:)
Podcast.where(medium:)
# Additional parameters only for searching with "music" medium
Podcast.where(medium: "music", term:, val: nil, aponly: nil, clean: nil, fulltext: nil) 
Podcast.where(term:, val: nil, aponly: nil, clean: nil, fulltext: nil)
Podcast.where(title:, val: nil, clean: nil, fulltext: nil)
Podcast.where(trending: true, max: nil, since: nil, lang: nil, categories: [], exclude_categories: [])
Podcast.where(dead: true)
Podcast.where(recent: true, max: nil, since: nil, lang: nil, categories: [], exclude_categories: [])
Podcast.where(new: true, max: nil, since: nil, feedid: nil, desc: nil)
Podcast.where(newly_found: true, max: nil, since: nil)

# Soundbite
Soundbite.where(recent: true, max: nil)

# Value
Value.find_by(feed_id)
Value.find_by(feed_url)

# Category
Category.all
Category.find(category_id)

# Stats
Stats.current.feed_count_total # => 4316919

The attributes of the models mirror the names in the API, but have been translated to "underscore" format to more closely follow Ruby conventions. For example, the lastUpdateTime attribute for a Podcast is exposed as last_update_time.

Exception Handling

If an error occurs, the client will raise a PodcastIndex::Error exception. The message field will contain the description returned from the server if available, or the exception message. For example, some request require one of three optional params:

begin
  episode = PodcastIndex::Episode.find_by_guid("PC2084")
rescue PodcastIndex::Error => e
  puts e.message # => "This call requires either a valid `feedid`, `feedurl` or `podcastguid` argument. "
end

Performance

Be aware that this client currently does not cache responses. So for example, multiple calls to Category.find() or Stats.current will make multiple API requests. This may change in the future.

Development

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

To install this gem onto your local machine, run bundle exec rake install.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/jasonyork/podcast_index.

License

The gem is available as open source under the terms of the MIT License.