GitHub - AAlvAAro/searchapi-ruby

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

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

# 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

# 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

# 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

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

# 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

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

# 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

response = SearchApi.google_hotels.search("hotels in Paris",
  check_in: "2026-06-15",
  check_out: "2026-06-18"
)

Google Images

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

response = SearchApi.google_videos.search("ruby tutorial")

# With filters
response = SearchApi.google_videos.search("cooking pasta",
  duration: "medium",
  time_period: "last_month"
)

Google Trends

# 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

response = SearchApi.google_jobs.search("software engineer")

# With filters
response = SearchApi.google_jobs.search("data scientist",
  location: "San Francisco, CA",
  gl: "us"
)

Google Events

response = SearchApi.google_events.search("concerts in Austin")

# Filter by date
response = SearchApi.google_events.search("tech conferences",
  chips: "date:next_week"
)

Google Finance

# 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

response = SearchApi.google_autocomplete.search("how to learn")

# With client specification
response = SearchApi.google_autocomplete.search("best restaurants",
  client: "chrome",
  gl: "us"
)

Google Local

response = SearchApi.google_local.search("pizza delivery",
  location: "Chicago, IL"
)

Google Forums

response = SearchApi.google_forums.search("best ruby gems 2026",
  time_period: "last_year"
)

Google Shorts

response = SearchApi.google_shorts.search("funny cats")

Google Patents

response = SearchApi.google_patents.search("solar panel efficiency",
  patent_status: "GRANT",
  num: 20
)

Google Lens

response = SearchApi.google_lens.search(
  url: "https://example.com/image.jpg",
  search_type: "products"
)

Google AI Mode

response = SearchApi.google_ai_mode.search("explain quantum computing simply")

Google AI Overview

# 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

response = SearchApi.google_about_this_domain.search(domain: "github.com")

Google Ads Transparency Center

# 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

# 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

response = SearchApi.youtube.search("ruby on rails tutorial")

# With parameters
response = SearchApi.youtube.search("cooking", gl: "us", hl: "en")

Bing

response = SearchApi.bing.search("artificial intelligence")

# With parameters
response = SearchApi.bing.search("web development",
  num: 30,
  market_code: "en-US"
)

Bing Images

response = SearchApi.bing_images.search("mountain landscape", size: "large")

Bing Videos

response = SearchApi.bing_videos.search("cooking tutorial", duration: "short")

Baidu

response = SearchApi.baidu.search("人工智能", num: 20)

Yandex

response = SearchApi.yandex.search("programming tutorials", lang: "en")

Yandex Reverse Image

response = SearchApi.yandex_reverse_image.search(
  url: "https://example.com/photo.jpg"
)

DuckDuckGo

response = SearchApi.duckduckgo.search("privacy tools", safe: "moderate")

Yahoo

response = SearchApi.yahoo.search("weather forecast",
  yahoo_domain: "search.yahoo.com"
)

Naver

response = SearchApi.naver.search("한국 뉴스", page: 2)

Amazon

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

response = SearchApi.walmart_search.search("organic coffee", sort_by: "price_low")

eBay

# 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

response = SearchApi.shein_search.search("summer dress",
  sort_by: "price_asc",
  currency: "USD"
)

Airbnb

response = SearchApi.airbnb.search("Tulum",
  check_in: "2026-06-15",
  check_out: "2026-06-22",
  adults: 2,
  price_max: 200
)

TripAdvisor

response = SearchApi.tripadvisor.search("best restaurants in Rome",
  category: "restaurants"
)

Apple App Store

response = SearchApi.apple_app_store.search(term: "photo editor",
  country: "us",
  num: 50
)

Instagram Profile

response = SearchApi.instagram_profile.search(username: "natgeo")

profile = response.data["profile"]
posts = response.data["posts"]

TikTok Profile

response = SearchApi.tiktok_profile.search(username: "tiktok")

profile = response.data["profile"]

Facebook Business Page

# 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

response = SearchApi.linkedin_ad_library.search(
  advertiser: "Google",
  country: "US"
)

Reddit Ad Library

response = SearchApi.reddit_ad_library.search(
  q: "gaming",
  industry: "GAMING",
  budget_category: "HIGH"
)

Meta Ad Library

response = SearchApi.meta_ad_library.search(
  q: "sneakers",
  active_status: "active",
  platforms: "instagram"
)

TikTok Ads Library

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.

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
assets		assets
lib		lib
spec		spec
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
Gemfile		Gemfile
LICENSE.txt		LICENSE.txt
README.md		README.md
Rakefile		Rakefile
searchapi-ruby.gemspec		searchapi-ruby.gemspec

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Table of Contents

Installation

Quick Start

Configuration

Supported Engines

Usage

Error Handling

Advanced Usage

Custom Client Instance

Common Parameters

Zero Retention (Enterprise)

Contributing

License

About

Uh oh!

Releases

Packages

Languages

License

AAlvAAro/searchapi-ruby

Folders and files

Latest commit

History

Repository files navigation

Table of Contents

Installation

Quick Start

Configuration

Supported Engines

Usage

Error Handling

Advanced Usage

Custom Client Instance

Common Parameters

Zero Retention (Enterprise)

Contributing

License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages