searchapi 1.0.0

data/lib/searchapi/google_search_options.rb

@@ -0,0 +1,67 @@
+module SearchAPI
+  class GoogleSearchOptions
+    include DynamicSchema::Definable
+    include Helpers
+
+    DEVICES = %w[ desktop mobile tablet ]
+    SAFE_SEARCH = %w[ active off ]
+    TIME_PERIODS = %w[ last_hour last_day last_week last_month last_year ]
+    OPTIMIZATION_STRATEGIES = %w[ performance ads ]
+
+    NORMALIZE_DOWNCASE = ->(v) { v.to_s.downcase }
+
+    schema do
+      # search query (q or kgmid required)
+      q                       String
+      kgmid                   String
+
+      # device
+      device                  String, in: DEVICES, normalize: NORMALIZE_DOWNCASE
+
+      # geographic location
+      location                String
+      uule                    String
+
+      # localization
+      google_domain           String
+      gl                      String
+      hl                      String
+      lr                      String
+      cr                      String
+
+      # filters
+      nfpr                    String
+      filter                  String
+      safe                    String, in: SAFE_SEARCH, normalize: NORMALIZE_DOWNCASE
+      time_period             String, in: TIME_PERIODS, normalize: NORMALIZE_DOWNCASE
+      time_period_min         String
+      time_period_max         String
+
+      # pagination
+      page                    Integer
+
+      # optimization
+      optimization_strategy   String, in: OPTIMIZATION_STRATEGIES, normalize: NORMALIZE_DOWNCASE
+    end
+
+    def self.build( options = nil, &block )
+      new( api_options: builder.build( options, &block ) )
+    end
+
+    def self.build!( options = nil, &block )
+      new( api_options: builder.build!( options, &block ) )
+    end
+
+    def initialize( options = {}, api_options: nil )
+      @options = self.class.builder.build( options || {} )
+      @options = api_options.merge( @options ) if api_options
+    end
+
+    def to_h
+      result = @options.to_h
+      result[ :engine ] = 'google'
+      result
+    end
+
+  end
+end

data/lib/searchapi/google_search_request.rb

@@ -0,0 +1,26 @@
+module SearchAPI
+  class GoogleSearchRequest < Request
+
+    def search( query = nil, options = nil, &block )
+      if options
+        options = options.is_a?( GoogleSearchOptions ) ? options : GoogleSearchOptions.build!( options.to_h )
+        options = options.to_h
+      else
+        options = { engine: 'google' }
+      end
+      options[ :q ] = query.to_s if query
+
+      response = get( "#{ BASE_URI }/search", options, &block )
+      attributes = ( JSON.parse( response.body, symbolize_names: true ) rescue nil )
+
+      result = if response.success?
+        GoogleSearchResult.new( attributes || {} )
+      else
+        ErrorResult.new( response.status, attributes )
+      end
+
+      ResponseMethods.install( response, result )
+    end
+
+  end
+end

data/lib/searchapi/google_search_result.rb

