SearchApi Ruby — an octopus holding a Ruby gem

Gem Version MIT License

Full-featured Ruby client for SearchAPI.io
Access 49 search engines from a single, consistent interface.

Google · Bing · Baidu · Yandex · DuckDuckGo · YouTube · Amazon · Walmart · eBay
Airbnb · TripAdvisor · Social Media · Ad Libraries · and much more

Table of Contents

Installation

Add to your Gemfile:

gem "searchapi-ruby"

Then run:

bundle install

Or install directly:

gem install searchapi-ruby

Quick Start

require "searchapi"

SearchApi.configure do |config|
  config.api_key = "your_api_key"
end

# Google search
response = SearchApi.google.search("ruby programming language")
puts response.data["organic_results"]

# YouTube search
response = SearchApi.youtube.search("ruby tutorial")
puts response.data["videos"]

# Amazon product search
response = SearchApi.amazon_search.search("wireless headphones")
puts response.data["organic_results"]

# Instagram profile
response = SearchApi.instagram_profile.search(username: "instagram")
puts response.data["profile"]

Configuration

SearchApi.configure do |config|
  config.api_key  = ENV["SEARCHAPI_API_KEY"] # default: reads from env
  config.base_url = "https://www.searchapi.io/api/v1" # default
  config.timeout  = 30 # seconds, default
  config.retries  = 2  # automatic retries on 429/5xx, default
  config.logger   = Logger.new($stdout) # optional, for debugging
end

Supported Engines

View all 49 supported engines | Category | Engine | Accessor | |----------|--------|----------| | **Google** | Google Search | `SearchApi.google` | | | Google Rank Tracking | `SearchApi.google_rank_tracking` | | | Google Maps | `SearchApi.google_maps` | | | Google Local | `SearchApi.google_local` | | | Google News | `SearchApi.google_news` | | | Google Scholar | `SearchApi.google_scholar` | | | Google Shopping | `SearchApi.google_shopping` | | | Google Flights | `SearchApi.google_flights` | | | Google Hotels | `SearchApi.google_hotels` | | | Google Images | `SearchApi.google_images` | | | Google Videos | `SearchApi.google_videos` | | | Google Shorts | `SearchApi.google_shorts` | | | Google Trends | `SearchApi.google_trends` | | | Google Jobs | `SearchApi.google_jobs` | | | Google Events | `SearchApi.google_events` | | | Google Finance | `SearchApi.google_finance` | | | Google Autocomplete | `SearchApi.google_autocomplete` | | | Google Forums | `SearchApi.google_forums` | | | Google Patents | `SearchApi.google_patents` | | | Google Lens | `SearchApi.google_lens` | | | Google AI Mode | `SearchApi.google_ai_mode` | | | Google AI Overview | `SearchApi.google_ai_overview` | | | Google About This Domain | `SearchApi.google_about_this_domain` | | | Google Ads Transparency | `SearchApi.google_ads_transparency_center` | | | Google Play Store | `SearchApi.google_play_store` | | **Other Search Engines** | Bing | `SearchApi.bing` | | | Bing Images | `SearchApi.bing_images` | | | Bing Videos | `SearchApi.bing_videos` | | | Baidu | `SearchApi.baidu` | | | Yandex | `SearchApi.yandex` | | | Yandex Reverse Image | `SearchApi.yandex_reverse_image` | | | DuckDuckGo | `SearchApi.duckduckgo` | | | Yahoo | `SearchApi.yahoo` | | | Naver | `SearchApi.naver` | | | YouTube | `SearchApi.youtube` | | **E-commerce** | Amazon | `SearchApi.amazon_search` | | | Walmart | `SearchApi.walmart_search` | | | eBay | `SearchApi.ebay_search` | | | Shein | `SearchApi.shein_search` | | **Travel** | Airbnb | `SearchApi.airbnb` | | | TripAdvisor | `SearchApi.tripadvisor` | | **App Stores** | Apple App Store | `SearchApi.apple_app_store` | | **Social Media** | Instagram Profile | `SearchApi.instagram_profile` | | | TikTok Profile | `SearchApi.tiktok_profile` | | | Facebook Business Page | `SearchApi.facebook_business_page` | | **Ad Libraries** | LinkedIn Ad Library | `SearchApi.linkedin_ad_library` | | | Reddit Ad Library | `SearchApi.reddit_ad_library` | | | Meta Ad Library | `SearchApi.meta_ad_library` | | | TikTok Ads Library | `SearchApi.tiktok_ads_library` |

