searchapi 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d08a566b8b60588ec83cfb8c18f535de5fe329325dfafb1d8120a61f105afeac
+  data.tar.gz: 4a59d8ca1b3921e1d419abd37789ca5098b61f4dd0a5465c1674b76445cff156
+SHA512:
+  metadata.gz: 680bf0570d6b8b814cf7256c5bc3df04d0a3e60f3c38cc7ff420044a51e15836835c8b40ead4c8a613c69016512206cc8f72fe41602124127b8130883d1408bd
+  data.tar.gz: 1dc489acd03a4540dcf63121ae4c4ece11f550f795c0e86a6f4326420c263dee4b0ac0bfc92b805ede693c24232f6d62dbf135bbb64424177963d52c342a7e45

data/README.md

@@ -0,0 +1,175 @@
+# SearchAPI Ruby Gem
+
+A Ruby client for the [SearchAPI.io](https://searchapi.io) API, providing access to Google Search, YouTube, Instagram, TikTok, and more.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'searchapi'
+```
+
+Or install directly:
+
+```bash
+gem install searchapi
+```
+
+## Configuration
+
+```ruby
+require 'searchapi'
+
+SearchAPI.api_key ENV['SEARCH_API_KEY']
+```
+
+## Available APIs
+
+| API | Method | Description |
+|-----|--------|-------------|
+| Google Search | `SearchAPI.google(query)` | Full Google search with all features |
+| Google Light | `SearchAPI.google_light(query)` | Fast, lightweight Google search |
+| Google News | `SearchAPI.news(query)` | Google News articles |
+| Google News Portal | `SearchAPI.news_portal(query)` | Google News Portal with topics |
+| Google News Light | `SearchAPI.news_light(query)` | Fast, lightweight news search |
+| Google Images | `SearchAPI.images(query)` | Google Image search |
+| Google Local | `SearchAPI.local(query)` | Local business search |
+| Google Scholar | `SearchAPI.scholar(query)` | Academic papers and citations |
+| Google Finance | `SearchAPI.finance(symbol)` | Stock quotes and financial data |
+| Google Flights | `SearchAPI.flights(options)` | Flight search and booking |
+| YouTube | `SearchAPI.youtube(query)` | YouTube video search |
+| Instagram | `SearchAPI.instagram(username)` | Instagram profile data |
+| TikTok | `SearchAPI.tiktok(username)` | TikTok profile data |
+
+## Quick Examples
+
+### Google Search
+
+```ruby
+response = SearchAPI.google('ruby programming')
+response.result.organic_results.each do |result|
+  puts "#{ result.title } - #{ result.link }"
+end
+```
+
+### Google News
+
+```ruby
+response = SearchAPI.news('technology', time_period: :last_week)
+response.result.each do |article|
+  puts "#{ article.title } (#{ article.source })"
+end
+```
+
+### Google Images
+
+```ruby
+response = SearchAPI.images('sunset', size: :large, color: :orange)
+response.result.each do |image|
+  puts "#{ image.title } - #{ image.original.link }"
+end
+```
+
+### Google Finance
+
+```ruby
+response = SearchAPI.finance('AAPL:NASDAQ')
+puts "#{ response.result.summary.title }: $#{ response.result.summary.price }"
+```
+
+### Google Flights
+
+```ruby
+options = SearchAPI::GoogleFlightsOptions.build do
+  departure_id 'JFK'
+  arrival_id 'LAX'
+  outbound_date '2026-06-15'
+  flight_type :one_way
+end
+
+response = SearchAPI.flights(options)
+puts "Cheapest: $#{ response.result.cheapest&.price }"
+```
+
+### YouTube Search
+
+```ruby
+response = SearchAPI.youtube('ruby tutorial')
+response.result.videos.each do |video|
+  puts "#{ video.title } by #{ video.channel.title }"
+end
+```
+
+### Social Media Profiles
+
+```ruby
+# Instagram
+response = SearchAPI.instagram('instagram')
+puts "#{ response.result.profile.username }: #{ response.result.followers } followers"
+
+# TikTok
+response = SearchAPI.tiktok('tiktok')
+puts "#{ response.result.profile.name }: #{ response.result.hearts } hearts"
+```
+
+## Using Options
+
+Each API supports options via a block or hash:
+
+```ruby
+# Block syntax
+options = SearchAPI::GoogleSearchOptions.build do
+  device :mobile
+  gl 'us'
+  hl 'en'
+  time_period :last_week
+end
+response = SearchAPI.google('news', options)
+
+# Hash syntax
+response = SearchAPI.google('news', { device: :mobile, gl: 'us' })
+```
+
+Options are case-insensitive and normalized automatically:
+
+```ruby
+# These are equivalent
+SearchAPI::GoogleFinanceOptions.build { window :'1d' }  # => '1D'
+SearchAPI::GoogleFinanceOptions.build { window :'1D' }  # => '1D'
+SearchAPI::GoogleFinanceOptions.build { window :MAX }   # => 'MAX'
+```
+
+## Response Structure
+
+All responses return a Faraday response with a `result` accessor:
+
+```ruby
+response = SearchAPI.google('test')
+response.success?        # HTTP success
+response.result.success? # API success (no error field)
+response.result.search_metadata
+response.result.search_parameters
+response.result.organic_results
+```
+
+Results are enumerable where it makes sense:
+
+```ruby
+response = SearchAPI.google('ruby')
+response.result.each { |r| puts r.title }  # Iterates organic_results
+response.result.first                       # First organic result
+response.result.count                       # Number of organic results
+```
+
+## Documentation
+
+See the `/readme` directory for detailed documentation on each API endpoint.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/EndlessInternational/searchapi](https://github.com/EndlessInternational/searchapi).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/bin/test

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+
+$LOAD_PATH.unshift File.expand_path( '../lib', __dir__ )
+$LOAD_PATH.unshift File.expand_path( '../test', __dir__ )
+
+test_files = if ARGV.empty?
+  Dir.glob( File.expand_path( '../test/**/*_test.rb', __dir__ ) )
+else
+  ARGV.map { | arg | File.expand_path( arg, Dir.pwd ) }
+end
+
+test_files.each { | file | require file }

data/lib/searchapi/error_result.rb

@@ -0,0 +1,50 @@
+module SearchAPI
+  class ErrorResult
+
+    attr_reader :error_type, :error_description
+
+    def initialize( status_code, attributes = nil )
+      @error_type, @error_description = status_code_to_error( status_code )
+      if attributes&.respond_to?( :[] ) && attributes[ :error ]
+        @error_description = attributes[ :error ]
+      end
+    end
+
+    def success?
+      false
+    end
+
+  private
+
+    def status_code_to_error( status_code )
+      case status_code
+      when 200
+        [ :unexpected_error,
+          "The response was successful but it did not include a valid payload." ]
+      when 400
+        [ :invalid_request_error,
+          "The request is invalid due to malformed parameters, malformed JSON, or " \
+          "missing required fields." ]
+      when 401
+        [ :authentication_error,
+          "The API key is missing or invalid." ]
+      when 403
+        [ :forbidden_error,
+          "The API key is valid but has insufficient permissions." ]
+      when 404
+        [ :not_found_error,
+          "The requested resource was not found." ]
+      when 429
+        [ :rate_limit_error,
+          "The rate limit has been exceeded." ]
+      when 500..599
+        [ :server_error,
+          "The SearchAPI server encountered an error while processing the request." ]
+      else
+        [ :unknown_error,
+          "The SearchAPI service returned an unexpected status code: '#{ status_code }'." ]
+      end
+    end
+
+  end
+end

data/lib/searchapi/google_finance_options.rb

@@ -0,0 +1,40 @@
+module SearchAPI
+  class GoogleFinanceOptions
+    include DynamicSchema::Definable
+    include Helpers
+
+    WINDOWS = %w[ 1D 5D 1M 6M YTD 1Y 5Y MAX ]
+    NORMALIZE_UPCASE = ->(v) { v.to_s.upcase }
+
+    schema do
+      # query (stock symbol, index, currency pair, etc.)
+      q                     String
+
+      # language
+      hl                    String
+
+      # time window for historical data
+      window                String, in: WINDOWS, normalize: NORMALIZE_UPCASE
+    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_finance'
+      result
+    end
+
+  end
+end

data/lib/searchapi/google_finance_request.rb

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

data/lib/searchapi/google_finance_result.rb

@@ -0,0 +1,262 @@
+require 'forwardable'
+
+module SearchAPI
+
+  # Google Finance Search metadata
+  GoogleFinanceMetadataSchema = 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
+    request_url           String, as: :request_url
+    html_url              String, as: :html_url
+    json_url              String, as: :json_url
+  end
+
+  class GoogleFinanceMetadata < GoogleFinanceMetadataSchema
+  end
+
+  # Google Finance Search parameters
+  GoogleFinanceParametersSchema = DynamicSchema::Struct.define do
+    engine                String
+    q                     String
+    hl                    String
+    window                String
+  end
+
+  class GoogleFinanceParameters < GoogleFinanceParametersSchema
+  end
+
+  # Price change
+  GoogleFinancePriceChangeSchema = DynamicSchema::Struct.define do
+    percentage            Float
+    amount                Float
+    movement              String
+  end
+
+  class GoogleFinancePriceChange < GoogleFinancePriceChangeSchema
+  end
+
+  # Summary
+  GoogleFinanceSummarySchema = DynamicSchema::Struct.define do
+    title                 String
+    stock                 String
+    exchange              String
+    price                 Float
+    currency              String
+    date                  String
+    price_change          GoogleFinancePriceChange, as: :price_change
+  end
+
+  class GoogleFinanceSummary < GoogleFinanceSummarySchema
+  end
+
+  # Key event
+  GoogleFinanceKeyEventSchema = DynamicSchema::Struct.define do
+    title                 String
+    link                  String
+    source                String
+    source_date           String, as: :source_date
+    date                  String
+    price_change          GoogleFinancePriceChange, as: :price_change
+  end
+
+  class GoogleFinanceKeyEvent < GoogleFinanceKeyEventSchema
+  end
+
+  # Graph point
+  GoogleFinanceGraphPointSchema = DynamicSchema::Struct.define do
+    price                 Float
+    currency              String
+    date                  String
+    volume                Integer
+  end
+
+  class GoogleFinanceGraphPoint < GoogleFinanceGraphPointSchema
+  end
+
+  # Knowledge graph tag
+  GoogleFinanceTagSchema = DynamicSchema::Struct.define do
+    title                 String
+    description           String
+  end
+
+  class GoogleFinanceTag < GoogleFinanceTagSchema
+  end
+
+  # Knowledge graph stat
+  GoogleFinanceStatSchema = DynamicSchema::Struct.define do
+    label                 String
+    description           String
+    value                 String
+  end
+
+  class GoogleFinanceStat < GoogleFinanceStatSchema
+  end
+
+  # Company about
+  GoogleFinanceCompanyAboutSchema = DynamicSchema::Struct.define do
+    company               String
+    description           String
+    address               String
+    founded               String
+    ceo                   String
+    employees             Integer
+    website               String
+    wikipedia             String
+  end
+
+  class GoogleFinanceCompanyAbout < GoogleFinanceCompanyAboutSchema
+  end
+
+  # Knowledge graph
+  GoogleFinanceKnowledgeGraphSchema = DynamicSchema::Struct.define do
+    tags                  GoogleFinanceTag, array: true
+    stats                 GoogleFinanceStat, array: true
+    about                 GoogleFinanceCompanyAbout
+  end
+
+  class GoogleFinanceKnowledgeGraph < GoogleFinanceKnowledgeGraphSchema
+  end
+
+  # News article
+  GoogleFinanceArticleSchema = DynamicSchema::Struct.define do
+    snippet               String
+    link                  String
+    source                String
+    date                  String
+    thumbnail             String
+  end
+
+  class GoogleFinanceArticle < GoogleFinanceArticleSchema
+  end
+
+  # News category
+  GoogleFinanceNewsCategorySchema = DynamicSchema::Struct.define do
+    title                 String
+    articles              GoogleFinanceArticle, array: true
+  end
+
+  class GoogleFinanceNewsCategory < GoogleFinanceNewsCategorySchema
+  end
+
+  # Financial metric
+  GoogleFinanceMetricSchema = DynamicSchema::Struct.define do
+    value                 Float
+    last_year_value       Float, as: :last_year_value
+    price_change          GoogleFinancePriceChange, as: :price_change
+  end
+
+  class GoogleFinanceMetric < GoogleFinanceMetricSchema
+  end
+
+  # Quarterly financial
+  GoogleFinanceQuarterlySchema = DynamicSchema::Struct.define do
+    year                  Integer
+    quarter               String
+    currency              String
+    revenue               GoogleFinanceMetric
+    net_income            GoogleFinanceMetric, as: :net_income
+    earnings_per_share    GoogleFinanceMetric, as: :earnings_per_share
+    net_profit_margin     GoogleFinanceMetric, as: :net_profit_margin
+    total_assets          GoogleFinanceMetric, as: :total_assets
+    total_equity          GoogleFinanceMetric, as: :total_equity
+    total_liabilities     GoogleFinanceMetric, as: :total_liabilities
+    free_cash_flow        GoogleFinanceMetric, as: :free_cash_flow
+  end
+
+  class GoogleFinanceQuarterly < GoogleFinanceQuarterlySchema
+  end
+
+  # Annual financial
+  GoogleFinanceAnnualSchema = DynamicSchema::Struct.define do
+    year                  Integer
+    currency              String
+    revenue               GoogleFinanceMetric
+    net_income            GoogleFinanceMetric, as: :net_income
+    earnings_per_share    GoogleFinanceMetric, as: :earnings_per_share
+    net_profit_margin     GoogleFinanceMetric, as: :net_profit_margin
+    total_assets          GoogleFinanceMetric, as: :total_assets
+    total_equity          GoogleFinanceMetric, as: :total_equity
+    total_liabilities     GoogleFinanceMetric, as: :total_liabilities
+    free_cash_flow        GoogleFinanceMetric, as: :free_cash_flow
+  end
+
+  class GoogleFinanceAnnual < GoogleFinanceAnnualSchema
+  end
+
+  # Financials
+  GoogleFinanceFinancialsSchema = DynamicSchema::Struct.define do
+    quarterly             GoogleFinanceQuarterly, array: true
+    annual                GoogleFinanceAnnual, array: true
+  end
+
+  class GoogleFinanceFinancials < GoogleFinanceFinancialsSchema
+  end
+
+  # Market stock
+  GoogleFinanceMarketStockSchema = DynamicSchema::Struct.define do
+    stock                 String
+    exchange              String
+    company               String
+    link                  String
+    name                  String
+    price                 Float
+    price_change          GoogleFinancePriceChange, as: :price_change
+    date                  String
+  end
+
+  class GoogleFinanceMarketStock < GoogleFinanceMarketStockSchema
+  end
+
+  # Discover item
+  GoogleFinanceDiscoverItemSchema = DynamicSchema::Struct.define do
+    stock                 String
+    link                  String
+    name                  String
+    price                 Float
+    price_change          GoogleFinancePriceChange, as: :price_change
+  end
+
+  class GoogleFinanceDiscoverItem < GoogleFinanceDiscoverItemSchema
+  end
+
+  # Discover section
+  GoogleFinanceDiscoverSectionSchema = DynamicSchema::Struct.define do
+    title                 String
+    items                 GoogleFinanceDiscoverItem, array: true
+  end
+
+  class GoogleFinanceDiscoverSection < GoogleFinanceDiscoverSectionSchema
+  end
+
+  # Main Google Finance result
+  GoogleFinanceResultSchema = DynamicSchema::Struct.define do
+    search_metadata       GoogleFinanceMetadata, as: :search_metadata
+    search_parameters     GoogleFinanceParameters, as: :search_parameters
+    summary               GoogleFinanceSummary
+    key_events            GoogleFinanceKeyEvent, array: true, as: :key_events
+    graph                 GoogleFinanceGraphPoint, array: true
+    knowledge_graph       GoogleFinanceKnowledgeGraph, as: :knowledge_graph
+    news                  GoogleFinanceNewsCategory, array: true
+    articles              GoogleFinanceArticle, array: true
+    financials            GoogleFinanceFinancials
+    markets               Hash
+    compare_to            GoogleFinanceMarketStock, array: true, as: :compare_to
+    discover_more         GoogleFinanceDiscoverSection, array: true, as: :discover_more
+    error                 String
+  end
+
+  class GoogleFinanceResult < GoogleFinanceResultSchema
+    extend Forwardable
+
+    def_delegators :summary, :title, :stock, :exchange, :price, :currency
+
+    def success?
+      self.error.nil?
+    end
+  end
+
+end

data/lib/searchapi/google_flights_options.rb

@@ -0,0 +1,85 @@
+module SearchAPI
+  class GoogleFlightsOptions
+    include DynamicSchema::Definable
+    include Helpers
+
+    FLIGHT_TYPES = %w[ round_trip one_way multi_city ]
+    STOPS = %w[ any nonstop one_stop_or_fewer two_stops_or_fewer ]
+    SORT_BY = %w[ top_flights price departure_time arrival_time duration emissions ]
+    TRAVEL_CLASSES = %w[ economy premium_economy business first_class ]
+
+    NORMALIZE_DOWNCASE = ->(v) { v.to_s.downcase }
+
+    schema do
+      # locations
+      departure_id          String
+      arrival_id            String
+
+      # dates
+      outbound_date         String
+      return_date           String
+
+      # localization
+      hl                    String
+      gl                    String
+      currency              String
+
+      # flight options
+      flight_type           String, in: FLIGHT_TYPES, normalize: NORMALIZE_DOWNCASE
+      stops                 String, in: STOPS, normalize: NORMALIZE_DOWNCASE
+      sort_by               String, in: SORT_BY, normalize: NORMALIZE_DOWNCASE
+      travel_class          String, in: TRAVEL_CLASSES, normalize: NORMALIZE_DOWNCASE
+
+      # passengers
+      adults                Integer, in: 1..9
+      children              Integer, in: 0..9
+      infants_in_seat       Integer, in: 0..9
+      infants_on_lap        Integer, in: 0..9
+
+      # filters
+      max_price             Integer
+      carry_on_bags         Integer
+      checked_bags          Integer
+      included_airlines     String
+      excluded_airlines     String
+      included_connecting_airports String
+      excluded_connecting_airports String
+      outbound_times        String
+      return_times          String
+      emissions             String
+      layover_duration_min  Integer
+      layover_duration_max  Integer
+      max_flight_duration   Integer
+      separate_tickets      String
+
+      # pagination/booking
+      departure_token       String
+      booking_token         String
+      multi_city_json       String
+
+      # display options
+      show_cheapest_flights [ TrueClass, FalseClass ]
+      show_hidden_flights   [ TrueClass, FalseClass ]
+    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_flights'
+      result
+    end
+
+  end
+end

data/lib/searchapi/google_flights_request.rb

@@ -0,0 +1,25 @@
+module SearchAPI
+  class GoogleFlightsRequest < Request
+
+    def search( options = nil, &block )
+      if options
+        options = options.is_a?( GoogleFlightsOptions ) ? options : GoogleFlightsOptions.build!( options.to_h )
+        options = options.to_h
+      else
+        options = { engine: 'google_flights' }
+      end
+
+      response = get( "#{ BASE_URI }/search", options, &block )
+      attributes = ( JSON.parse( response.body, symbolize_names: true ) rescue nil )
+
+      result = if response.success?
+        GoogleFlightsResult.new( attributes || {} )
+      else
+        ErrorResult.new( response.status, attributes )
+      end
+
+      ResponseMethods.install( response, result )
+    end
+
+  end
+end