@@ -0,0 +1,301 @@
+require 'forwardable'
+
+module SearchAPI
+
+  # Search metadata
+  GoogleSearchMetadataSchema = DynamicSchema::Struct.define do
+    id                    String
+    status                String
+    created_at            String, as: :created_at
+    request_time_taken    Float, as: :request_time_taken
+    parsing_time_taken    Float, as: :parsing_time_taken
+    total_time_taken      Float, as: :total_time_taken
+  end
+
+  class GoogleSearchMetadata < GoogleSearchMetadataSchema
+  end
+
+  # Search parameters
+  GoogleSearchParametersSchema = DynamicSchema::Struct.define do
+    engine                String
+    q                     String
+    kgmid                 String
+    location              String
+    location_used         String, as: :location_used
+    uule                  String
+    google_domain         String, as: :google_domain
+    hl                    String
+    gl                    String
+    lr                    String
+    cr                    String
+    device                String
+    page                  Integer
+    num                   Integer
+    safe                  String
+    filter                String
+    nfpr                  String
+    time_period           String, as: :time_period
+    time_period_min       String, as: :time_period_min
+    time_period_max       String, as: :time_period_max
+    optimization_strategy String, as: :optimization_strategy
+  end
+
+  class GoogleSearchParameters < GoogleSearchParametersSchema
+  end
+
+  # Search information
+  GoogleSearchInformationSchema = DynamicSchema::Struct.define do
+    query_displayed       String, as: :query_displayed
+    total_results         Integer, as: :total_results
+    page                  Integer
+    time_taken_displayed  String, as: :time_taken_displayed
+    detected_location     String, as: :detected_location
+    did_you_mean          String, as: :did_you_mean
+  end
+
+  class GoogleSearchInformation < GoogleSearchInformationSchema
+  end
+
+  # Organic result sitelinks
+  GoogleSitelinkSchema = DynamicSchema::Struct.define do
+    title                 String
+    link                  String
+  end
+
+  class GoogleSitelink < GoogleSitelinkSchema
+  end
+
+  # Organic result
+  GoogleOrganicResultSchema = DynamicSchema::Struct.define do
+    position              Integer
+    title                 String
+    link                  String
+    displayed_link        String, as: :displayed_link
+    favicon               String
+    snippet               String
+    snippet_highlighted_words String, array: true, as: :snippet_highlighted_words
+    date                  String
+    sitelinks             GoogleSitelink, array: true
+    source                String
+  end
+
+  class GoogleOrganicResult < GoogleOrganicResultSchema
+  end
+
+  # Ad result
+  GoogleAdSchema = DynamicSchema::Struct.define do
+    position              Integer
+    title                 String
+    link                  String
+    displayed_link        String, as: :displayed_link
+    tracking_link         String, as: :tracking_link
+    description           String
+    sitelinks             GoogleSitelink, array: true
+  end
+
+  class GoogleAd < GoogleAdSchema
+  end
+
+  # Shopping ad
+  GoogleShoppingAdSchema = DynamicSchema::Struct.define do
+    position              Integer
+    title                 String
+    link                  String
+    source                String
+    price                 String
+    rating                Float
+    reviews               Integer
+    thumbnail             String
+  end
+
+  class GoogleShoppingAd < GoogleShoppingAdSchema
+  end
+
+  # Knowledge graph
+  GoogleKnowledgeGraphSchema = DynamicSchema::Struct.define do
+    title                 String
+    type                  String
+    description           String
+    source                Hash
+    image                 String
+    attributes            Hash
+  end
+
+  class GoogleKnowledgeGraph < GoogleKnowledgeGraphSchema
+  end
+
+  # Related question
+  GoogleRelatedQuestionSchema = DynamicSchema::Struct.define do
+    question              String
+    answer                String
+    title                 String
+    link                  String
+    displayed_link        String, as: :displayed_link
+  end
+
+  class GoogleRelatedQuestion < GoogleRelatedQuestionSchema
+  end
+
+  # Related search
+  GoogleRelatedSearchSchema = DynamicSchema::Struct.define do
+    query                 String
+    link                  String
+  end
+
+  class GoogleRelatedSearch < GoogleRelatedSearchSchema
+  end
+
+  # Video result
+  GoogleVideoSchema = DynamicSchema::Struct.define do
+    position              Integer
+    title                 String
+    link                  String
+    source                String
+    channel               String
+    date                  String
+    duration              String
+    thumbnail             String
+  end
+
+  class GoogleVideo < GoogleVideoSchema
+  end
+
+  # Top story
+  GoogleTopStorySchema = DynamicSchema::Struct.define do
+    title                 String
+    link                  String
+    source                String
+    date                  String
+    thumbnail             String
+  end
+
+  class GoogleTopStory < GoogleTopStorySchema
+  end
+
+  # Local result
+  GoogleLocalResultSchema = DynamicSchema::Struct.define do
+    position              Integer
+    title                 String
+    place_id              String, as: :place_id
+    data_cid              String, as: :data_cid
+    rating                Float
+    reviews               Integer
+    price                 String
+    type                  String
+    address               String
+    hours                 String
+    phone                 String
+    website               String
+    thumbnail             String
+    gps_coordinates       Hash, as: :gps_coordinates
+  end
+
+  class GoogleLocalResult < GoogleLocalResultSchema
+  end
+
+  # Pagination
+  GooglePaginationSchema = DynamicSchema::Struct.define do
+    current               Integer
+    _value                :next, type: Integer
+    previous              Integer
+  end
+
+  class GooglePagination < GooglePaginationSchema
+  end
+
+  # AI Overview reference link
+  GoogleAIOverviewReferenceSchema = DynamicSchema::Struct.define do
+    link                  String
+    title                 String
+    source                String
+  end
+
+  class GoogleAIOverviewReference < GoogleAIOverviewReferenceSchema
+  end
+
+  # AI Overview text block
+  GoogleAIOverviewTextBlockSchema = DynamicSchema::Struct.define do
+    text                  String
+    position              Integer
+  end
+
+  class GoogleAIOverviewTextBlock < GoogleAIOverviewTextBlockSchema
+  end
+
+  # AI Overview
+  GoogleAIOverviewSchema = DynamicSchema::Struct.define do
+    text_blocks           GoogleAIOverviewTextBlock, array: true, as: :text_blocks
+    markdown              String
+    reference_links       GoogleAIOverviewReference, array: true, as: :reference_links
+    error                 String
+  end
+
+  class GoogleAIOverview < GoogleAIOverviewSchema
+  end
+
+  # Answer box
+  GoogleAnswerBoxSchema = DynamicSchema::Struct.define do
+    type                  String
+    title                 String
+    answer                String
+    link                  String
+    snippet               String
+    date                  String
+    thumbnail             String
+  end
+
+  class GoogleAnswerBox < GoogleAnswerBoxSchema
+  end
+
+  # Inline image
+  GoogleInlineImageSchema = DynamicSchema::Struct.define do
+    title                 String
+    source                String
+    link                  String
+    thumbnail             String
+    original              String
+  end
+
+  class GoogleInlineImage < GoogleInlineImageSchema
+  end
+
+  # Inline images container
+  GoogleInlineImagesSchema = DynamicSchema::Struct.define do
+    images                GoogleInlineImage, array: true
+    more_link             String, as: :more_link
+  end
+
+  class GoogleInlineImages < GoogleInlineImagesSchema
+  end
+
+  # Main search result
+  GoogleSearchResultSchema = DynamicSchema::Struct.define do
+    search_metadata       GoogleSearchMetadata, as: :search_metadata
+    search_parameters     GoogleSearchParameters, as: :search_parameters
+    search_information    GoogleSearchInformation, as: :search_information
+    ai_overview           GoogleAIOverview, as: :ai_overview
+    answer_box            GoogleAnswerBox, as: :answer_box
+    knowledge_graph       GoogleKnowledgeGraph, as: :knowledge_graph
+    ads                   GoogleAd, array: true
+    shopping_ads          GoogleShoppingAd, array: true, as: :shopping_ads
+    organic_results       GoogleOrganicResult, array: true, as: :organic_results
+    related_questions     GoogleRelatedQuestion, array: true, as: :related_questions
+    inline_videos         GoogleVideo, array: true, as: :inline_videos
+    top_stories           GoogleTopStory, array: true, as: :top_stories
+    local_results         GoogleLocalResult, array: true, as: :local_results
+    related_searches      GoogleRelatedSearch, array: true, as: :related_searches
+    pagination            GooglePagination
+  end
+
+  class GoogleSearchResult < GoogleSearchResultSchema
+    extend Forwardable
+    include Enumerable
+
+    def_delegators :organic_results, :each, :[], :count, :size, :length, :first, :last, :empty?
+
+    def success?
+      true
+    end
+  end
+
+end

