Rework example section

.gitignore

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

README.md.erb

@@ -339,156 +339,156 @@ 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 Shopping
 
-### 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)
+Scrape Google Shopping results with product names, prices, ratings, and merchant information.
 
-### 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)
+```ruby
+require 'serpapi'
 
-### 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)
+client = SerpApi::Client.new(engine: 'google_shopping', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'Macbook M4' })
+pp results[:shopping_results]
+```
 
-### 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)
+[See documentation](https://serpapi.com/google-shopping-api)
 
-### 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)
+**Google Shopping Light**
 
-### 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)
+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 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'
 
-### 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)
+client = SerpApi::Client.new(engine: 'google_images', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'coffee' })
+pp results[: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)
+[See documentation](https://serpapi.com/images-results)
 
-### 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)
+**Google Images Light**
 
-### 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)
+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 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)
+### Google Trends
 
-### 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)
+Track search interest over time and compare the popularity of search terms.
 
-### 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)
+```ruby
+require 'serpapi'
 
-### 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)
+client = SerpApi::Client.new(engine: 'google_trends', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'coffee', data_type: 'TIMESERIES' })
+pp results[:interest_over_time]
+```
 
-### 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)
+[See documentation](https://serpapi.com/google-trends-api)
 
-### 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 Flights
 
-### 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)
+Search flight routes, schedules, prices, and booking options.
 
-### 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)
+> **Note:** The `google_flights` engine does not use `q`. Specify route and date parameters such as `departure_id`, `arrival_id`, `outbound_date`, and `return_date`.
 
-### 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)
+```ruby
+require 'date'
+require 'serpapi'
 
-### 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)
+outbound_date = (Date.today + 30).iso8601
+return_date = (Date.today + 37).iso8601
+client = SerpApi::Client.new(engine: 'google_flights', api_key: ENV['SERPAPI_KEY'])
+results = client.search({
+  departure_id: 'LAX',
+  arrival_id: 'AUS',
+  outbound_date: outbound_date,
+  return_date: return_date
+})
+flights = results[:best_flights] || results[:other_flights]
+pp flights
+```
 
-### 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)
+[See documentation](https://serpapi.com/google-flights-api)
 
-### 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]
+```
 
-### 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)
+[See documentation](https://serpapi.com/google-ai-mode-api)
 
-### 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)
+### Bing Search
 
-### 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)
+Scrape Bing web search results, including organic results, ads, related searches, and more.
 
-### 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)
+```ruby
+require 'serpapi'
 
-### 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)
+client = SerpApi::Client.new(engine: 'bing', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'coffee' })
+pp results[:organic_results]
+```
+
+[See documentation](https://serpapi.com/bing-search-api)
+
+### DuckDuckGo 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 DuckDuckGo search results, including organic results, ads, knowledge graphs, and related searches.
 
-### 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)
+```ruby
+require 'serpapi'
+
+client = SerpApi::Client.new(engine: 'duckduckgo', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'coffee' })
+pp results[:organic_results]
+```
+
+[See documentation](https://serpapi.com/duckduckgo-search-api)
+
+### Baidu Search
+
+Scrape Baidu search results, including organic results, answer boxes, and related searches.
+
+```ruby
+require 'serpapi'
+
+client = SerpApi::Client.new(engine: 'baidu', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'coffee' })
+pp results[:organic_results]
+```
+
+[See documentation](https://serpapi.com/baidu-search-api)
+
+### Amazon Search
+
+Scrape Amazon product search results, including product names, prices, ratings, reviews, and availability.
+
+> **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_flights_spec.rb

@@ -1,7 +1,8 @@
+require 'date'
 require 'spec_helper'
 
 describe 'example: google_flights search' do
-  it 'prints best_flights' do
+  it 'prints flight 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']
@@ -11,17 +12,16 @@
     client = SerpApi::Client.new(engine: 'google_flights', api_key: api_key)
     # run a search using serpapi service
     results = client.search({
-      departure_id: 'PEK',
+      departure_id: 'LAX',
       arrival_id: 'AUS',
-      outbound_date: '2025-05-26',
-      return_date: '2025-06-01',
-      currency: 'USD',
-      hl: 'en'
+      outbound_date: (Date.today + 30).iso8601,
+      return_date: (Date.today + 37).iso8601
     })
-    expect(results[:best_flights]).not_to be_nil, "No best flights found! keys available: #{results.keys}"
+    flights = results[:best_flights] || results[:other_flights]
+    expect(flights).not_to be_nil, "No flights found! keys available: #{results.keys}"
 
     # print the output of the response in formatted JSON
-    # pp results[:best_flights]
+    # pp flights
     # doc: https://serpapi.com/google-flights-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}"