From 7c0088f6cf8c96d62c15fadbfa79240a830f54c4 Mon Sep 17 00:00:00 2001
From: Josef Strzibny <strzibny@strzibny.name>
Date: Fri, 12 Jun 2026 10:28:41 +0200
Subject: [PATCH 1/3] Redo examples section with our most popular APIs

---
 README.md | 680 ++++--------------------------------------------------
 1 file changed, 43 insertions(+), 637 deletions(-)

diff --git a/README.md b/README.md
index 4422747..e93bfa8 100644
--- a/README.md
+++ b/README.md
@@ -319,695 +319,101 @@ 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).
 
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/search-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_spec.rb)
-see: [https://serpapi.com/search-api](https://serpapi.com/search-api)
-
-### Search google light
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_light', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/google-light-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_light_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_light_spec.rb)
-see: [https://serpapi.com/google-light-api](https://serpapi.com/google-light-api)
-
-### Search google scholar
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_scholar', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'biology'
-})
-
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/google-scholar-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_scholar_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_scholar_spec.rb)
-see: [https://serpapi.com/google-scholar-api](https://serpapi.com/google-scholar-api)
-
-### Search google autocomplete
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_autocomplete', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:suggestions]
-# doc: https://serpapi.com/google-autocomplete-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_autocomplete_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_autocomplete_spec.rb)
-see: [https://serpapi.com/google-autocomplete-api](https://serpapi.com/google-autocomplete-api)
-
-### Search google product
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_product', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee',
-  product_id: '4887235756540435899'
-})
-
-# print the output of the response in formatted JSON
-pp results[:product_results]
-# doc: https://serpapi.com/google-product-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_product_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_product_spec.rb)
-see: [https://serpapi.com/google-product-api](https://serpapi.com/google-product-api)
-
-### Search google reverse image
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_reverse_image', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  image_url: 'https://i.imgur.com/5bGzZi7.jpg'
-})
-
-# print the output of the response in formatted JSON
-pp results[:image_sizes]
-# doc: https://serpapi.com/google-reverse-image
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_reverse_image_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_reverse_image_spec.rb)
-see: [https://serpapi.com/google-reverse-image](https://serpapi.com/google-reverse-image)
-
-### Search google events
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_events', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:events_results]
-# doc: https://serpapi.com/google-events-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_events_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_events_spec.rb)
-see: [https://serpapi.com/google-events-api](https://serpapi.com/google-events-api)
-
-### Search google local services
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_local_services', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'electrician',
-  data_cid: '6745062158417646970'
-})
-
-# print the output of the response in formatted JSON
-pp results[:local_ads]
-# doc: https://serpapi.com/google-local-services-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_local_services_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/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)
-
-### Search google maps
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_maps', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'Coffee',
-  ll: '@40.7455096,-74.0083012,14z',
-  type: 'search'
-})
-
-# print the output of the response in formatted JSON
-pp results[:local_results]
-# doc: https://serpapi.com/google-maps-api
-```
+### Google Immersive Product
 
- * source code: [spec/serpapi/client/example/example_search_google_maps_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/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's immersive product listings to get rich product cards with images, prices, and seller details surfaced directly in search results.
 
-### Search google jobs
 ```ruby
 require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_jobs', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:jobs_results]
-# doc: https://serpapi.com/google-jobs-api
+client = SerpApi::Client.new(engine: 'google_immersive_product', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'coffee' })
+pp results[:immersive_product_results]
 ```
 
- * source code: [spec/serpapi/client/example/example_search_google_jobs_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_jobs_spec.rb)
-see: [https://serpapi.com/google-jobs-api](https://serpapi.com/google-jobs-api)
+[See documentation](https://serpapi.com/google-immersive-product-api)
 
-### Search google play
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_play', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'kite',
-  store: 'apps'
-})
+### Google Images
 
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/google-play-api
-```
+Scrape Google Images search results, including image URLs, thumbnails, titles, and source pages.
 