data/lib/searchapi/helpers.rb

@@ -0,0 +1,10 @@
+module SearchAPI
+  module Helpers
+
+    def string_camelize( string )
+      words = string.split( /[\s_\-]/ )
+      words.map.with_index { | word, index | index.zero? ? word.downcase : word.capitalize }.join
+    end
+
+  end
+end

data/lib/searchapi/instagram_profile_options.rb

@@ -0,0 +1,31 @@
+module SearchAPI
+  class InstagramProfileOptions
+    include DynamicSchema::Definable
+    include Helpers
+
+    schema do
+      # required
+      username              String
+    end
+
+    def self.build( options = nil, &block )
+      new( api_options: builder.build( options, &block ) )
+    end
+
+    def self.build!( options = nil, &block )
+      new( api_options: builder.build!( options, &block ) )
+    end
+
+    def initialize( options = {}, api_options: nil )
+      @options = self.class.builder.build( options || {} )
+      @options = api_options.merge( @options ) if api_options
+    end
+
+    def to_h
+      result = @options.to_h
+      result[ :engine ] = 'instagram_profile'
+      result
+    end
+
+  end
+end

data/lib/searchapi/instagram_profile_request.rb

@@ -0,0 +1,26 @@
+module SearchAPI
+  class InstagramProfileRequest < Request
+
+    def profile( username, options = nil, &block )
+      if options
+        options = options.is_a?( InstagramProfileOptions ) ? options : InstagramProfileOptions.build!( options.to_h )
+        options = options.to_h
+      else
+        options = { engine: 'instagram_profile' }
+      end
+      options[ :username ] = username.to_s
+
+      response = get( "#{ BASE_URI }/search", options, &block )
+      attributes = ( JSON.parse( response.body, symbolize_names: true ) rescue nil )
+
+      result = if response.success?
+        InstagramProfileResult.new( attributes || {} )
+      else
+        ErrorResult.new( response.status, attributes )
+      end
+
+      ResponseMethods.install( response, result )
+    end
+
+  end
+end

