yourub 2.0.3 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 76023fb4d89509d08902ab1ed6810758b260a070
-  data.tar.gz: 964ad582fc7d3463da47e2e8220154e92d4177cb
+SHA256:
+  metadata.gz: 8d722c005745a329557fad47e8b494e1fd42e18f2e7f2df397a6b467bee9a599
+  data.tar.gz: 5e0c6ffc16c546c32b3d21f0354cb19976756b0436e71260e9dcf937aa2af7e2
 SHA512:
-  metadata.gz: 7bacc97831647d25a6f8288b2258c0a100aac9aa5f9ac092e30940228f9790815d7866f9fe431ccda70764461b13b984d1ff058bd381fdcd55b9643451c37964
-  data.tar.gz: aa97fb23ddb4bc1f2a1cebb2d7cd1fdb6e4845c4b4489a82a34afdf3b6af8d91571d227acc2d2ef261773f03e62df98f1fccad76308b1c5e315f1524f9b9ef86
+  metadata.gz: 90b6010eeb9cd2f0311ef0217b152ab800ed038d7ac18557d983b877d8e4653e890f5046490f490c18130a7a871a60919255823cda38920295626391ec7f8241
+  data.tar.gz: 58beed04c2d831215d74129c9c41e9029d7daaa671b68c711be1df41076b0b9819f1fb8854a5d922f4bf7aa68633a5f1646853415577e9cf170a8fa936e1eea5

data/.gitignore

@@ -15,3 +15,4 @@ lib/yourub/DEVELOPER_KEY
 lib/yourub/cli.rb
 pkg
 rdoc
+test.rb

data/.travis.yml

@@ -1,13 +1,9 @@
 language: ruby
 
 rvm:
-  - 1.9.3
   - 2.0.0
   - 2.1
   - 2.2
-  - jruby-19mode
-  - jruby-head
-  - rbx-2
   - ruby-head
 
 sudo: false

data/Gemfile

@@ -9,9 +9,9 @@ end
 
 group :test do
   gem 'coveralls'
-  gem 'rspec', '>= 3.00'
-  gem 'rubocop', '>= 0.27'
-  gem 'simplecov', '>= 0.9'
+  gem 'rspec'
+  gem 'rubocop'
+  gem 'simplecov'
   gem 'webmock'
 end
 

data/README.md