- * source code: [spec/serpapi/client/example/example_search_google_play_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_play_spec.rb)
-see: [https://serpapi.com/google-play-api](https://serpapi.com/google-play-api)
-
-### Search google images
 ```ruby
 require 'serpapi'
-# initialize the serp api client
 client = SerpApi::Client.new(engine: 'google_images', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  tbm: 'isch',
-  q: 'coffee'
-})
-
-# print the output of the response in formatted JSON
+results = client.search({ tbm: 'isch', q: 'coffee' })
 pp results[:images_results]
-# doc: https://serpapi.com/images-results
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_images_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_images_spec.rb)
-see: [https://serpapi.com/images-results](https://serpapi.com/images-results)
-
-### Search google lens
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_lens', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  url: 'https://i.imgur.com/HBrB8p0.png'
-})
-
-# print the output of the response in formatted JSON
-pp results[:visual_matches]
-# doc: https://serpapi.com/google-lens-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_lens_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_lens_spec.rb)
-see: [https://serpapi.com/google-lens-api](https://serpapi.com/google-lens-api)
-
-### Search google images light
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_images_light', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'Coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:images_results]
-# doc: https://serpapi.com/google-images-light-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_images_light_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/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)
-
-### Search google hotels
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_hotels', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'Bali Resorts',
-  check_in_date: '2025-05-26',
-  check_out_date: '2025-05-27',
-  adults: '2',
-  currency: 'USD',
-  gl: 'us',
-  hl: 'en'
-})
-
-# print the output of the response in formatted JSON
-pp results[:properties]
-# doc: https://serpapi.com/google-hotels-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_hotels_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_hotels_spec.rb)
-see: [https://serpapi.com/google-hotels-api](https://serpapi.com/google-hotels-api)
-
-### Search google flights
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_flights', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  departure_id: 'PEK',
-  arrival_id: 'AUS',
-  outbound_date: '2025-05-26',
-  return_date: '2025-06-01',
-  currency: 'USD',
-  hl: 'en'
-})
-
-# print the output of the response in formatted JSON
-pp results[:best_flights]
-# doc: https://serpapi.com/google-flights-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_flights_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_flights_spec.rb)
-see: [https://serpapi.com/google-flights-api](https://serpapi.com/google-flights-api)
-
-### Search google finance
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_finance', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'GOOG:NASDAQ'
-})
-
-# print the output of the response in formatted JSON
-pp results[:markets]
-# doc: https://serpapi.com/google-finance-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_finance_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_finance_spec.rb)
-see: [https://serpapi.com/google-finance-api](https://serpapi.com/google-finance-api)
-
-### Search google ai overview
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_ai_overview', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  page_token: 'KIVu-nictZPdjrI4GMeTPdkrWU8cFXV0dBKyKbUgiigy6OgJQawFQapUBpmzvZe9qr2aLYzO6I5vsm-yW0Ip7dPn4__L88efoR8Ff_36i3c87tlzrZamaZVQSkJcdemu5rAscmsbGrLY9X5PkhCLaRkC1VCh6hivs_e1EiaaPA2xIr9r8ixxXqfhEkova0UWlq-jEgnFhJW8UMRRKXsTmyWXiUIJ-2JTJ2jZxnTINvK-8zgJBtEiM4JSEVG0Vw7DW57Qactqdo1PwW_NHv-psiqObMusqpNU7ZM-OFlWFbNWdVxzdtwE_NsBv5YSJMblF5K71vwcgkAqlvk0569vIPXsx0D5pALt0Tbd6yAqUD4jJfxVZYAu0dN8gc6H9MfREVKlyu2WWszcgQx4zCKlD0dGnmJ_wEu6mI5BBfQJHkknc_69LGK8gP5e65BzXTeDDEziu0wH0KitCRdXqK1i_qnXYpZLDV-6ApW7TlzvmoJE585mMs2icNfe4-28-dYBDwVGl31yZNcc9acEefre8kxQ1apS_YLQGFMuZZ7OAPSl_T0cXAD0hZDXTPjDUMp3ehlfAj3fAL2Uu3G55eJyL_isTbLgl7NcPpRLJ5-lLdwWMCDKD-E4FyvHE3CEfTrN0JkAzC8qCliQQ35jiMk5pQ9FFx-6WoU5gmBiqJIKJBW6eRflSYaFMTpXQhDwB8EtQgDMuyJcj-EP9iVwh5nSSA9O3PXh-MWakaC52oRuJREk3dxcmNHd6qeaz_1_uHq8NZMzV3if621rEmkOL62Za4KMnKuhX7XmmesIKAieuSZXXOFPcEXWKG_N71zTgitvTatgm3M1tv_k-l-1ZoEXf3xu-zTZkm_92obr02LIdCKkM_9oyVJMuo2t5Wmx8WBvdsfnfUzJg-2vn6XG4JitSwfRo2l5TTErO_GxnNI4KPtR2YnWMfXXpV0YU1FwWvG7NyOVXlyJvK129AUN6TFI3JPk4MZ4OfLdKNzoShtnpl3RfNxij748svedxMtmmI3e-gc6kgJFVye-qg48j7Rwo71OcbA7dA9-NBe2o2napHMzmuMFQWqr9zSVtJXmKbbej73jI7XHPaymnfBdEIqsmPg6RI_L1URaVmiJuY6N2ZtYb3U3zSen3mjV611h0y3tyDHbi_W_AU9HHA0'
-})
-
-# print the output of the response in formatted JSON
-pp results[:ai_overview]
-# doc: https://serpapi.com/google-ai-overview-api
 ```
 
- * source code: [spec/serpapi/client/example/example_search_google_ai_overview_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/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)
+[See documentation](https://serpapi.com/images-results)
 
-### Search google news
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_news', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'pizza',
-  gl: 'us',
-  hl: 'en'
-})
+**Google Images Light**
 
