Project

podcast_index

0.0
The project is in a healthy, maintained state
podcast_indexjasonyork/podcast-indexHomepageDocumentationSource CodeBug TrackerWiki
Exposes the podcastindex.org API through Ruby domain models.
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Popularity
Downloads
2,776
Stars
5
Forks
2
Watchers
1
 Releases
Current version
0.5.0
Total releases
6
First release
2023-01-07
Latest release
2024-11-08
 Issues
Open Issues
0
Closed Issues
1
Total Issues
1
Issue Closure Rate
100%
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
6
Merged Pull Requests
3
Pull Request Acceptance Rate
33%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2023-08-01
Reverse Dependencies
0

 Dependencies

Development

rspec-its
>= 0
rubocop-performance
>= 0
rubocop-rake
>= 0
rubocop-rspec
>= 0
webmock
>= 0
codecov
>= 0
debug
>= 0
rspec-core
>= 0

Runtime

activesupport
>= 0
addressable
>= 0
 Project Readme

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:

These are exposed through the following domain models:

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.