Rework example section

.gitignore

@@ -6,6 +6,7 @@ rdoc
 log
 websites
 .DS_Store
+.env
 
 ## BUNDLER
 *.gem

README.md.erb

@@ -339,156 +339,129 @@ It prints your account information as:
 }
  ```
 
-## Basic example per search engine
+## Examples
 
-### Search google
+Here are some examples for some of our most popular APIs. You can find the full list of supported engines and parameters in our [documentation](https://serpapi.com/search-engine-apis).
 
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_spec.rb') %>
-see: [https://serpapi.com/search-api](https://serpapi.com/search-api)
+### Google Immersive Product
 
-### Search google light
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_light_spec.rb') %>
-see: [https://serpapi.com/google-light-api](https://serpapi.com/google-light-api)
+Retrieve detailed information about a product selected from Google Shopping results, including images, prices, stores, ratings, and reviews.
 
-### Search google scholar
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_scholar_spec.rb') %>
-see: [https://serpapi.com/google-scholar-api](https://serpapi.com/google-scholar-api)
+> **Note:** The `google_immersive_product` engine does not accept a `q` parameter. It requires a `page_token`, returned as `immersive_product_page_token` by a Google Shopping search.
 
-### Search google autocomplete
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_autocomplete_spec.rb') %>
-see: [https://serpapi.com/google-autocomplete-api](https://serpapi.com/google-autocomplete-api)
+```ruby
+require 'serpapi'
 
-### Search google product
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_product_spec.rb') %>
-see: [https://serpapi.com/google-product-api](https://serpapi.com/google-product-api)
+shopping_client = SerpApi::Client.new(engine: 'google_shopping', api_key: ENV['SERPAPI_KEY'])
+shopping_results = shopping_client.search({ q: 'coffee maker' })
+product = shopping_results[:shopping_results].find { |result| result[:immersive_product_page_token] }
+page_token = product[:immersive_product_page_token]
 
-### Search google reverse image
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_reverse_image_spec.rb') %>
-see: [https://serpapi.com/google-reverse-image](https://serpapi.com/google-reverse-image)
+product_client = SerpApi::Client.new(engine: 'google_immersive_product', api_key: ENV['SERPAPI_KEY'])
+product_results = product_client.search({ page_token: page_token })
+pp product_results[:product_results]
+```
 
-### Search google events
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_events_spec.rb') %>
-see: [https://serpapi.com/google-events-api](https://serpapi.com/google-events-api)
+[See documentation](https://serpapi.com/google-immersive-product-api)
 
-### Search google local services
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_local_services_spec.rb') %>
-see: [https://serpapi.com/google-local-services-api](https://serpapi.com/google-local-services-api)
+### Google Images
 
-### Search google maps
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_maps_spec.rb') %>
-see: [https://serpapi.com/google-maps-api](https://serpapi.com/google-maps-api)
+Scrape Google Images search results, including image URLs, thumbnails, titles, and source pages.
 
-### Search google jobs
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_jobs_spec.rb') %>
-see: [https://serpapi.com/google-jobs-api](https://serpapi.com/google-jobs-api)
+```ruby
+require 'serpapi'
+client = SerpApi::Client.new(engine: 'google_images', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'coffee' })
+pp results[:images_results]
+```
 
-### Search google play
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_play_spec.rb') %>
-see: [https://serpapi.com/google-play-api](https://serpapi.com/google-play-api)
+[See documentation](https://serpapi.com/images-results)
 
-### Search google images
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_images_spec.rb') %>
-see: [https://serpapi.com/images-results](https://serpapi.com/images-results)
+**Google Images Light**
 
-### Search google lens
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_lens_spec.rb') %>
-see: [https://serpapi.com/google-lens-api](https://serpapi.com/google-lens-api)
+A [light variant](https://serpapi.com/google-images-light-api) engine called `google_images_light` is also available for faster, lower-cost image searches.
 
-### Search google images light
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_images_light_spec.rb') %>
-see: [https://serpapi.com/google-images-light-api](https://serpapi.com/google-images-light-api)
+### Google Shopping
 
-### Search google hotels
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_hotels_spec.rb') %>
-see: [https://serpapi.com/google-hotels-api](https://serpapi.com/google-hotels-api)
+Scrape Google Shopping results with product names, prices, ratings, and merchant information.
 
-### Search google flights
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_flights_spec.rb') %>
-see: [https://serpapi.com/google-flights-api](https://serpapi.com/google-flights-api)
+```ruby
+require 'serpapi'
+client = SerpApi::Client.new(engine: 'google_shopping', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'Macbook M4' })
+pp results[:shopping_results]
+```
 
-### Search google finance
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_finance_spec.rb') %>
-see: [https://serpapi.com/google-finance-api](https://serpapi.com/google-finance-api)
+[See documentation](https://serpapi.com/google-shopping-api)
 
-### Search google ai overview
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_ai_overview_spec.rb') %>
-see: [https://serpapi.com/google-ai-overview-api](https://serpapi.com/google-ai-overview-api)
+**Google Shopping Light**
 
-### Search google news
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_news_spec.rb') %>
-see: [https://serpapi.com/google-news-api](https://serpapi.com/google-news-api)
+A [light variant](https://serpapi.com/google-shopping-light-api) engine called `google_shopping_light` is also available for faster, lower-cost shopping searches.
 
-### Search google news light
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_news_light_spec.rb') %>
-see: [https://serpapi.com/google-news-light-api](https://serpapi.com/google-news-light-api)
+### Google Maps
 
-### Search google patents
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_patents_spec.rb') %>
-see: [https://serpapi.com/google-patents-api](https://serpapi.com/google-patents-api)
+Scrape Google Maps local search results with business names, addresses, ratings, and coordinates.
 
-### Search google trends
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_trends_spec.rb') %>
-see: [https://serpapi.com/google-trends-api](https://serpapi.com/google-trends-api)
+```ruby
+require 'serpapi'
+client = SerpApi::Client.new(engine: 'google_maps', api_key: ENV['SERPAPI_KEY'])
+results = client.search({
+  q: 'Coffee',
+  ll: '@40.7455096,-74.0083012,14z',
+  type: 'search'
+})
+pp results[:local_results]
+```
 
-### Search google shopping
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_shopping_spec.rb') %>
-see: [https://serpapi.com/google-shopping-api](https://serpapi.com/google-shopping-api)
+[See documentation](https://serpapi.com/google-maps-api)
 
-### Search google immersive product
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_immersive_product_spec.rb') %>
-see: [https://serpapi.com/google-immersive-product-api](https://serpapi.com/google-immersive-product-api)
+**Google Maps Light**
 
-### Search google videos
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_google_videos_spec.rb') %>
-see: [https://serpapi.com/google-videos-api](https://serpapi.com/google-videos-api)
+A [light variant](https://serpapi.com/google-maps-light-api) engine called `google_maps_light` is also available for faster, lower-cost local searches.
 
-### Search amazon
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_amazon_spec.rb') %>
-see: [https://serpapi.com/amazon-search-api](https://serpapi.com/amazon-search-api)
+### Google AI Mode API
 
-### Search baidu
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_baidu_spec.rb') %>
-see: [https://serpapi.com/baidu-search-api](https://serpapi.com/baidu-search-api)
+The Google AI Mode API returns AI-generated answers with structured text blocks, references, images, products, and more.
 
-### Search yahoo
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_yahoo_spec.rb') %>
-see: [https://serpapi.com/yahoo-search-api](https://serpapi.com/yahoo-search-api)
+```ruby
+require 'serpapi'
 
