podcast_api 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2359319833e4c907123b311fab199141119a0f4f24cd7f1ff22bbd765a96ddd2
+  data.tar.gz: 1b1c6746481927ba1b7bf3d56c85c6fdd126f5af3eeb89586591f4eebf48b0dd
+SHA512:
+  metadata.gz: fe91bc1773b38f0ede9be6ebda3dc8f6c05dd34cf4727d38772b996ef7096268c66cb6d066de20eeba76abd920e051684bf7afcd84152c73c3bfc4f0bab4638e
+  data.tar.gz: 62e082095fb3f0a2b6a73c63ccf8b1f5b7f1a228263abe2bcc6809a47c7cb2b0dc934b5f2c1267696cb5c78a3a4fdc8879fe0a245d155321789d3766ffe5ce94

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Listen Notes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,75 @@
+# Podcast API Ruby Library
+
+[![Build Status](https://travis-ci.com/ListenNotes/podcast-api-ruby.svg?branch=main)](https://travis-ci.com/ListenNotes/podcast-api-ruby)
+
+The Podcast API Ruby library provides convenient access to the [Listen Notes Podcast API](https://www.listennotes.com/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.
+
+<a href="https://www.listennotes.com/api/"><img src="https://raw.githubusercontent.com/ListenNotes/ListenApiDemo/master/web/src/powered_by_listennotes.png" width="300" /></a>
+
+## Documentation
+
+See the [Listen Notes Podcast API docs](https://www.listennotes.com/api/docs/).
+
+
+## Installation
+
+Install the package with:
+```sh
+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](https://www.listennotes.com/api/dashboard/#apps). Set `api_key` to its
+value:
+
+```ruby
+
+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](https://www.listennotes.com/api/tutorials/#faq0) 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/](https://www.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](https://github.com/ListenNotes/podcast-api-ruby/blob/main/lib/errors.rb).
+
+And you can see some sample code [here](https://github.com/ListenNotes/podcast-api-ruby/blob/main/examples/sample.rb).

data/examples/Gemfile

@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+
+gem "podcast_api", path: "../"

data/examples/Gemfile.lock

@@ -0,0 +1,25 @@
+PATH
+  remote: ..
+  specs:
+    podcast_api (1.0.1)
+      httparty
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    httparty (0.18.1)
+      mime-types (~> 3.0)
+      multi_xml (>= 0.5.2)
+    mime-types (3.3.1)
+      mime-types-data (~> 3.2015)
+    mime-types-data (3.2021.0225)
+    multi_xml (0.6.0)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  podcast_api!
+
+BUNDLED WITH
+   1.17.2

data/examples/sample.rb

@@ -0,0 +1,77 @@
+require "podcast_api"
+
+api_key = ENV["LISTEN_API_KEY"]
+client = PodcastApi::Client.new(api_key: api_key)
+
+begin
+    response = client.search(q: 'startup')
+    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
+
+
+# response = client.typeahead(q: 'startup', show_podcasts: 1)
+# puts JSON.parse(response.body)
+
+# response = client.fetch_best_podcasts()
+# puts JSON.parse(response.body)
+
+# response = client.fetch_podcast_by_id(id: '4d3fe717742d4963a85562e9f84d8c79')
+# puts JSON.parse(response.body)
+
+# response = client.fetch_episode_by_id(id: '6b6d65930c5a4f71b254465871fed370')
+# puts JSON.parse(response.body)
+
+# response = client.batch_fetch_podcasts(ids: '3302bc71139541baa46ecb27dbf6071a,68faf62be97149c280ebcc25178aa731,37589a3e121e40debe4cef3d9638932a,9cf19c590ff0484d97b18b329fed0c6a')
+# puts JSON.parse(response.body)
+
+# response = client.batch_fetch_episodes(ids: 'c577d55b2b2b483c969fae3ceb58e362,0f34a9099579490993eec9e8c8cebb82')
+# puts JSON.parse(response.body)
+
+# response = client.fetch_curated_podcasts_list_by_id(id: 'SDFKduyJ47r')
+# puts JSON.parse(response.body)
+
+# response = client.fetch_podcast_genres()
+# puts JSON.parse(response.body)
+
+# response = client.fetch_podcast_regions()
+# puts JSON.parse(response.body)
+
+# response = client.fetch_podcast_languages()
+# puts JSON.parse(response.body)
+
+# response = client.just_listen()
+# puts JSON.parse(response.body)
+
+# response = client.fetch_recommendations_for_podcast(id: '25212ac3c53240a880dd5032e547047b')
+# puts JSON.parse(response.body)
+
+# response = client.fetch_recommendations_for_episode(id: '914a9deafa5340eeaa2859c77f275799')
+# puts JSON.parse(response.body)
+
+# response = client.fetch_playlist_by_id(id: 'm1pe7z60bsw')
+# puts JSON.parse(response.body)
+
+# response = client.fetch_my_playlists()
+# puts JSON.parse(response.body)
+
+# response = client.submit_podcast(rss: 'https://feeds.megaphone.fm/committed')
+# puts JSON.parse(response.body)
+
+# response = client.delete_podcast(id: '4d3fe717742d4963a85562e9f84d8c79')
+# puts JSON.parse(response.body)

data/lib/errors.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PodcastApi
+    # PodcastApiError is the base error from which all other more specific PodcastApi
+    # errors derive.
+    class PodcastApiError < StandardError
+    end
+  
+    class AuthenticationError < PodcastApiError
+    end
+  
+    class APIConnectionError < PodcastApiError
+    end
+  
+    class InvalidRequestError < PodcastApiError
+    end
+  
+    class RateLimitError < PodcastApiError
+    end
+  
+    class NotFoundError < PodcastApiError
+    end    
+
+    class APIConnectionError < PodcastApiError
+    end        
+end

data/lib/podcast_api.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require 'httparty'
+
+# Version
+require 'version'
+require 'errors'
+
+module PodcastApi
+
+    class Client
+        include HTTParty
+
+        @@BASE_URL_PROD = 'https://listen-api.listennotes.com/api/v2'
+        @@BASE_URL_TEST = 'https://listen-api-test.listennotes.com/api/v2'
+
+        def initialize(api_key: nil, user_agent: nil)
+            @api_key = api_key
+            @base_url = api_key ? @@BASE_URL_PROD : @@BASE_URL_TEST
+            @headers = {
+                'X-ListenAPI-Key' => @api_key,
+                'User-Agent' => user_agent ? user_agent : "podcasts-api-ruby #{VERSION}"
+            }
+            puts @headers
+        end    
+
+        protected
+        def get_response(response:)
+            if response.code == 200
+                return response
+            elsif response.code == 400
+                raise InvalidRequestError.new 'something wrong on your end (client side errors), e.g., missing required parameters'
+            elsif response.code == 401
+                raise AuthenticationError.new 'wrong api key or your account is suspended'
+            elsif response.code == 404
+                raise NotFoundError.new 'endpoint not exist, or podcast / episode not exist'
+            elsif response.code == 429
+                raise RateLimitError.new 'you are using FREE plan and you exceed the quota limit'
+            else
+                raise PodcastApiError.new 'something wrong on our end (unexpected server errors)'
+            end
+        end
+
+        def send_http_request(http_method, *args)
+            begin
+                response = HTTParty.public_send(http_method, *args)
+            rescue SocketError
+                raise APIConnectionError.new 'Failed to connect to Listen API servers'
+            else
+                return get_response(response: response)
+            end
+        end
+
+        public
+        def search(**kwargs)
+            return send_http_request('get', "#{@base_url}/search", {query: kwargs, headers: @headers})
+        end
+
+        def typeahead(**kwargs)
+            return send_http_request('get', "#{@base_url}/typeahead", {query: kwargs, headers: @headers})
+        end
+        
+        def fetch_best_podcasts(**kwargs)
+            return send_http_request('get', "#{@base_url}/best_podcasts", {query: kwargs, headers: @headers})
+        end
+        
+        def fetch_podcast_by_id(**kwargs)
+            id = kwargs.delete(:id)
+            return send_http_request('get', "#{@base_url}/podcasts/#{id}", {query: kwargs, headers: @headers})
+        end        
+
+        def fetch_episode_by_id(**kwargs)
+            id = kwargs.delete(:id)
+            return send_http_request('get', "#{@base_url}/episodes/#{id}", {query: kwargs, headers: @headers})
+        end        
+
+        def batch_fetch_podcasts(**kwargs)
+            return send_http_request('post', "#{@base_url}/podcasts", {body: kwargs, headers: @headers})
+        end         
+
+        def batch_fetch_episodes(**kwargs)
+            return send_http_request('post', "#{@base_url}/episodes", {body: kwargs, headers: @headers})
+        end              
+
+        def fetch_curated_podcasts_list_by_id(**kwargs)
+            id = kwargs.delete(:id)            
+            return send_http_request('get', "#{@base_url}/curated_podcasts/#{id}", {query: kwargs, headers: @headers})
+        end      
+        
+        def fetch_curated_podcasts_lists(**kwargs)
+            id = kwargs.delete(:id)            
+            return send_http_request('get', "#{@base_url}/curated_podcasts", {query: kwargs, headers: @headers})
+        end              
+        
+        def fetch_podcast_genres(**kwargs)
+            return send_http_request('get', "#{@base_url}/genres", {query: kwargs, headers: @headers})
+        end         
+        
+        def fetch_podcast_regions(**kwargs)
+            return send_http_request('get', "#{@base_url}/regions", {query: kwargs, headers: @headers})
+        end                   
+
+        def fetch_podcast_languages(**kwargs)
+            return send_http_request('get', "#{@base_url}/languages", {query: kwargs, headers: @headers})
+        end            
+
+        def just_listen(**kwargs)
+            return send_http_request('get', "#{@base_url}/just_listen", {query: kwargs, headers: @headers})
+        end           
+
+        def fetch_recommendations_for_podcast(**kwargs)
+            id = kwargs.delete(:id)            
+            return send_http_request('get', "#{@base_url}/podcasts/#{id}/recommendations", {query: kwargs, headers: @headers})
+        end           
+        
+        def fetch_recommendations_for_episode(**kwargs)
+            id = kwargs.delete(:id)            
+            return send_http_request('get', "#{@base_url}/episodes/#{id}/recommendations", {query: kwargs, headers: @headers})
+        end     
+        
+        def fetch_playlist_by_id(**kwargs)
+            id = kwargs.delete(:id)            
+            return send_http_request('get', "#{@base_url}/playlists/#{id}", {query: kwargs, headers: @headers})
+        end     
+        
+        def fetch_my_playlists(**kwargs)
+            return send_http_request('get', "#{@base_url}/playlists", {query: kwargs, headers: @headers})
+        end  
+        
+        def submit_podcast(**kwargs)
+            return send_http_request('post', "#{@base_url}/podcasts/submit", {body: kwargs, headers: @headers})
+        end       
+        
+        def delete_podcast(**kwargs)
+            id = kwargs.delete(:id)            
+            return send_http_request('delete', "#{@base_url}/podcasts/#{id}", {query: kwargs, headers: @headers})
+        end        
+    end
+
+end

data/lib/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module PodcastApi
+  VERSION = "1.0.1"
+end

data/podcast_api.gemspec

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(::File.join(::File.dirname(__FILE__), "lib"))
+
+require "version"
+
+Gem::Specification.new do |s|
+  s.name = "podcast_api"
+  s.version = PodcastApi::VERSION
+  s.required_ruby_version = ">= 2.3.0"
+  s.summary = "Ruby bindings for the Listen Notes Podcast API"
+  s.description = "Listen Notes is the best podcast search engine and api.  " \
+                  "See https://www.listennotes.com/api/ for details."
+  s.author = "Listen Notes, Inc."
+  s.email = "hello@listennotes.com"
+  s.homepage = "https://www.listennotes.com/api/"
+  s.license = "MIT"
+  s.add_runtime_dependency "httparty"
+  s.metadata = {
+    "bug_tracker_uri" => "https://github.com/ListenNotes/podcast-api-ruby/issues",
+    "changelog_uri" =>
+      "https://github.com/ListenNotes/podcast-api-ruby/releases",
+    "documentation_uri" => "https://www.listennotes.com/api/docs/",
+    "github_repo" => "https://github.com/ListenNotes/podcast-api-ruby",
+    "homepage_uri" => "https://www.listennotes.com/api/",
+    "source_code_uri" => "https://github.com/ListenNotes/podcast-api-ruby",
+  }
+
+  ignored = Regexp.union(
+    /\A\.editorconfig/,
+    /\A\.git/,
+    /\A\.rubocop/,
+    /\A\.travis.yml/,
+    /\Atest/
+  )
+  s.files = `git ls-files`.split("\n").reject { |f| ignored.match(f) }
+  s.executables   = `git ls-files -- bin/*`.split("\n")
+                                           .map { |f| ::File.basename(f) }
+  s.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,72 @@
+--- !ruby/object:Gem::Specification
+name: podcast_api
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Listen Notes, Inc.
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2021-04-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Listen Notes is the best podcast search engine and api.  See https://www.listennotes.com/api/
+  for details.
+email: hello@listennotes.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- examples/Gemfile
+- examples/Gemfile.lock
+- examples/sample.rb
+- lib/errors.rb
+- lib/podcast_api.rb
+- lib/version.rb
+- podcast_api.gemspec
+homepage: https://www.listennotes.com/api/
+licenses:
+- MIT
+metadata:
+  bug_tracker_uri: https://github.com/ListenNotes/podcast-api-ruby/issues
+  changelog_uri: https://github.com/ListenNotes/podcast-api-ruby/releases
+  documentation_uri: https://www.listennotes.com/api/docs/
+  github_repo: https://github.com/ListenNotes/podcast-api-ruby
+  homepage_uri: https://www.listennotes.com/api/
+  source_code_uri: https://github.com/ListenNotes/podcast-api-ruby
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Ruby bindings for the Listen Notes Podcast API
+test_files: []