rename API_KEY to SERPAPI_KEY

minor doc improvements

Author: jvmvik

.github/workflows/ci.yml

@@ -22,9 +22,9 @@ jobs:
         run: bundle exec rake lint
       - name: tests
         env:
-          API_KEY: ${{ secrets.API_KEY }}
+          SERPAPI_KEY: ${{ secrets.SERPAPI_KEY }}
         run: bundle exec rake test
       - name: oobt
         env:
-          API_KEY: ${{ secrets.API_KEY }}
+          SERPAPI_KEY: ${{ secrets.SERPAPI_KEY }}
         run: bundle exec rake oobt

README.md

@@ -13,7 +13,7 @@ def snippet(format, path, demo = false)
   slice.map! { |l| l.gsub(/(^\s\s\s\s)/, '')}
   buf = slice.join
   buf.gsub!('# pp ', 'pp ')
-  buf.gsub!('api_key)', "ENV['API_KEY'])")
+  buf.gsub!('api_key)', "ENV['SERPAPI_KEY'])")
  end
  %Q(```#{format}\nrequire 'serpapi'\n#{buf}```\n\n * source code: [#{path}](https://github.com/serpapi/serpapi-ruby/blob/master/#{path}))
 end
@@ -26,20 +26,19 @@ end
 [![Gem Version](https://badge.fury.io/rb/serpapi.svg)](https://badge.fury.io/rb/serpapi) [![serpapi-ruby](https://github.com/serpapi/serpapi-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/serpapi/serpapi-ruby/actions/workflows/ci.yml)  
 </div>
 
-Integrate search data into your Ruby application. This library is the official wrapper for SerpApi (https://serpapi.com). 
+Integrate search data into your AI workflow or ruby application. This library is the official wrapper for [SerpApi](https://serpapi.com). 
 SerpApi supports Google, Google Maps, Google Shopping, Baidu, Yandex, Yahoo, eBay, App Stores, and more.
 Fast query at scale a vast range of data, including web search results, flight schedule, stock market data, news headlines, and more.
 
 ## Features
-  * `persistent`:Keep socket connection open to save on SSL handshake / reconnection (2x
-  faster). [default: true] [Search at scale](#Search-At-Scale)
-  * `async`: [Boolean] Support non-blocking job submission. [default: false] [Search Asynchronous](#Search-Asynchronous)
-  * extensive documentations
-  * real world examples
+  * `persistent` → Keep socket connection open to save on SSL handshake / reconnection (2x faster).  [Search at scale](#Search-At-Scale)
+  * `async` → Support non-blocking job submission. [Search Asynchronous](#Search-Asynchronous)
+  * extensive documentation → easy to follow
+  * real world examples → included throughout
 
 ## Installation
 
-To achieve optimal performance, it is essential to have Ruby 3.x (preferably version 3.4) installed. 
+To achieve optimal performance, it is essential to have Ruby 3.1+ (preferably version 3.4) installed. 
 
 | Older versions such as Ruby 1.9, 2.x, and JRuby are compatible with [serpapi older library](https://github.com/serpapi/google-search-results-ruby), which continues to function effectively.
 
@@ -67,8 +66,12 @@ pp results
 This example runs a search for "coffee" on Google. It then returns the results as a regular Ruby Hash.
  See the [playground](https://serpapi.com/playground) to generate your own code.
 
-The `SERPAPI_KEY` should be replaced with your actual API key obtained from 
-https://serpapi.com/users/sign_up?plan=free.
+The SerpApi key can be obtained from [serpapi.com/signup](https://serpapi.com/users/sign_up?plan=free).
+
+Environment variables are a secure, safe, and easy way to manage secrets.
+ Set `export SERPAPI_KEY=<secret_serpapi_key>` in your shell.
+ Ruby accesses these variables from `ENV['SERPAPI_KEY']`.
+
 
 ## Search API advanced Usage
 
@@ -80,10 +83,10 @@ require 'serpapi'
 client = SerpApi::Client.new(
   engine: 'google',
   api_key: ENV['SERPAPI_KEY'],
-  # HTTP client behavior
-  async: false, # non blocking HTTP request see [Search Asynchronous](#Search-Asynchronous)
-  persistent: true, # leave socket connection open for faster response time [Search at scale](#Search-At-Scale)
-  timeout: 5, # HTTP timeout in seconds on the client side only.
+  # HTTP client configuration
+  async: false, # non blocking HTTP request see: Search Asynchronous (default: false)
+  persistent: true, # leave socket connection open for faster response time see: Search at scale (default: true)
+  timeout: 5, # HTTP timeout in seconds on the client side only. (default: 120s)
 )
 
 # search query overview (more fields available depending on search engine)
@@ -136,7 +139,7 @@ Search API features non-blocking search using the option: `async=true`.
 
 Search API enables `async` search.
  - Non-blocking (`async=true`) : the development is more complex, but this allows handling many simultaneous connections.
- - Blocking (`async=false`) : it's easy to write the code but more compute-intensive when the parent process needs to hold many connections.
+ - Blocking (`async=false`) : it is easy to write the code but more compute-intensive when the parent process needs to hold many connections.
 
 Here is an example of asynchronous searches using Ruby 
 <%= snippet('ruby', 'demo/demo_async.rb', true) %>
@@ -153,7 +156,7 @@ require 'connection_pool'
 
 # create a thread pool of 4 threads with a persistent connection to serpapi.com
 pool = ConnectionPool.new(size: n, timeout: 5) do
-    SerpApi::Client.new(engine: 'google', api_key: ENV['API_KEY'], timeout: 30, persistent: true)
+    SerpApi::Client.new(engine: 'google', api_key: ENV['SERPAPI_KEY'], timeout: 30, persistent: true)
 end
 
 # run user thread to search for your favorites coffee type
@@ -524,7 +527,7 @@ The directory spec/ includes specification which serves the dual purposes of exa
 
 Set your secret API key in your shell before running a test.
 ```bash
-export API_KEY="your_secret_key"
+export SERPAPI_KEY="your_secret_key"
 ```
 Install testing dependency
 ```bash

README.md.erb

@@ -88,10 +88,10 @@ end
 
 # private
 task :check do
-  if ENV['API_KEY']
-    puts 'check: found $API_KEY'
+  if ENV['SERPAPI_KEY']
+    puts 'check: found $SERPAPI_KEY'
   else
-    puts 'check: API_KEY must be defined'
+    puts 'check: SERPAPI_KEY must be defined'
     exit 1
   end
 end

Rakefile

@@ -3,21 +3,21 @@
 #
 # **Key Points:**
 #
-# * **API Key:** The code requires an API key to be set in the `API_KEY` environment variable.
-# * **Serpapi Client:** A SerpApi client is created with default parameters, including the engine, client, language, 
+# * **API Key:** The code requires an API key to be set in the `SERPAPI_KEY` environment variable.
+# * **Serpapi Client:** A SerpApi client is created with default parameters, including the engine, client, language,
 # country, API key, persistence settings, and timeout.
 # * **Search Parameters:** A search request is made with the query "coffee".
 # * **Suggestions Retrieval:** The `suggestions` key in the response is checked for availability and non-emptiness.
 # * **Output:** The suggestions are printed using the `pp` gem.
 #
 # **Purpose:**
 #
-# The code is designed to demonstrate how to use the SerpApi client to retrieve autocomplete suggestions from Google. It 
+# The code is designed to demonstrate how to use the SerpApi client to retrieve autocomplete suggestions from Google. It
 # verifies that suggestions are returned and outputs them for demonstration purposes.
 #
 # **Usage:**
 #
-# To run the code, you need to set the `API_KEY` environment variable to your actual SerpApi API key. 
+# To run the code, you need to set the `SERPAPI_KEY` environment variable to your actual SerpApi API key.
 # Obtain your free key from: serpapi.com
 #
 # **Output:**
@@ -34,14 +34,14 @@
 require 'serpapi'
 require 'pp'
 
-raise 'API_KEY environment variable must be set' if ENV['API_KEY'].nil?
+raise 'SERPAPI_KEY environment variable must be set' if ENV['SERPAPI_KEY'].nil?
 
 default_params = {
   engine: 'google_autocomplete',
   client: 'safari',
   hl: 'en',
   gl: 'us',
-  api_key: ENV['API_KEY'],
+  api_key: ENV.fetch('SERPAPI_KEY', nil),
   persistent: false,
   timeout: 2
 }

demo/demo.rb

@@ -2,64 +2,73 @@
 # The request are non-blocking which allows batching a large amount of query, and wait before fetching the result back.
 #
 # **Process:**
-# 1. **Request Queue:** The company list is iterated over, and each company is queried using the SerpApi client. Requests 
+# 1. **Request Queue:** The company list is iterated over, and each company is queried using the SerpApi client. Requests
 # are stored in a queue to avoid blocking the main thread.
 #
-# 2. **Client Retrieval:** After each request, the code checks the status of the search result. If it's cached or 
-# successful, the company name is printed, and the request is skipped. Otherwise, the result is added to the queue for 
+# 2. **Client Retrieval:** After each request, the code checks the status of the search result. If it's cached or
+# successful, the company name is printed, and the request is skipped. Otherwise, the result is added to the queue for
 # further processing.
 #
-# 3. **Queue Processing:** The queue is processed until it's empty. In each iteration, the last result is retrieved and 
+# 3. **Queue Processing:** The queue is processed until it's empty. In each iteration, the last result is retrieved and
 # its client ID is extracted.
 #
-# 4. **Archived Client Retrieval:** Using the client ID, the code retrieves the archived client and checks its status. If 
-# it's cached or successful, the company name is printed, and the client is skipped. Otherwise, the result is added back 
+# 4. **Archived Client Retrieval:** Using the client ID, the code retrieves the archived client and checks its status. If
+# it's cached or successful, the company name is printed, and the client is skipped. Otherwise, the result is added back
 # to the queue for further processing.
 #
 # 5. **Completion:** The queue is closed, and a message is printed indicating that the process is complete.
 #
-# * **Asynchronous Requests:** The `async: true` option ensures that search requests are processed in parallel, improving 
+# * **Asynchronous Requests:** The `async: true` option ensures that search requests are processed in parallel, improving
 # efficiency.
 # * **Queue Management:** The queue allows requests to be processed asynchronously without blocking the main thread.
 # * **Status Checking:** The code checks the status of each search result before processing it, avoiding unnecessary work.
 # * **Queue Processing:** The queue ensures that all requests are processed in the order they were submitted.
 
-# **Overall, the code snippet demonstrates a well-structured approach to improve the efficiency of searching for company 
+# **Overall, the code snippet demonstrates a well-structured approach to improve the efficiency of searching for company
 # information using SerpApi.**
 
 # load serpapi library
 require 'serpapi'
 
 # target MAANG companies
-company_list = %w(meta amazon apple netflix google)
-client = SerpApi::Client.new(engine: 'google', async: true, persistent: true, api_key: ENV['API_KEY'])
+company_list = %w[meta amazon apple netflix google]
+client = SerpApi::Client.new(engine: 'google', async: true, persistent: true, api_key: ENV.fetch('SERPAPI_KEY', nil))
 search_queue = Queue.new
 company_list.each do |company|
   # store request into a search_queue - no-blocker
-  result = client.search({q: company})
-  if result[:search_metadata][:status] =~ /Cached|Success/
+  result = client.search({ q: company })
+  if result[:search_metadata][:status] =~ /Cached/
     puts "#{company}: search results found in cache for: #{company}"
-    next
   end
 
   # add results to the client queue
-  search_queue.push(result)
+  search_queue.push(result[:search_metadata][:id])
 end
 
-puts "wait until all searches are cached or success"
-while !search_queue.empty?
-  result = search_queue.pop
+# wait for all requests to be completed
+puts 'wait for all requests to be completed'
+# wait for 10 seconds to allow all requests to be processed
+sleep(10)
+
+puts 'wait until all searches are cached or success'
+until search_queue.empty?
   # extract client id
-  search_id = result[:search_metadata][:id]
+  search_id = search_queue.pop
 
   # retrieve client from the archive - blocker
   search_archived = client.search_archive(search_id)
+
+  # read original company name from the search parameters
+  company = search_archived[:search_parameters][:q]
+
+  # check if the search is cached or successful
   if search_archived[:search_metadata][:status] =~ /Cached|Success/
     puts "#{search_archived[:search_parameters][:q]}: search results found in archive for: #{company}"
     next
   end
 
-  # add results to the client queue
+  # add results back to the client queue 
+  #  if the search is still in progress
   search_queue.push(result)
 end
 

demo/demo_async.rb

@@ -1,55 +1,54 @@
-
-# The provided code snippet is a Ruby spec test case that 
-# demonstrates the use of thread pools to execute multiple HTTP 
+# The provided code snippet is a Ruby spec test case that
+# demonstrates the use of thread pools to execute multiple HTTP
 # requests concurrently.
 #
 # **Key Points:**
 #
-# * The `connection_pool` gem is used to create a thread pool of 
+# * The `connection_pool` gem is used to create a thread pool of
 # `HTTP` connections.
-# * The `Thread` class is used to spawn multiple threads, each of 
+# * The `Thread` class is used to spawn multiple threads, each of
 # which makes a GET request to the specified endpoint.
-# * The `pool.with` method is used to acquire a connection from the 
+# * The `pool.with` method is used to acquire a connection from the
 # thread pool and use it to make the HTTP request.
 # * The `to_s` method converts the HTTP response to a string.
-# * The `total` method from the `Benchmark` class is used to measure 
+# * The `total` method from the `Benchmark` class is used to measure
 # the total execution time of the code block.
 
 # **Purpose:**
 
-# The code aims to demonstrate how thread pools can be used to 
-# improve performance by executing multiple tasks concurrently. In 
-# this case, it makes multiple HTTP requests to an API endpoint using 
+# The code aims to demonstrate how thread pools can be used to
+# improve performance by executing multiple tasks concurrently. In
+# this case, it makes multiple HTTP requests to an API endpoint using
 # a thread pool of connections.
 #
 # **Benefits:**
 #
-# * Improved performance by avoiding the overhead of creating and 
+# * Improved performance by avoiding the overhead of creating and
 # destroying connections for each request.
-# * Efficient use of resources by sharing connections among multiple 
+# * Efficient use of resources by sharing connections among multiple
 # threads.
-# * Concurrency and parallelism, allowing multiple requests to be 
+# * Concurrency and parallelism, allowing multiple requests to be
 # processed simultaneously.
 #
 # **Usage:**
 #
-# The code snippet can be used as a reference to implement thread 
-# pools in Ruby applications. It provides an example of how to use 
-# the `connection_pool` gem to create a thread pool of connections 
+# The code snippet can be used as a reference to implement thread
+# pools in Ruby applications. It provides an example of how to use
+# the `connection_pool` gem to create a thread pool of connections
 # and make concurrent HTTP requests.
 #
 # **Additional Notes:**
 #
-# * The number of threads created should be set to an appropriate 
-# value based on the available resources and the expected request 
+# * The number of threads created should be set to an appropriate
+# value based on the available resources and the expected request
 # load.
-# * The `timeout` option in the `ConnectionPool` constructor 
-# specifies the maximum time a thread should wait to acquire a 
+# * The `timeout` option in the `ConnectionPool` constructor
+# specifies the maximum time a thread should wait to acquire a
 # connection from the pool.
-# * The `HTTP.persistent` method is used to create persistent 
-# connections, which can improve performance by reusing connections 
+# * The `HTTP.persistent` method is used to create persistent
+# connections, which can improve performance by reusing connections
 # between requests.
-# * The `benchmark` gem is used to measure the execution time of the 
+# * The `benchmark` gem is used to measure the execution time of the
 # code block.
 # reference: https://github.com/httprb/http/wiki/Thread-Safety
 
@@ -59,18 +58,18 @@
 
 # number of thread == number of HTTP persistent connection
 n = 4
-runtime = Benchmark.measure do 
+runtime = Benchmark.measure do
   # create a thread pool of 4 threads with a persistent connection to serpapi.com
   pool = ConnectionPool.new(size: n, timeout: 5) do
-      SerpApi::Client.new(engine: 'google', api_key: ENV['API_KEY'], timeout: 30, persistent: true)
+    SerpApi::Client.new(engine: 'google', api_key: ENV.fetch('SERPAPI_KEY', nil), timeout: 30, persistent: true)
   end
 
   # run user thread to search for your favorites coffee type
-  threads = %w(latte espresso cappuccino americano mocha macchiato frappuccino cold_brew).map do |query|
+  threads = %w[latte espresso cappuccino americano mocha macchiato frappuccino cold_brew].map do |query|
     Thread.new do
-      pool.with { |socket| socket.search({q: query }).to_s }
+      pool.with { |socket| socket.search({ q: query }).to_s }
     end
   end
-  responses = threads.map(&:value)
+  threads.map(&:value)
 end.total
 puts "total runtime: #{runtime}s for #{n} threads == #{n} HTTP connections"

demo/demo_thread_pool.rb

@@ -2,14 +2,14 @@
 
 describe 'account API' do
   it 'fetch user account information' do
-    client = SerpApi::Client.new(api_key: ENV['API_KEY'])
+    client = SerpApi::Client.new(api_key: ENV['SERPAPI_KEY'])
 
-    # mock response if no API_KEY specified
-    if ENV['API_KEY'].nil?
+    # mock response if no SERPAPI_KEY specified
+    if ENV['SERPAPI_KEY'].nil?
       allow(search).to receive(:get_results) {
         '{
           "account_id": "5ac54d6adefb2f1dba1663f5",
-          "api_key": "SECRET_API_KEY",
+          "api_key": "SECRET_SERPAPI_KEY",
           "account_email": "demo@serpapi.com",
           "plan_id": "bigdata",
           "plan_name": "Big Data Plan",

spec/serpapi/client/account_api_spec.rb

@@ -21,7 +21,7 @@
 
   it 'regular get' do
     runtime = Benchmark.measure do
-      client = SerpApi::Client.new(persistent: false, engine: 'google', api_key: ENV['API_KEY'])
+      client = SerpApi::Client.new(persistent: false, engine: 'google', api_key: ENV['SERPAPI_KEY'])
       results = n.times.map { |x| client.search(q: "coffee #{x}") }
       client.close
     end.total
@@ -30,7 +30,7 @@
 
   it 'keep alive' do
     runtime = Benchmark.measure do
-      client = SerpApi::Client.new(persistent: true, engine: 'google', api_key: ENV['API_KEY'],)
+      client = SerpApi::Client.new(persistent: true, engine: 'google', api_key: ENV['SERPAPI_KEY'],)
       results = n.times.map { |x| client.search(q: "coffee #{n+x}") }
       client.close 
     end.total