Usage

Google Search ```ruby # Basic search response = SearchApi.google.search("ruby programming") # With parameters response = SearchApi.google.search("ruby programming", gl: "us", hl: "en", num: 10, page: 1 ) ```
Google Rank Tracking ```ruby # Track rankings (up to 100 results per request) response = SearchApi.google_rank_tracking.search("best crm software", num: 100) # With location targeting response = SearchApi.google_rank_tracking.search("plumber near me", num: 50, location: "New York, NY" ) ```
Google Maps ```ruby # Search for places response = SearchApi.google_maps.search("restaurants in Tokyo") # With GPS coordinates response = SearchApi.google_maps.search("coffee", ll: "@35.6762,139.6503,15z") # Get place details response = SearchApi.google_maps.place(data_id: "0x60188b857...") # Get directions response = SearchApi.google_maps.directions( start: "Tokyo Station", destination: "Shibuya Station" ) ```
Google News ```ruby response = SearchApi.google_news.search("artificial intelligence") # Filter by time period response = SearchApi.google_news.search("tech startups", time_period: "last_week", gl: "us" ) ```
Google Scholar ```ruby # Search papers response = SearchApi.google_scholar.search("machine learning") # Filter by year response = SearchApi.google_scholar.search("deep learning", as_ylo: 2023, as_yhi: 2026 ) # Find citing articles response = SearchApi.google_scholar.cite("article_id_here") ```
Google Shopping ```ruby response = SearchApi.google_shopping.search("laptop") # With filters response = SearchApi.google_shopping.search("headphones", sort_by: "price_low_to_high", price_min: 50, price_max: 200, condition: "new" ) ```
Google Flights ```ruby # Round trip response = SearchApi.google_flights.search( from: "JFK", to: "LAX", outbound_date: "2026-06-15", return_date: "2026-06-22" ) # One way response = SearchApi.google_flights.search( from: "SFO", to: "ORD", outbound_date: "2026-07-01", flight_type: "one_way", travel_class: "business" ) ```
Google Hotels ```ruby response = SearchApi.google_hotels.search("hotels in Paris", check_in: "2026-06-15", check_out: "2026-06-18" ) ```
Google Images ```ruby response = SearchApi.google_images.search("sunset over ocean") # With filters response = SearchApi.google_images.search("logo design", color: "red", size: "large", image_type: "clipart" ) ```
Google Videos ```ruby response = SearchApi.google_videos.search("ruby tutorial") # With filters response = SearchApi.google_videos.search("cooking pasta", duration: "medium", time_period: "last_month" ) ```
Google Trends ```ruby # Interest over time response = SearchApi.google_trends.interest_over_time("ruby, python, javascript") # Interest by region response = SearchApi.google_trends.interest_by_region("react", geo: "US") # Related queries response = SearchApi.google_trends.related_queries("machine learning") # Related topics response = SearchApi.google_trends.related_topics("artificial intelligence") # Direct search with data_type response = SearchApi.google_trends.search("web development", data_type: "TIMESERIES", time: "today 12-m" ) ```
Google Jobs ```ruby response = SearchApi.google_jobs.search("software engineer") # With filters response = SearchApi.google_jobs.search("data scientist", location: "San Francisco, CA", gl: "us" ) ```
Google Events ```ruby response = SearchApi.google_events.search("concerts in Austin") # Filter by date response = SearchApi.google_events.search("tech conferences", chips: "date:next_week" ) ```
Google Finance ```ruby # Stock quote response = SearchApi.google_finance.search("NVDA:NASDAQ") # With time window response = SearchApi.google_finance.search("AAPL:NASDAQ", window: "1Y") # Crypto response = SearchApi.google_finance.search("BTC-USD") ```
Google Autocomplete ```ruby response = SearchApi.google_autocomplete.search("how to learn") # With client specification response = SearchApi.google_autocomplete.search("best restaurants", client: "chrome", gl: "us" ) ```
Google Local ```ruby response = SearchApi.google_local.search("pizza delivery", location: "Chicago, IL" ) ```
Google Forums ```ruby response = SearchApi.google_forums.search("best ruby gems 2026", time_period: "last_year" ) ```
Google Shorts ```ruby response = SearchApi.google_shorts.search("funny cats") ```
Google Patents ```ruby response = SearchApi.google_patents.search("solar panel efficiency", patent_status: "GRANT", num: 20 ) ```
Google Lens ```ruby response = SearchApi.google_lens.search( url: "https://example.com/image.jpg", search_type: "products" ) ```
Google AI Mode ```ruby response = SearchApi.google_ai_mode.search("explain quantum computing simply") ```
Google AI Overview ```ruby # Requires a page_token from a prior Google Search response response = SearchApi.google_ai_overview.search(page_token: "token_from_google_search") ```
Google About This Domain ```ruby response = SearchApi.google_about_this_domain.search(domain: "github.com") ```
Google Ads Transparency Center ```ruby # Search by advertiser response = SearchApi.google_ads_transparency_center.by_advertiser("AR01234567890") # Search by domain response = SearchApi.google_ads_transparency_center.by_domain("example.com", region: "US" ) # Generic search response = SearchApi.google_ads_transparency_center.search( advertiser_id: "AR01234567890", region: "US" ) ```
Google Play Store ```ruby # Search apps response = SearchApi.google_play_store.apps("calculator") # Browse games response = SearchApi.google_play_store.games # Search movies response = SearchApi.google_play_store.movies("action") # Search books response = SearchApi.google_play_store.books("ruby programming") # Direct search with store parameter response = SearchApi.google_play_store.search(store: "apps", q: "fitness", gl: "us") ```
YouTube ```ruby response = SearchApi.youtube.search("ruby on rails tutorial") # With parameters response = SearchApi.youtube.search("cooking", gl: "us", hl: "en") ```
Bing ```ruby response = SearchApi.bing.search("artificial intelligence") # With parameters response = SearchApi.bing.search("web development", num: 30, market_code: "en-US" ) ```
Bing Images ```ruby response = SearchApi.bing_images.search("mountain landscape", size: "large") ```
Bing Videos ```ruby response = SearchApi.bing_videos.search("cooking tutorial", duration: "short") ```
Baidu ```ruby response = SearchApi.baidu.search("人工智能", num: 20) ```
Yandex ```ruby response = SearchApi.yandex.search("programming tutorials", lang: "en") ```
Yandex Reverse Image ```ruby response = SearchApi.yandex_reverse_image.search( url: "https://example.com/photo.jpg" ) ```
DuckDuckGo ```ruby response = SearchApi.duckduckgo.search("privacy tools", safe: "moderate") ```
Yahoo ```ruby response = SearchApi.yahoo.search("weather forecast", yahoo_domain: "search.yahoo.com" ) ```
Naver ```ruby response = SearchApi.naver.search("한국 뉴스", page: 2) ```
Amazon ```ruby response = SearchApi.amazon_search.search("wireless headphones") # With filters response = SearchApi.amazon_search.search("organic coffee", amazon_domain: "amazon.co.uk", sort_by: "price_asc", page: 2 ) ```
Walmart ```ruby response = SearchApi.walmart_search.search("organic coffee", sort_by: "price_low") ```
eBay ```ruby # Search with query response = SearchApi.ebay_search.search("vintage watch") # Browse by category response = SearchApi.ebay_search.search(category_id: "123") # With filters response = SearchApi.ebay_search.search("laptop", condition: "new", price_min: 500, price_max: 1500 ) ```
Shein ```ruby response = SearchApi.shein_search.search("summer dress", sort_by: "price_asc", currency: "USD" ) ```
Airbnb ```ruby response = SearchApi.airbnb.search("Tulum", check_in: "2026-06-15", check_out: "2026-06-22", adults: 2, price_max: 200 ) ```
TripAdvisor ```ruby response = SearchApi.tripadvisor.search("best restaurants in Rome", category: "restaurants" ) ```
Apple App Store ```ruby response = SearchApi.apple_app_store.search(term: "photo editor", country: "us", num: 50 ) ```
Instagram Profile ```ruby response = SearchApi.instagram_profile.search(username: "natgeo") profile = response.data["profile"] posts = response.data["posts"] ```
TikTok Profile ```ruby response = SearchApi.tiktok_profile.search(username: "tiktok") profile = response.data["profile"] ```
Facebook Business Page ```ruby # By username response = SearchApi.facebook_business_page.by_username("cocacola") # By page ID response = SearchApi.facebook_business_page.by_page_id("123456789") # Generic search response = SearchApi.facebook_business_page.search(username: "nasa") ```
LinkedIn Ad Library ```ruby response = SearchApi.linkedin_ad_library.search( advertiser: "Google", country: "US" ) ```
Reddit Ad Library ```ruby response = SearchApi.reddit_ad_library.search( q: "gaming", industry: "GAMING", budget_category: "HIGH" ) ```
Meta Ad Library ```ruby response = SearchApi.meta_ad_library.search( q: "sneakers", active_status: "active", platforms: "instagram" ) ```
TikTok Ads Library ```ruby response = SearchApi.tiktok_ads_library.search( q: "fashion", country: "US", sort_by: "last_shown_date_newest_to_oldest" ) ```

