Podcast API Ruby Library

The Podcast API Ruby library provides convenient access to the Listen Notes Podcast API from applications written in Ruby.

Simple and no-nonsense podcast search & directory API. Search the meta data of all podcasts and episodes by people, places, or topics.

Documentation

See the Listen Notes Podcast API docs.

Installation

Install the package with:

gem install podcast_api

Requirements

• Ruby 2.3+

Usage

The library needs to be configured with your account's API key which is available in your Listen API Dashboard. Set api_key to its value:

require "podcast_api"

api_key = ENV["LISTEN_API_KEY"]
client = PodcastApi::Client.new(api_key: api_key)

begin
    response = client.search(q: 'startup', type: 'episode')
    puts JSON.parse(response.body)
rescue PodcastApi::AuthenticationError
    puts 'Wrong api key'
rescue PodcastApi::InvalidRequestError
    puts 'Client side errors, e.g., wrong parameters'
rescue PodcastApi::NotFoundError
    puts 'Not found'
rescue PodcastApi::RateLimitError
    puts 'Reached quota limit'
rescue PodcastApi::APIConnectionError
    puts 'Failed to connect to Listen API servers'
rescue PodcastApi::PodcastApiError
    puts 'Server side errors'
else
    puts "Free Quota per month: #{response.headers['X-ListenAPI-FreeQuota']}"
    puts "Usage this month: #{response.headers['X-ListenAPI-Usage']}"
    puts "Next billing date: #{response.headers['X-Listenapi-NextBillingDate']}"
end

If api_key is nil, then we'll connect to a mock server that returns fake data for testing purposes.

You can see all available API endpoints and parameters on the API Docs page at listennotes.com/api/docs/.

Handling exceptions

Unsuccessful requests raise exceptions. The class of the exception will reflect the sort of error that occurred.

All exception classes can be found in this file.

And you can see some sample code here.