-# print the output of the response in formatted JSON
-pp results[:news_results]
-# doc: https://serpapi.com/google-news-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.
 
- * source code: [spec/serpapi/client/example/example_search_google_news_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_news_spec.rb)
-see: [https://serpapi.com/google-news-api](https://serpapi.com/google-news-api)
+### Google Shopping
 
-### Search google news light
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_news_light', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'pizza'
-})
-
-# print the output of the response in formatted JSON
-pp results[:news_results]
-# doc: https://serpapi.com/google-news-light-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_news_light_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/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)
+Scrape Google Shopping results with product names, prices, ratings, and merchant information.
 
-### Search google patents
 ```ruby
 require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_patents', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: '(Coffee)'
-})
-
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/google-patents-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_patents_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_patents_spec.rb)
-see: [https://serpapi.com/google-patents-api](https://serpapi.com/google-patents-api)
-
-### Search google trends
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_trends', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee,milk,bread,pasta,steak',
-  data_type: 'TIMESERIES'
-})
-
-# print the output of the response in formatted JSON
-pp results[:interest_over_time]
-# doc: https://serpapi.com/google-trends-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_trends_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_trends_spec.rb)
-see: [https://serpapi.com/google-trends-api](https://serpapi.com/google-trends-api)
-
-### Search google shopping
-```ruby
-require 'serpapi'
-# initialize the serp api client
 client = SerpApi::Client.new(engine: 'google_shopping', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'Macbook M4'
-})
-
-# print the output of the response in formatted JSON
+results = client.search({ q: 'Macbook M4' })
 pp results[:shopping_results]