Response Object

Every API call returns a SearchApi::Response:

response = SearchApi.google.search("ruby")

response.success?          # => true
response.status            # => 200
response.data              # => parsed JSON hash (full response)
response.results           # => same as data when it's a Hash
response.headers           # => response headers
response.credits_remaining # => remaining API credits (integer)

Error Handling

All errors inherit from SearchApi::Error:

begin
  SearchApi.google.search("ruby")
rescue SearchApi::AuthenticationError => e
  # Invalid or missing API key (401)
rescue SearchApi::RateLimitError => e
  # Too many requests (429)
rescue SearchApi::NotFoundError => e
  # Resource not found (404)
rescue SearchApi::TimeoutError => e
  # Request timed out or connection failed
rescue SearchApi::ServerError => e
  # Server-side error (5xx)
rescue SearchApi::Error => e
  # Catch-all for any SearchApi error
end

Automatic retries are built in for 429, 500, 502, and 503 status codes (configurable via config.retries).

Advanced Usage

Custom Client Instance

You can create a standalone client instead of using the global module:

config = SearchApi::Configuration.new
config.api_key = "different_api_key"
config.timeout = 60

client = SearchApi::Client.new(config)
google = SearchApi::Resources::Google.new(client)

response = google.search("ruby programming")

Common Parameters

Most Google engines support these shared parameters:

Parameter Description Example
gl Country code (ISO 3166-1 alpha-2) "us", "gb", "jp"
hl Language code "en", "es", "ja"
location Geo-targeting location "New York, NY"
device Device type "desktop", "mobile", "tablet"
page Pagination 1, 2, 3
safe SafeSearch "active", "off"
num Results per page 10, 20, 100

See the SearchAPI documentation for the full parameter reference of each engine.

Zero Retention (Enterprise)

Disable data logging for compliance scenarios:

response = SearchApi.google.search("sensitive query", zero_retention: true)

Contributing

Bug reports and pull requests are welcome! See CONTRIBUTING.md for guidelines.

License

Released under the MIT License.