data/lib/searchapi/instagram_profile_result.rb

@@ -0,0 +1,117 @@
+require 'forwardable'
+
+module SearchAPI
+
+  # Instagram Search metadata
+  InstagramProfileMetadataSchema = DynamicSchema::Struct.define do
+    id                    String
+    status                String
+    created_at            String, as: :created_at
+    request_time_taken    Float, as: :request_time_taken
+    parsing_time_taken    Float, as: :parsing_time_taken
+    total_time_taken      Float, as: :total_time_taken
+  end
+
+  class InstagramProfileMetadata < InstagramProfileMetadataSchema
+  end
+
+  # Instagram Search parameters
+  InstagramProfileParametersSchema = DynamicSchema::Struct.define do
+    engine                String
+    username              String
+  end
+
+  class InstagramProfileParameters < InstagramProfileParametersSchema
+  end
+
+  # Bio link
+  InstagramBioLinkSchema = DynamicSchema::Struct.define do
+    title                 String
+    url                   String
+  end
+
+  class InstagramBioLink < InstagramBioLinkSchema
+  end
+
+  # Tagged user
+  InstagramTaggedUserSchema = DynamicSchema::Struct.define do
+    username              String
+    x                     Float
+    y                     Float
+  end
+
+  class InstagramTaggedUser < InstagramTaggedUserSchema
+  end
+
+  # Carousel item
+  InstagramCarouselItemSchema = DynamicSchema::Struct.define do
+    type                  String
+    link                  String
+    width                 Integer
+    height                Integer
+    thumbnail             String
+  end
+
+  class InstagramCarouselItem < InstagramCarouselItemSchema
+  end
+
+  # Post
+  InstagramPostSchema = DynamicSchema::Struct.define do
+    position              Integer
+    id                    String
+    permalink             String
+    type                  String
+    link                  String
+    width                 Integer
+    height                Integer
+    thumbnail             String
+    caption               String
+    likes                 Integer
+    comments              Integer
+    iso_date              String, as: :iso_date
+    tagged_users          InstagramTaggedUser, array: true, as: :tagged_users
+    carousel_items        InstagramCarouselItem, array: true, as: :carousel_items
+  end
+
+  class InstagramPost < InstagramPostSchema
+  end
+
+  # Profile
+  InstagramProfileSchema = DynamicSchema::Struct.define do
+    username              String
+    name                  String
+    bio                   String
+    avatar                String
+    avatar_hd             String, as: :avatar_hd
+    is_verified           [ TrueClass, FalseClass ], as: :is_verified
+    is_business           [ TrueClass, FalseClass ], as: :is_business
+    posts                 Integer
+    followers             Integer
+    following             Integer
+    external_link         String, as: :external_link
+    bio_links             InstagramBioLink, array: true, as: :bio_links
+  end
+
+  class InstagramProfile < InstagramProfileSchema
+  end
+
+  # Main Instagram profile result
+  InstagramProfileResultSchema = DynamicSchema::Struct.define do
+    search_metadata       InstagramProfileMetadata, as: :search_metadata
+    search_parameters     InstagramProfileParameters, as: :search_parameters
+    profile               InstagramProfile
+    posts                 InstagramPost, array: true
+    error                 String
+  end
+
+  class InstagramProfileResult < InstagramProfileResultSchema
+    extend Forwardable
+
+    def_delegators :profile, :username, :name, :bio, :avatar, :followers, :following
+
+    def success?
+      self.error.nil?
+    end
+  end
+
+end