-# doc: https://serpapi.com/google-shopping-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_shopping_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_shopping_spec.rb)
-see: [https://serpapi.com/google-shopping-api](https://serpapi.com/google-shopping-api)
-
-### Search google immersive product
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_immersive_product', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:immersive_product_results]
-# doc: https://serpapi.com/google-immersive-product-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_immersive_product_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/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)
-
-### Search google videos
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'google_videos', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/google-videos-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_google_videos_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_google_videos_spec.rb)
-see: [https://serpapi.com/google-videos-api](https://serpapi.com/google-videos-api)
-
-### Search amazon
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'amazon', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/amazon-search-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_amazon_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_amazon_spec.rb)
-see: [https://serpapi.com/amazon-search-api](https://serpapi.com/amazon-search-api)
-
-### Search baidu
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'baidu', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/baidu-search-api
 ```
 
- * source code: [spec/serpapi/client/example/example_search_baidu_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_baidu_spec.rb)
-see: [https://serpapi.com/baidu-search-api](https://serpapi.com/baidu-search-api)
+[See documentation](https://serpapi.com/google-shopping-api)
 
-### Search yahoo
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'yahoo', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  p: 'coffee'
-})
+**Google Shopping Light**
 
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/yahoo-search-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.
 
- * source code: [spec/serpapi/client/example/example_search_yahoo_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_yahoo_spec.rb)
-see: [https://serpapi.com/yahoo-search-api](https://serpapi.com/yahoo-search-api)
+### Google Maps
 
-### Search youtube
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'youtube', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  search_query: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:video_results]
-# doc: https://serpapi.com/youtube-search-api
-```
+Scrape Google Maps local search results with business names, addresses, ratings, and coordinates.
 
- * source code: [spec/serpapi/client/example/example_search_youtube_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_youtube_spec.rb)
-see: [https://serpapi.com/youtube-search-api](https://serpapi.com/youtube-search-api)
-
-### Search walmart
 ```ruby
 require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'walmart', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  query: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/walmart-search-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_walmart_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_walmart_spec.rb)
-see: [https://serpapi.com/walmart-search-api](https://serpapi.com/walmart-search-api)
-
-### Search ebay
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'ebay', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  _nkw: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/ebay-search-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_ebay_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_ebay_spec.rb)
-see: [https://serpapi.com/ebay-search-api](https://serpapi.com/ebay-search-api)
-
-### Search naver
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'naver', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
+client = SerpApi::Client.new(engine: 'google_maps', api_key: ENV['SERPAPI_KEY'])
 results = client.search({
-  query: 'coffee'
+  q: 'Coffee',
+  ll: '@40.7455096,-74.0083012,14z',
+  type: 'search'
 })
-
-# print the output of the response in formatted JSON
-pp results[:ads_results]
-# doc: https://serpapi.com/naver-search-api
+pp results[:local_results]
 ```
 
- * source code: [spec/serpapi/client/example/example_search_naver_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_naver_spec.rb)
-see: [https://serpapi.com/naver-search-api](https://serpapi.com/naver-search-api)
-
-### Search home depot
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'home_depot', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'table'
-})
-
-# print the output of the response in formatted JSON
-pp results[:products]
-# doc: https://serpapi.com/home-depot-search-api
-```
+[See documentation](https://serpapi.com/google-maps-api)
 
- * source code: [spec/serpapi/client/example/example_search_home_depot_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/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)
+**Google Maps Light**
 
-### Search apple app store
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'apple_app_store', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  term: 'coffee'
-})
+A [light variant](https://serpapi.com/google-maps-light-api) engine called `google_maps_light` is also available for faster, lower-cost local searches.
 
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/apple-app-store
-```
+### Google AI Overview API
 
- * source code: [spec/serpapi/client/example/example_search_apple_app_store_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_apple_app_store_spec.rb)
-see: [https://serpapi.com/apple-app-store](https://serpapi.com/apple-app-store)
+The AI Overview API returns the AI-generated summary shown at the top of Google Search results. The `page_token` is obtained from the `ai_overview` field of a regular Google search response.
 
-### Search duckduckgo
 ```ruby
 require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'duckduckgo', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  q: 'coffee'
-})
-
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/duckduckgo-search-api
-```
-
- * source code: [spec/serpapi/client/example/example_search_duckduckgo_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_duckduckgo_spec.rb)
-see: [https://serpapi.com/duckduckgo-search-api](https://serpapi.com/duckduckgo-search-api)
 
-### Search yandex
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'yandex', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  text: 'coffee'
-})
+# Run a Google search to get the page_token from the ai_overview field
+client = SerpApi::Client.new(engine: 'google', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'best coffee maker' })
+page_token = results[:ai_overview][:page_token]
 
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/yandex-search-api
+# Fetch the full AI overview using the page_token
+ai_client = SerpApi::Client.new(engine: 'google_ai_overview', api_key: ENV['SERPAPI_KEY'])
+ai_results = ai_client.search({ page_token: page_token })
+pp ai_results[:ai_overview]
 ```
 
- * source code: [spec/serpapi/client/example/example_search_yandex_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_yandex_spec.rb)
-see: [https://serpapi.com/yandex-search-api](https://serpapi.com/yandex-search-api)
+[See documentation](https://serpapi.com/google-ai-overview-api)
 
-### Search yelp
-```ruby
-require 'serpapi'
-# initialize the serp api client
-client = SerpApi::Client.new(engine: 'yelp', api_key: ENV['SERPAPI_KEY'])
-# run a search using serpapi service
-results = client.search({
-  find_desc: 'Coffee',
-  find_loc: 'New York, NY, USA'
-})
-
-# print the output of the response in formatted JSON
-pp results[:organic_results]
-# doc: https://serpapi.com/yelp-search-api
-```
+**Google AI Mode**
 
- * source code: [spec/serpapi/client/example/example_search_yelp_spec.rb](https://github.com/serpapi/serpapi-ruby/blob/master/spec/serpapi/client/example/example_search_yelp_spec.rb)
-see: [https://serpapi.com/yelp-search-api](https://serpapi.com/yelp-search-api)
+For Google AI Mode search results, use the `google` engine with the `udm` parameter set to `14`.
 
 ## Performance Comparison
 

From b5994636849c3ab3690baf789ac4545523258e21 Mon Sep 17 00:00:00 2001
From: Josef Strzibny <strzibny@strzibny.name>
Date: Fri, 12 Jun 2026 12:17:19 +0200
Subject: [PATCH 2/3] Redo examples section in README.md.erb

---
 README.md.erb | 183 +++++++++++++++++---------------------------------
 1 file changed, 63 insertions(+), 120 deletions(-)

diff --git a/README.md.erb b/README.md.erb
index 766add8..be2ff30 100644
--- a/README.md.erb
+++ b/README.md.erb
@@ -339,156 +339,99 @@ 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)
+Scrape Google's immersive product listings to get rich product cards with images, prices, and seller details surfaced directly in search results.
 
-### 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)
-
-### 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)
-
-### 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)
-
-### 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)
-
-### 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)
-
-### 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)
-
-### 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)
-
-### 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)
-
-### 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)
+```ruby
+require 'serpapi'
+client = SerpApi::Client.new(engine: 'google_immersive_product', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'coffee' })
+pp results[:immersive_product_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/google-immersive-product-api)
 