@@ -1,10 +1,8 @@
 [![Gem Version](https://badge.fury.io/rb/yourub.svg)](http://badge.fury.io/rb/yourub)
-[![Dependency Status](https://gemnasium.com/edap/yourub.svg)](https://gemnasium.com/edap/yourub)
-[![Build Status](https://travis-ci.org/edap/yourub.svg?branch=master)](https://travis-ci.org/edap/yourub)
-[![Code Climate](https://codeclimate.com/github/edap/yourub.png)](https://codeclimate.com/github/edap/yourub)
+
 
 # Yourub
-Yourub is a gem that search videos on youtebe using the YouTube API v3.
+Yourub is a gem for searching YouTube videos using the YouTube Data API v3.
 
 ## Installation
 
@@ -28,10 +26,8 @@ rails app,  create a app/config/yourub.yml file as follow:
 ```
 yourub_defaults: &yourub_defaults
   developer_key: 'YoUrDevEl0PerKey'
-  youtube_api_service_name: 'youtube'
-  youtube_api_version: 'v3'
   application_name: "yourub"
-  application_version: "0.1"
+  application_version: "0.2"
   log_level: WARN
 
 development:
@@ -45,7 +41,8 @@ test:
 ```
 
 If you want to use it from the console, or in another program, you can simply
-pass an hash containing the needed options
+pass an hash containing the needed options. Change 'yourub' with the name of your application.
+
 ```ruby
 options = { developer_key: 'mySecretKey',
              application_name: 'yourub',
@@ -58,18 +55,21 @@ client = Yourub::Client.new(options)
 
 ### Examples
 
-For example, to find the most recent videos in the category "sports" in Germany
+**`search`** always requires a non-empty `:query` (YouTube `search.list` uses the `q` parameter). Optional filters narrow results.
+
+Recent sports-related videos in Germany (category is matched by **name**, see below):
+
 ```ruby
-client = Yourub::Client.new
-client.search(country: "DE", category: "sports", order: 'date') do |v|
+client = Yourub::Client.new(developer_key: "…", application_name: "yourub", application_version: "1.0")
+client.search(query: "highlights", country: "DE", category: "sports", order: "date") do |v|
   puts v
 end
 ```
 
-To find video for a specific thema, use the parameter query
+Search by text only (optional `country` sets `regionCode` on the API request):
 
 ```ruby
-client = Yourub::Client.new
+client = Yourub::Client.new(developer_key: "…", application_name: "yourub", application_version: "1.0")
 client.search(query: "aliens") do |v|
   puts v
 end
@@ -79,59 +79,65 @@ that is the content of the response:
 [{"kind"=>"youtube#video", "etag"=>"\"N5Eg36Gl054SUNiWWc-Su3t5O-k/U6AzLXvcnZt2WFqpnq9_dksV7DA\"", "id"=>"NisCkxU544c", "snippet"=>{"publishedAt"=>"2009-04-05T05:20:10.000Z", "channelId"=>"UCCHcEUksSVKsRDH86j77Ntg", "title"=>"Like A Boss (ft. Seth Rogen) - Uncensored Version", "description"=>"http://www.itunes.com/thelonelyisland\r\n\r\nThe new single from The Lonely Island's debut album \"INCREDIBAD\" In stores now!\r\n\r\nFeaturing Seth Rogen.\r\n\r\nThe Lonely Island is Andy Samberg, Akiva Schaffer & Jorma Taccone.", "thumbnails"=>{"default"=>{"url"=>"https://i1.ytimg.com/vi/NisCkxU544c/default.jpg", "width"=>120, "height"=>90}, "medium"=>{"url"=>"https://i1.ytimg.com/vi/NisCkxU544c/mqdefault.jpg", "width"=>320, "height"=>180}, "high"=>{"url"=>"https://i1.ytimg.com/vi/NisCkxU544c/hqdefault.jpg", "width"=>480, "height"=>360}, "standard"=>{"url"=>"https://i1.ytimg.com/vi/NisCkxU544c/sddefault.jpg", "width"=>640, "height"=>480}, "maxres"=>{"url"=>"https://i1.ytimg.com/vi/NisCkxU544c/maxresdefault.jpg", "width"=>1280, "height"=>720}}, "channelTitle"=>"thelonelyisland", "categoryId"=>"23", "liveBroadcastContent"=>"none"}, "statistics"=>{"viewCount"=>"120176425", "likeCount"=>"594592", "dislikeCount"=>"15121", "favoriteCount"=>"0", "commentCount"=>"208109"}}]
 ```
 ### Available parameters
-`:query` String, example `aliens`
 
-`:country` String, one or more alpha-2 country codes [ISO 3166-1](http://www.iso.org/iso/country_codes/iso_3166_code_lists/country_names_and_code_elements.htm), example `US` or `IT, DE`. The default one is `US`
+`:query` — **Required.** Non-empty string (after stripping whitespace). Sent as YouTube **`q`**.
 
-`:category` String, example `comedy`. It accept the wildcard `all`, that retrieves videos for all the category for the given nation, or the default one (US) if no one is given
+`:country` — Optional. One or more [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) codes, e.g. `"US"` or `"IT,DE"`. Each code is applied as **`regionCode`** on `search.list`. Codes are validated against `Yourub::CountryCodes::ISO_3166_1_ALPHA2` (also exposed as `Yourub::Validator::COUNTRIES` / `client.countries`).
 
-`:count_filter` Hash, example `{views: ">= 100"}` or `{views: "== 600"}`
+`:category` — Optional. If the name of a category is set, Yourub resolves a category_id from the name: it calls `list_video_categories`, cached on the client), finds the first item whose title contains your string (case-insensitive). Omit `category` entirely when you do not want a category filter. If the name does not match any category, `ArgumentError` lists `id: title` lines of the available categories.
 
-`:max_results` Integer, between 1 and 50
+`:count_filter` — Optional hash, e.g. `{ views: ">= 100" }` or `{ views: "== 600" }` (applied after fetching full video resources).
 
-`:order` String, one of these: 'date', 'rating', 'relevance', 'title', 'videocount', 'viewcount'. The default one is `'relevance'`
+`:max_results` — Optional integer from 1 to 50.
 
-It's necessary at least one of this parameters to start a search: `:country`, `:category`, `:query`
+`:order` — Optional. One of: `date`, `rating`, `relevance`, `title`, `videoCount`, `viewCount`. Default `relevance`.
  
 ### Methods
-* `search`, search youtube videos for the given parameters
+* `search` — Runs a YouTube search and yields each video hash that passes optional filters. Requires `:query` and typically a block.
+
 ```ruby
-client = Yourub::Client.new
-client.search(query: "space missions")
+client = Yourub::Client.new(developer_key: "…", application_name: "yourub", application_version: "1.0")
+client.search(query: "space missions") { |v| puts v["id"] }
 ```
 
-* `get_views`
-it return the number of views for the given video id
+* `get` — Fetches one video’s metadata (`snippet` + `statistics`).
+
 ```ruby
-client = Yourub::Client.new
-client.get_views("G2b0OIkTraI")
+client = Yourub::Client.new(developer_key: "…", application_name: "yourub", application_version: "1.0")
+client.get("G2b0OIkTraI")
 ```
-* `get`
-retrieves all the metatags available for one
+
+* `list_video_categories`
+
+  Calls YouTube [`videoCategories.list`](https://developers.google.com/youtube/v3/docs/videoCategories/list) using only **`regionCode`** (via `region_code:`). The API does not use category IDs in this helper; you pass an [ISO 3166-1 alpha-2](https://www.iso.org/iso-3166-country-codes.html) region when you want that country’s category list.
+
+  **`region_code`:** Optional. If omitted or blank, the request is sent without `regionCode`, which matches the documented default catalog (United States).
+
+  **`hl`:** Optional. Sets the `hl` query parameter so snippet titles in the response use the requested locale (e.g. Spanish labels for Spain).
+
+  **Caching:** Responses are cached per client instance, keyed by `region_code` and `hl`, because category metadata changes rarely. Repeat calls with the same arguments return the same in-memory result without another HTTP request.
+
+  **Return value:** A `Google::Apis::YoutubeV3::VideoCategoryListResponse` (from `google-apis-youtube_v3`). Use `#items` to iterate categories (each has `#id` and `#snippet`).
+
 ```ruby
-client = Yourub::Client.new
-client.get("G2b0OIkTraI")
+client = Yourub::Client.new(options)
+
+# Default catalog (documented as US when region is not specified)
+us_like = client.list_video_categories
+
+# Explicit region
+de_categories = client.list_video_categories(region_code: "DE")
+
+# Region + localized labels
+es_labels = client.list_video_categories(region_code: "ES", hl: "es")
 ```
 
-## Supported Ruby Versions
-This gem [supports](https://travis-ci.org/edap/yourub) the following Ruby versions:
-
-* Ruby 1.9.3
-* Ruby 2.0.0
-* Ruby 2.1
-* Ruby 2.2
-* JRuby 1.7 (in Ruby 1.9 mode)
-
-##TODO
-Here there is a [list](https://developers.google.com/youtube/v3/docs/) of the available methods.
-Currently, this gem implements: [videos.list](https://developers.google.com/youtube/v3/docs/videos/list), [search.list](https://developers.google.com/youtube/v3/docs/search/list) and [videoCategories.list](https://developers.google.com/youtube/v3/docs/videoCategories/list).
-The next methods that will be implemented are [playlist.list](https://developers.google.com/youtube/v3/docs/playlists/list) and [channelis.list](https://developers.google.com/youtube/v3/docs/channels/list)
-## Contributing
-
-1. Fork it
-2. Create your feature branch (`git checkout -b my-new-feature`)
-3. Commit your changes (`git commit -am 'Add some feature'`)
-4. Run the test, run the spec/yourub/integration.rb file with a valid developer
-   key
-5. Push to the branch (`git push origin my-new-feature`)
-4. Create new Pull Request
+* `flush_video_categories_cache!`
+
+  Clears all cached `list_video_categories` results for this client. Call this if you need to force a fresh fetch (e.g. after a long-lived process or for tests).
+
+```ruby
+client.flush_video_categories_cache!
+```
+
+

data/config/yourub.yml

@@ -1,7 +1,5 @@
 yourub_defaults: &yourub_defaults
   developer_key: 'YourDeveloperKey'
-  youtube_api_service_name: 'youtube'
-  youtube_api_version: 'v3'
   application_name: "yourub"
   application_version: "0.1"
   log_level: WARN

data/lib/yourub/client.rb

@@ -1,8 +1,8 @@
 require 'yourub/meta_search'
-require 'google/api_client'
+require 'google/apis/youtube_v3'
 
 module Yourub
-  class Client < Google::APIClient
+  class Client
     include Yourub::MetaSearch
 
     attr_reader :videos
@@ -34,30 +34,106 @@ module Yourub
         Yourub::Config.override_config_file(options)
       end
 
-      args = {
-        :key => config.developer_key,
-        :application_name => config.application_name,
-        :application_version => config.application_version,
-        :authorization => nil
-      }
-      super(args)
+      @service = Google::Apis::YoutubeV3::YouTubeService.new
+      @service.key = config.developer_key
+      @service.client_options.application_name = config.application_name
+      @service.client_options.application_version = config.application_version
+      @video_categories_cache = {}
     end
 
-    # @return countries [Array] contain a list of the available alpha-2 country codes ISO 3166-1
     def countries
       Yourub::Validator.available_countries
     end
 
-    # it returns the youtube service object
-    # @see http://www.rubydoc.info/github/google/google-api-ruby-client/Google/APIClient#discovered_api-instance_method
-    def youtube_api
-      @youtube_api ||= self.discovered_api(
-        config.youtube_api_service_name, config.youtube_api_version
-      )
+    def list_video_categories(region_code: nil, hl: nil)
+      key = video_categories_cache_key(region_code, hl)
+      return @video_categories_cache[key] if @video_categories_cache.key?(key)
+
+      part = "snippet"
+      kwargs = {}
+      unless region_code.nil? || region_code.to_s.strip.empty?
+        kwargs[:region_code] = region_code.to_s.strip.upcase
+      end
+      kwargs[:hl] = hl.to_s.strip if hl && !hl.to_s.strip.empty?
+
+      @video_categories_cache[key] = @service.list_video_categories(part, **kwargs)
+    end
+
+    def flush_video_categories_cache!
+      @video_categories_cache.clear
+    end
+
+    # Compatibility shim used by Yourub::REST::Request
+    def execute!(api_method:, parameters:)
+      case api_method
+      when :search_list
+        part = parameters.delete(:part) || parameters.delete('part') || 'snippet'
+        opts = normalize_search_params(parameters)
+        data = @service.list_searches(part, **opts)
+        OpenStruct.new(data: data, status: 200)
+      when :videos_list
+        part = parameters.delete(:part) || parameters.delete('part') || 'snippet'
+        opts = normalize_videos_params(parameters)
+        data = @service.list_videos(part, **opts)
+        OpenStruct.new(data: data, status: 200)
+      when :video_categories_list
+        part = parameters.delete(:part) || parameters.delete('part') || 'snippet'
+        opts = normalize_categories_params(parameters)
+        data = @service.list_video_categories(part, **opts)
+        OpenStruct.new(data: data, status: 200)
+      else
+        raise ArgumentError, "Unsupported api_method #{api_method.inspect}"
+      end
     end
 
     def config
       Yourub::Config
     end
+
+    private
+
+    def video_categories_cache_key(region_code, hl)
+      region = if region_code.nil? || region_code.to_s.strip.empty?
+                 "_default"
+               else
+                 region_code.to_s.strip.upcase
+               end
+      hl_part = (hl.nil? || hl.to_s.strip.empty?) ? "" : hl.to_s.strip
+      "#{region}\0#{hl_part}"
+    end
+
+    def normalize_search_params(params)
+      query = params[:q] || params['q'] || ""
+
+      transform_common_params(params).merge(
+        {
+         q: query,
+         type: params[:type] || params['type'],
+         order: params[:order] || params['order'],
+         safe_search: params[:safeSearch] || params['safeSearch']
+        }.compact
+      )
+    end
+
+    def normalize_videos_params(params)
+      transform_common_params(params).merge(
+        {
+          id: params[:id] || params['id'],
+          fields: params[:fields] || params['fields']
+        }.compact
+      )
+    end
+
+    def normalize_categories_params(params)
+      transform_common_params(params)
+    end
+
+    def transform_common_params(params)
+      {
+        max_results: params[:maxResults] || params['maxResults'],
+        region_code: params[:regionCode] || params['regionCode'],
+        video_category_id: params[:videoCategoryId] || params['videoCategoryId']
+      }.compact
+    end
   end
 end

data/lib/yourub/config.rb

@@ -9,17 +9,18 @@ module Yourub
       extend Forwardable
       attr_accessor :config
 
-      def_delegators :@config, :developer_key,:youtube_api_service_name, :log_level,
-                    :youtube_api_version, :application_name, :application_version
+      def_delegators :@config, :developer_key, :log_level,
+                    :application_name, :application_version
 
       MANDATORY_KEYS = [:developer_key, :application_name, :application_version, :log_level]
 
-      # It loads the configuration file
-      # this method is used in the railtie.rb and in the default.rb files
-      # @example
-      #   Yourub::Config.load!(File.join("config", "yourub.yml"), 'yourub_defaults')
+      # Only these keys are read from YAML or from +Client.new(opts)+. The API is always
+      # YouTube Data API v3 via google-apis-youtube_v3 (+YouTubeService+).
+      USER_CONFIG_KEYS = %i[developer_key application_name application_version log_level].freeze
+
       def load!(file_path, environment)
-        @config = OpenStruct.new YAML.load_file(file_path)[environment]
+        raw = YAML.load_file(file_path)[environment]
+        @config = OpenStruct.new(prune_config_hash(raw))
       end
 
       def override_config_file(hash)
@@ -29,8 +30,15 @@ module Yourub
 
 private
 
+      def prune_config_hash(h)
+        return {} unless h.is_a?(Hash)
+
+        h.transform_keys { |k| k.to_sym }.slice(*USER_CONFIG_KEYS)
+      end
+
       def valid_options(hash)
-        opt = default_options.merge(hash)
+        normalized = hash.transform_keys { |k| k.to_sym }
+        opt = default_options.merge(normalized.slice(*USER_CONFIG_KEYS))
         raise ArgumentError.new(
           "please provide an hash containing at least a valid developer_key"
         ) if opt[:developer_key].empty?
@@ -40,8 +48,6 @@ private
       def default_options
         {
           developer_key: "",
-          youtube_api_service_name: "youtube",
-          youtube_api_version: "v3",
           application_name: "yourub",
           application_version: Yourub::VERSION,
           log_level: "WARN"

data/lib/yourub/country_codes.rb

@@ -0,0 +1,28 @@
+module Yourub
+  # ISO 3166-1 alpha-2 codes used for YouTube +regionCode+ style parameters.
+  #
+  # Derived from the +slim-2.csv+ dataset:
+  # https://github.com/lukes/ISO-3166-Countries-with-Regional-Codes (249 entries).
+  module CountryCodes
+    ISO_3166_1_ALPHA2 = %w[
+      AD AE AF AG AI AL AM AO AQ AR AS AT AU AW
+      AX AZ BA BB BD BE BF BG BH BI BJ BL BM BN
+      BO BQ BR BS BT BV BW BY BZ CA CC CD CF CG
+      CH CI CK CL CM CN CO CR CU CV CW CX CY CZ
+      DE DJ DK DM DO DZ EC EE EG EH ER ES ET FI
+      FJ FK FM FO FR GA GB GD GE GF GG GH GI GL
+      GM GN GP GQ GR GS GT GU GW GY HK HM HN HR
+      HT HU ID IE IL IM IN IO IQ IR IS IT JE JM
+      JO JP KE KG KH KI KM KN KP KR KW KY KZ LA
+      LB LC LI LK LR LS LT LU LV LY MA MC MD ME
+      MF MG MH MK ML MM MN MO MP MQ MR MS MT MU
+      MV MW MX MY MZ NA NC NE NF NG NI NL NO NP
+      NR NU NZ OM PA PE PF PG PH PK PL PM PN PR
+      PS PT PW PY QA RE RO RS RU RW SA SB SC SD
+      SE SG SH SI SJ SK SL SM SN SO SR SS ST SV
+      SX SY SZ TC TD TF TG TH TJ TK TL TM TN TO
+      TR TT TV TW TZ UA UG UM US UY UZ VA VC VE
+      VG VI VN VU WF WS YE YT ZA ZM ZW
+    ].freeze
+  end
+end

data/lib/yourub/meta_search.rb

@@ -11,35 +11,31 @@ module Yourub
     #   client.search(country: "DE", category: "sports", order: 'date')
     def search(criteria)
       begin
+        Yourub::CountFilter.filter = nil
+
         @api_options= {
           :part            => 'snippet',
           :type            => 'video',
           :order           => 'relevance',
           :safeSearch      => 'none',
-         }
+          :q               => nil
+        }
+
         @categories = []
         @count_filter = {}
+
+        @api_options[:q] = criteria[:query] if criteria[:query]
+
         @criteria = Yourub::Validator.confirm(criteria)
         search_by_criteria do |result|
           yield result
         end
       rescue ArgumentError => e
         Yourub.logger.error "#{e}"
+        raise
       end
     end
 
-    # return the number of times a video was watched
-    # @param video_id[Integer]
-    # @example
-    #   client = Yourub::Client.new
-    #   client.get_views("G2b0OIkTraI")
-    def get_views(video_id)
-      params = { :id => video_id, :part => 'statistics' }
-      request = Yourub::REST::Videos.list(self,params)
-      v = Yourub::Result.format(request).first
-      v ? Yourub::CountFilter.get_views_count(v) : nil
-    end
-
     # return an hash containing the metadata for the given video
     # @param video_id[Integer]
     # @example
@@ -61,62 +57,84 @@ private
       end
     end
 
-    def merge_criteria_with_api_options
-      mappings = {query: :q, max_results: :maxResults, country: :regionCode}
-      @api_options.merge! @criteria
-      @api_options.keys.each do |k|
-        @api_options[ mappings[k] ] = @api_options.delete(k) if mappings[k]
-      end
-    end
 
-    def retrieve_categories
-      if @criteria.has_key? :category
-        @categories = Yourub::REST::Categories.for_country(self,@criteria[:country])
-        @categories = Yourub::Validator.valid_category(@categories, @criteria[:category])
-      end
-    end
-
-    def retrieve_videos
-      consume_criteria do |criteria|
-        begin
-          req = Yourub::REST::Search.list(self, criteria)
-          get_details_for_each_video(req) do |v|
-            yield v
-          end
-        rescue StandardError => e
-          Yourub.logger.error "Error #{e} retrieving videos for the criteria: #{criteria.to_s}"
-        end
-      end
+    def merge_criteria_with_api_options
+      @api_options[:q] = @criteria[:query] if @criteria[:query]
+      @api_options[:maxResults] = @criteria[:max_results] if @criteria[:max_results]
+      @api_options[:order] = @criteria[:order] if @criteria[:order]
     end
 
     def consume_criteria
-      to_consume = @api_options
       if @criteria[:country]
         @criteria[:country].each do |country|
+          to_consume = @api_options.dup
           to_consume[:regionCode] = country
           consume_categories(to_consume) do |cat|
             yield cat
           end
         end
       else
-        yield to_consume
+        consume_categories(@api_options.dup) do |cat|
+          yield cat
+        end
       end
     end
 
     def consume_categories(to_consume)
       if @categories.size > 0
         @categories.each do |cat|
-          to_consume[:videoCategoryId] = cat.keys[0].to_i
-          yield to_consume
+          current_params = to_consume.dup
+          current_params[:videoCategoryId] = cat.keys[0].to_i
+          yield current_params
         end
       else
         yield to_consume
       end
     end
 
+    def retrieve_categories
+      return unless @criteria.key?(:category)
+
+      term = @criteria[:category].to_s.strip
+      if term.empty?
+        @categories = []
+        return
+      end
+
+      if term.casecmp("all").zero?
+        raise ArgumentError,
+              'category "all" is not supported; omit :category to search without a video category filter.'
+      end
+
+      region_code = region_code_for_category_catalog
+      list = list_video_categories(region_code: region_code)
+      items = video_category_list_items(list)
+      match = find_category_item_by_partial_name(items, term)
+      if match.nil?
+        raise ArgumentError, category_not_found_message(term, items)
+      end
+
+      cid = video_category_item_id(match)
+      @categories = [{ cid.to_s => term }]
+    end
+
+    def retrieve_videos
+      consume_criteria do |criteria|
+        begin
+          req = Yourub::REST::Search.list(self, criteria)
+          get_details_for_each_video(req) do |v|
+            yield v
+          end
+        rescue StandardError => e
+          Yourub.logger.error "Error #{e} retrieving videos for the criteria: #{criteria.to_s}"
+        end
+      end
+    end
+
+
     def get_details_for_each_video(video_list)
       video_list.data.items.each do |video_item|
-        v = Yourub::REST::Videos.single_video(self, video_item.id.videoId)
+        v = Yourub::REST::Videos.single_video(self, video_item.id.video_id)
         v = Yourub::Result.format(v)
         if v && Yourub::CountFilter.accept?(v.first)
           yield v.first
@@ -130,5 +148,60 @@ private
       end
     end
 
+    def region_code_for_category_catalog
+      return nil unless @criteria[:country].is_a?(Array) && @criteria[:country].any?
+
+      @criteria[:country].first
+    end
+
+    def video_category_list_items(list)
+      raw =
+        if list.respond_to?(:items)
+          list.items
+        elsif list.is_a?(Hash)
+          list["items"]
+        end
+      Array(raw)
+    end
+
+    def find_category_item_by_partial_name(items, search_term)
+      needle = search_term.to_s.strip.downcase
+      return nil if needle.empty?
+
+      items.find do |item|
+        title = video_category_item_title(item).to_s.downcase
+        title.include?(needle)
+      end
+    end
+
+    def video_category_item_title(item)
+      if item.respond_to?(:snippet) && item.snippet.respond_to?(:title)
+        item.snippet.title
+      elsif item.is_a?(Hash)
+        item.dig("snippet", "title")
+      else
+        ""
+      end
+    end
+
+    def video_category_item_id(item)
+      if item.respond_to?(:id)
+        id = item.id
+        id.is_a?(Hash) ? id["videoId"] || id[:videoId] : id
+      elsif item.is_a?(Hash)
+        item["id"]
+      end
+    end
+
+    def category_not_found_message(term, items)
+      lines = items.map do |it|
+        "#{video_category_item_id(it)}: #{video_category_item_title(it)}"
+      end
+      <<~MSG.chomp
+        category not found, this is the list of the available categories:
+        #{lines.join("\n")}
+      MSG
+    end
+
   end
 end