data/lib/searchapi/module_methods.rb

@@ -0,0 +1,80 @@
+module SearchAPI
+  module ModuleMethods
+
+    def connection( connection = nil )
+      @connection = connection if connection
+      @connection ||= Faraday.new { | builder | builder.adapter Faraday.default_adapter }
+    end
+
+    def api_key( api_key = nil )
+      @api_key = api_key || @api_key
+      @api_key
+    end
+
+    # Google Search
+    def google( query = nil, options = nil, &block )
+      GoogleSearchRequest.new.search( query, options, &block )
+    end
+
+    # YouTube Search
+    def youtube( query, options = nil, &block )
+      YouTubeSearchRequest.new.search( query, options, &block )
+    end
+
+    # Instagram Profile
+    def instagram( username, options = nil, &block )
+      InstagramProfileRequest.new.profile( username, options, &block )
+    end
+
+    # TikTok Profile
+    def tiktok( username, options = nil, &block )
+      TikTokProfileRequest.new.profile( username, options, &block )
+    end
+
+    # Google Finance
+    def finance( symbol, options = nil, &block )
+      GoogleFinanceRequest.new.quote( symbol, options, &block )
+    end
+
+    # Google Flights
+    def flights( options = nil, &block )
+      GoogleFlightsRequest.new.search( options, &block )
+    end
+
+    # Google Light (fast, lightweight search)
+    def google_light( query, options = nil, &block )
+      GoogleLightRequest.new.search( query, options, &block )
+    end
+
+    # Google News
+    def news( query, options = nil, &block )
+      GoogleNewsRequest.new.search( query, options, &block )
+    end
+
+    # Google News Portal
+    def news_portal( query = nil, options = nil, &block )
+      GoogleNewsPortalRequest.new.search( query, options, &block )
+    end
+
+    # Google News Light
+    def news_light( query, options = nil, &block )
+      GoogleNewsLightRequest.new.search( query, options, &block )
+    end
+
+    # Google Images
+    def images( query, options = nil, &block )
+      GoogleImagesRequest.new.search( query, options, &block )
+    end
+
+    # Google Local
+    def local( query, options = nil, &block )
+      GoogleLocalRequest.new.search( query, options, &block )
+    end
+
+    # Google Scholar
+    def scholar( query = nil, options = nil, &block )
+      GoogleScholarRequest.new.search( query, options, &block )
+    end
+
+  end
+end

data/lib/searchapi/request.rb

@@ -0,0 +1,25 @@
+module SearchAPI
+  class Request
+
+    BASE_URI = 'https://www.searchapi.io/api/v1'
+
+    def initialize( connection: nil, api_key: nil )
+      @connection = connection || SearchAPI.connection
+      @api_key = api_key || SearchAPI.api_key
+      raise ArgumentError,
+            "The API key is required but was not provided; configure it using " \
+            "'SearchAPI.api_key' or pass it directly." unless @api_key
+    end
+
+  protected
+
+    def get( uri, params = {}, &block )
+      @connection.get( uri ) do | request |
+        request.headers[ 'Authorization' ] = "Bearer #{ @api_key }"
+        request.params = params unless params.empty?
+        block.call( request ) if block
+      end
+    end
+
+  end
+end

data/lib/searchapi/response_methods.rb

@@ -0,0 +1,14 @@
+module SearchAPI
+  module ResponseMethods
+
+    def self.install( response, result )
+      response.instance_variable_set( "@_searchapi_result", result )
+      response.extend( ResponseMethods )
+    end
+
+    def result
+      @_searchapi_result
+    end
+
+  end
+end