-### 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
 
-### 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)
+Scrape Google Images search results, including image URLs, thumbnails, titles, and source pages.
 
-### 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)
+```ruby
+require 'serpapi'
+client = SerpApi::Client.new(engine: 'google_images', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ tbm: 'isch', q: 'coffee' })
+pp results[:images_results]
+```
 
-### 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)
+[See documentation](https://serpapi.com/images-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)
+**Google Images Light**
 
-### 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)
+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 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)
+### Google Shopping
 
-### 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)
+Scrape Google Shopping results with product names, prices, ratings, and merchant information.
 
-### 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)
+```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 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)
+[See documentation](https://serpapi.com/google-shopping-api)
 
-### 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)
+**Google Shopping Light**
 
-### 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)
+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 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)
+### Google Maps
 
-### 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)
+Scrape Google Maps local search results with business names, addresses, ratings, and coordinates.
 
-### 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)
+```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 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)
+[See documentation](https://serpapi.com/google-maps-api)
 
-### 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)
+**Google Maps Light**
 
-### 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)
+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 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)
+### Google AI Overview API
 
-### 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)
+The AI Overview API returns the AI-generated summary shown at the top of Google Search results. The `page_token` is obtained from the `ai_overview` field of a regular Google search response.
 
-### 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)
+# run a Google search to get the page_token from the ai_overview field
+client = SerpApi::Client.new(engine: 'google', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ q: 'best coffee maker' })
+page_token = results[:ai_overview][:page_token]
 