-### Search youtube
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_youtube_spec.rb') %>
-see: [https://serpapi.com/youtube-search-api](https://serpapi.com/youtube-search-api)
+client = SerpApi::Client.new(engine: 'google_ai_mode', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'best coffee maker' })
+pp results[:reconstructed_markdown]
+```
+
+[See documentation](https://serpapi.com/google-ai-mode-api)
 
-### Search walmart
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_walmart_spec.rb') %>
-see: [https://serpapi.com/walmart-search-api](https://serpapi.com/walmart-search-api)
+### Bing Search
 
-### Search ebay
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_ebay_spec.rb') %>
-see: [https://serpapi.com/ebay-search-api](https://serpapi.com/ebay-search-api)
+Scrape Bing web search results, including organic results, ads, related searches, and more.
 
-### Search naver
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_naver_spec.rb') %>
-see: [https://serpapi.com/naver-search-api](https://serpapi.com/naver-search-api)
+```ruby
+require 'serpapi'
+
+client = SerpApi::Client.new(engine: 'bing', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'coffee' })
+pp results[:organic_results]
+```
 
-### Search home depot
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_home_depot_spec.rb') %>
-see: [https://serpapi.com/home-depot-search-api](https://serpapi.com/home-depot-search-api)
+[See documentation](https://serpapi.com/bing-search-api)
 
-### Search apple app store
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_apple_app_store_spec.rb') %>
-see: [https://serpapi.com/apple-app-store](https://serpapi.com/apple-app-store)
+### Amazon Search
 
-### Search duckduckgo
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_duckduckgo_spec.rb') %>
-see: [https://serpapi.com/duckduckgo-search-api](https://serpapi.com/duckduckgo-search-api)
+Scrape Amazon product search results, including product names, prices, ratings, reviews, and availability.
 
-### Search yandex
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_yandex_spec.rb') %>
-see: [https://serpapi.com/yandex-search-api](https://serpapi.com/yandex-search-api)
+> **Note:** The `amazon` engine uses the `k` parameter for a keyword search, not `q`.
+
+```ruby
+require 'serpapi'
+
+client = SerpApi::Client.new(engine: 'amazon', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ k: 'coffee' })
+pp results[:organic_results]
+```
 
-### Search yelp
-<%= snippet('ruby', 'spec/serpapi/client/example/example_search_yelp_spec.rb') %>
-see: [https://serpapi.com/yelp-search-api](https://serpapi.com/yelp-search-api)
+[See documentation](https://serpapi.com/amazon-search-api)
 
 ## Performance Comparison
 

spec/serpapi/client/example/example_search_amazon_spec.rb

@@ -11,7 +11,7 @@
     client = SerpApi::Client.new(engine: 'amazon', api_key: api_key)
     # run a search using serpapi service
     results = client.search({
-      q: 'coffee'
+      k: 'coffee'
     })
     expect(results[:organic_results]).not_to be_nil, "No organic results found! keys available: #{results.keys}"
 

spec/serpapi/client/example/example_search_bing_spec.rb

@@ -0,0 +1,22 @@
+require 'spec_helper'
+
+describe 'example: bing search' do
+  it 'prints organic_results' do
+    # Confirm that the environment variable for SERPAPI_KEY has been set properly.
+    # Your SerpApi key can be obtained at this URL: https://serpapi.com
+    api_key = ENV['SERPAPI_KEY']
+    skip('SERPAPI_KEY not set. Please set your SerpApi API key.') if api_key.nil?
+
+    # initialize the serp api client
+    client = SerpApi::Client.new(engine: 'bing', api_key: api_key)
+    # run a search using serpapi service
+    results = client.search({
+      q: 'coffee'
+    })
+    expect(results[:organic_results]).not_to be_nil, "No organic results found! keys available: #{results.keys}"
+
+    # print the output of the response in formatted JSON
+    # pp results[:organic_results]
+    # doc: https://serpapi.com/bing-search-api
+  end
+end

spec/serpapi/client/example/example_search_google_ai_mode_spec.rb

@@ -0,0 +1,20 @@
+require 'spec_helper'
+
+describe 'example: google_ai_mode search' do
+  it 'prints reconstructed_markdown' do
+    # Confirm that the environment variable for SERPAPI_KEY has been set properly.
+    # Your SerpApi key can be obtained at this URL: https://serpapi.com
+    api_key = ENV['SERPAPI_KEY']
+    skip('SERPAPI_KEY not set. Please set your SerpApi API key.') if api_key.nil?
+
+    # initialize the serp api client
+    client = SerpApi::Client.new(engine: 'google_ai_mode', api_key: api_key)
+    # run a search using serpapi service
+    results = client.search({ q: 'best coffee maker' })
+    expect(results[:reconstructed_markdown]).not_to be_nil, "No reconstructed markdown found! keys available: #{results.keys}"
+
+    # print the output of the response in formatted Markdown
+    # pp results[:reconstructed_markdown]
+    # doc: https://serpapi.com/google-ai-mode-api
+  end
+end

spec/serpapi/client/example/example_search_google_images_spec.rb

@@ -11,7 +11,6 @@
     client = SerpApi::Client.new(engine: 'google_images', api_key: api_key)
     # run a search using serpapi service
     results = client.search({
-      tbm: 'isch',
       q: 'coffee'
     })
     expect(results[:images_results]).not_to be_nil, "No images results found! keys available: #{results.keys}"

spec/serpapi/client/example/example_search_google_immersive_product_spec.rb

@@ -1,22 +1,25 @@
 require 'spec_helper'
 
 describe 'example: google_immersive_product search' do
-  it 'prints immersive_product_results' do
+  it 'prints product_results' do
     # Confirm that the environment variable for SERPAPI_KEY has been set properly.
     #  Your SerpApi key can be obtained at this URL http://serpapi.com
     api_key = ENV['SERPAPI_KEY']
     skip('SERPAPI_KEY not set. Please set your SerpApi API key.') if api_key.nil?
 
-    # initialize the serp api client
-    client = SerpApi::Client.new(engine: 'google_immersive_product', api_key: api_key)
-    # run a search using serpapi service
-    results = client.search({
-      q: 'coffee'
-    })
-    expect(results[:immersive_product_results]).not_to be_nil, "No immersive product results found! keys available: #{results.keys}"
+    # Find an immersive product token in Google Shopping results
+    shopping_client = SerpApi::Client.new(engine: 'google_shopping', api_key: api_key)
+    shopping_results = shopping_client.search({ q: 'coffee maker' })
+    product = shopping_results[:shopping_results].find { |result| result[:immersive_product_page_token] }
+    page_token = product[:immersive_product_page_token]
+
+    # Fetch the selected product's details
+    product_client = SerpApi::Client.new(engine: 'google_immersive_product', api_key: api_key)
+    product_results = product_client.search({ page_token: page_token })
+    expect(product_results[:product_results]).not_to be_nil, "No product results found! keys available: #{product_results.keys}"
 
     # print the output of the response in formatted JSON
-    # pp results[:immersive_product_results]
+    # pp product_results[:product_results]
     # doc: https://serpapi.com/google-immersive-product-api
   end
 end