-### 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)
+# fetch the full AI overview using the page_token
+ai_client = SerpApi::Client.new(engine: 'google_ai_overview', api_key: ENV['SERPAPI_KEY'])
+ai_results = ai_client.search({ page_token: page_token })
+pp ai_results[:ai_overview]
+```
 
-### 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)
+[See documentation](https://serpapi.com/google-ai-overview-api)
 
-### 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)
+For AI Mode search results (Google Search with `udm: 14`), use the `google` engine with the `udm` parameter set to `14`.
 
 ## Performance Comparison
 

From 0344c03b2702a641f777239a5027f168c9fd6743 Mon Sep 17 00:00:00 2001
From: Josef Strzibny <strzibny@strzibny.name>
Date: Mon, 20 Jul 2026 15:53:37 +0200
Subject: [PATCH 3/3] Add Bing and Amazon examples

---
 .gitignore                                    |  1 +
 README.md                                     | 62 ++++++++++++++-----
 README.md.erb                                 | 62 ++++++++++++++-----
 .../example/example_search_amazon_spec.rb     |  2 +-
 .../example/example_search_bing_spec.rb       | 22 +++++++
 .../example_search_google_ai_mode_spec.rb     | 20 ++++++
 .../example_search_google_ai_overview_spec.rb | 22 -------
 .../example_search_google_images_spec.rb      |  1 -
 ...le_search_google_immersive_product_spec.rb | 21 ++++---
 9 files changed, 147 insertions(+), 66 deletions(-)
 create mode 100644 spec/serpapi/client/example/example_search_bing_spec.rb
 create mode 100644 spec/serpapi/client/example/example_search_google_ai_mode_spec.rb
 delete mode 100644 spec/serpapi/client/example/example_search_google_ai_overview_spec.rb

diff --git a/.gitignore b/.gitignore
index 00f8b34..86232a1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -6,6 +6,7 @@ rdoc
 log
 websites
 .DS_Store
+.env
 
 ## BUNDLER
 *.gem
diff --git a/README.md b/README.md
index e93bfa8..762b43a 100644
--- a/README.md
+++ b/README.md
@@ -325,13 +325,21 @@ Here are some examples for some of our most popular APIs. You can find the full
 
 ### Google Immersive Product
 
-Scrape Google's immersive product listings to get rich product cards with images, prices, and seller details surfaced directly in search results.
+Retrieve detailed information about a product selected from Google Shopping results, including images, prices, stores, ratings, and reviews.
+
+> **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.
 
 ```ruby
 require 'serpapi'
-client = SerpApi::Client.new(engine: 'google_immersive_product', api_key: ENV['SERPAPI_KEY'])
-results = client.search({ q: 'coffee' })
-pp results[:immersive_product_results]
+
+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]
+
+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]
 ```
 
 [See documentation](https://serpapi.com/google-immersive-product-api)
@@ -343,7 +351,7 @@ Scrape Google Images search results, including image URLs, thumbnails, titles, a
 ```ruby
 require 'serpapi'
 client = SerpApi::Client.new(engine: 'google_images', api_key: ENV['SERPAPI_KEY'])
-results = client.search({ tbm: 'isch', q: 'coffee' })
+results = client.search({ q: 'coffee' })
 pp results[:images_results]
 ```
 
@@ -391,29 +399,49 @@ pp results[:local_results]
 
 A [light variant](https://serpapi.com/google-maps-light-api) engine called `google_maps_light` is also available for faster, lower-cost local searches.
 
-### Google AI Overview API
+### Google AI Mode API
 
-The AI Overview API returns the AI-generated summary shown at the top of Google Search results. The `page_token` is obtained from the `ai_overview` field of a regular Google search response.
+The Google AI Mode API returns AI-generated answers with structured text blocks, references, images, products, and more.
 
 ```ruby
 require 'serpapi'
 
-# Run a Google search to get the page_token from the ai_overview field
-client = SerpApi::Client.new(engine: 'google', api_key: ENV['SERPAPI_KEY'])
+client = SerpApi::Client.new(engine: 'google_ai_mode', api_key: ENV['SERPAPI_KEY'])
 results = client.search({ q: 'best coffee maker' })
-page_token = results[:ai_overview][:page_token]
+pp results[:reconstructed_markdown]
+```
+
+[See documentation](https://serpapi.com/google-ai-mode-api)
+
+### Bing Search
 
-# Fetch the full AI overview using the page_token
-ai_client = SerpApi::Client.new(engine: 'google_ai_overview', api_key: ENV['SERPAPI_KEY'])
-ai_results = ai_client.search({ page_token: page_token })
-pp ai_results[:ai_overview]
+Scrape Bing web search results, including organic results, ads, related searches, and more.
+
+```ruby
+require 'serpapi'
+
+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/google-ai-overview-api)
+[See documentation](https://serpapi.com/bing-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`.
 
-**Google AI Mode**
+```ruby
+require 'serpapi'
+
+client = SerpApi::Client.new(engine: 'amazon', api_key: ENV['SERPAPI_KEY'])
+results = client.search({ k: 'coffee' })
+pp results[:organic_results]
+```
 
-For Google AI Mode search results, use the `google` engine with the `udm` parameter set to `14`.
+[See documentation](https://serpapi.com/amazon-search-api)
 
 ## Performance Comparison
 
diff --git a/README.md.erb b/README.md.erb
index be2ff30..5024c4d 100644
--- a/README.md.erb
+++ b/README.md.erb
@@ -345,13 +345,21 @@ Here are some examples for some of our most popular APIs. You can find the full
 
 ### Google Immersive Product
 
-Scrape Google's immersive product listings to get rich product cards with images, prices, and seller details surfaced directly in search results.
+Retrieve detailed information about a product selected from Google Shopping results, including images, prices, stores, ratings, and reviews.
+
+> **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.
 
 ```ruby
 require 'serpapi'
-client = SerpApi::Client.new(engine: 'google_immersive_product', api_key: ENV['SERPAPI_KEY'])
-results = client.search({ q: 'coffee' })
-pp results[:immersive_product_results]
+
+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]
+
+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]
 ```
 
 [See documentation](https://serpapi.com/google-immersive-product-api)
@@ -363,7 +371,7 @@ Scrape Google Images search results, including image URLs, thumbnails, titles, a
 ```ruby
 require 'serpapi'
 client = SerpApi::Client.new(engine: 'google_images', api_key: ENV['SERPAPI_KEY'])
-results = client.search({ tbm: 'isch', q: 'coffee' })
+results = client.search({ q: 'coffee' })
 pp results[:images_results]
 ```
 
@@ -411,27 +419,49 @@ pp results[:local_results]
 
 A [light variant](https://serpapi.com/google-maps-light-api) engine called `google_maps_light` is also available for faster, lower-cost local searches.
 
-### Google AI Overview API
+### Google AI Mode API
 
-The AI Overview API returns the AI-generated summary shown at the top of Google Search results. The `page_token` is obtained from the `ai_overview` field of a regular Google search response.
+The Google AI Mode API returns AI-generated answers with structured text blocks, references, images, products, and more.
 
 ```ruby
 require 'serpapi'
 
-# run a Google search to get the page_token from the ai_overview field
-client = SerpApi::Client.new(engine: 'google', api_key: ENV['SERPAPI_KEY'])
+client = SerpApi::Client.new(engine: 'google_ai_mode', api_key: ENV['SERPAPI_KEY'])
 results = client.search({ q: 'best coffee maker' })
-page_token = results[:ai_overview][:page_token]
+pp results[:reconstructed_markdown]
+```
+
+[See documentation](https://serpapi.com/google-ai-mode-api)
+
+### Bing Search
+
+Scrape Bing web search results, including organic results, ads, related searches, and more.
+
+```ruby
+require 'serpapi'
 
-# fetch the full AI overview using the page_token
-ai_client = SerpApi::Client.new(engine: 'google_ai_overview', api_key: ENV['SERPAPI_KEY'])
-ai_results = ai_client.search({ page_token: page_token })
-pp ai_results[:ai_overview]
+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/google-ai-overview-api)
+[See documentation](https://serpapi.com/bing-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]
+```
 
-For AI Mode search results (Google Search with `udm: 14`), use the `google` engine with the `udm` parameter set to `14`.
+[See documentation](https://serpapi.com/amazon-search-api)
 
 ## Performance Comparison
 
diff --git a/spec/serpapi/client/example/example_search_amazon_spec.rb b/spec/serpapi/client/example/example_search_amazon_spec.rb
index c6afcb3..0a3476c 100644
--- a/spec/serpapi/client/example/example_search_amazon_spec.rb
+++ b/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}"
 
diff --git a/spec/serpapi/client/example/example_search_bing_spec.rb b/spec/serpapi/client/example/example_search_bing_spec.rb
new file mode 100644
index 0000000..dbd002d
--- /dev/null
+++ b/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
diff --git a/spec/serpapi/client/example/example_search_google_ai_mode_spec.rb b/spec/serpapi/client/example/example_search_google_ai_mode_spec.rb
new file mode 100644
index 0000000..4b6964b
--- /dev/null
+++ b/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
diff --git a/spec/serpapi/client/example/example_search_google_ai_overview_spec.rb b/spec/serpapi/client/example/example_search_google_ai_overview_spec.rb
deleted file mode 100644
index a8a286a..0000000
--- a/spec/serpapi/client/example/example_search_google_ai_overview_spec.rb
+++ /dev/null
@@ -1,22 +0,0 @@
-require 'spec_helper'
-
-describe 'example: google_ai_overview search' do
-  it 'prints ai_overview' 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_ai_overview', api_key: api_key)
-    # run a search using serpapi service
-    results = client.search({
-      page_token: 'KIVu-nictZPdjrI4GMeTPdkrWU8cFXV0dBKyKbUgiigy6OgJQawFQapUBpmzvZe9qr2aLYzO6I5vsm-yW0Ip7dPn4__L88efoR8Ff_36i3c87tlzrZamaZVQSkJcdemu5rAscmsbGrLY9X5PkhCLaRkC1VCh6hivs_e1EiaaPA2xIr9r8ixxXqfhEkova0UWlq-jEgnFhJW8UMRRKXsTmyWXiUIJ-2JTJ2jZxnTINvK-8zgJBtEiM4JSEVG0Vw7DW57Qactqdo1PwW_NHv-psiqObMusqpNU7ZM-OFlWFbNWdVxzdtwE_NsBv5YSJMblF5K71vwcgkAqlvk0569vIPXsx0D5pALt0Tbd6yAqUD4jJfxVZYAu0dN8gc6H9MfREVKlyu2WWszcgQx4zCKlD0dGnmJ_wEu6mI5BBfQJHkknc_69LGK8gP5e65BzXTeDDEziu0wH0KitCRdXqK1i_qnXYpZLDV-6ApW7TlzvmoJE585mMs2icNfe4-28-dYBDwVGl31yZNcc9acEefre8kxQ1apS_YLQGFMuZZ7OAPSl_T0cXAD0hZDXTPjDUMp3ehlfAj3fAL2Uu3G55eJyL_isTbLgl7NcPpRLJ5-lLdwWMCDKD-E4FyvHE3CEfTrN0JkAzC8qCliQQ35jiMk5pQ9FFx-6WoU5gmBiqJIKJBW6eRflSYaFMTpXQhDwB8EtQgDMuyJcj-EP9iVwh5nSSA9O3PXh-MWakaC52oRuJREk3dxcmNHd6qeaz_1_uHq8NZMzV3if621rEmkOL62Za4KMnKuhX7XmmesIKAieuSZXXOFPcEXWKG_N71zTgitvTatgm3M1tv_k-l-1ZoEXf3xu-zTZkm_92obr02LIdCKkM_9oyVJMuo2t5Wmx8WBvdsfnfUzJg-2vn6XG4JitSwfRo2l5TTErO_GxnNI4KPtR2YnWMfXXpV0YU1FwWvG7NyOVXlyJvK129AUN6TFI3JPk4MZ4OfLdKNzoShtnpl3RfNxij748svedxMtmmI3e-gc6kgJFVye-qg48j7Rwo71OcbA7dA9-NBe2o2napHMzmuMFQWqr9zSVtJXmKbbej73jI7XHPaymnfBdEIqsmPg6RI_L1URaVmiJuY6N2ZtYb3U3zSen3mjV611h0y3tyDHbi_W_AU9HHA0'
-    })
-    expect(results[:ai_overview]).not_to be_nil, "No ai overview found! keys available: #{results.keys}"
-
-    # print the output of the response in formatted JSON
-    # pp results[:ai_overview]
-    # doc: https://serpapi.com/google-ai-overview-api
-  end
-end
diff --git a/spec/serpapi/client/example/example_search_google_images_spec.rb b/spec/serpapi/client/example/example_search_google_images_spec.rb
index c36da21..f49ca96 100644
--- a/spec/serpapi/client/example/example_search_google_images_spec.rb
+++ b/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}"
diff --git a/spec/serpapi/client/example/example_search_google_immersive_product_spec.rb b/spec/serpapi/client/example/example_search_google_immersive_product_spec.rb
index e4585c7..e34a6e5 100644
--- a/spec/serpapi/client/example/example_search_google_immersive_product_spec.rb
+++ b/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