{"id":13878187,"url":"https://github.com/serpapi/google-search-results-ruby","last_synced_at":"2025-05-16T18:09:36.923Z","repository":{"id":27560063,"uuid":"114412768","full_name":"serpapi/google-search-results-ruby","owner":"serpapi","description":"Google Search Results via SERP API Ruby Gem","archived":false,"fork":false,"pushed_at":"2025-03-07T21:30:30.000Z","size":129,"stargazers_count":62,"open_issues_count":5,"forks_count":12,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-05-11T14:47:47.887Z","etag":null,"topics":["api","ruby","rubygems","serp-api"],"latest_commit_sha":null,"homepage":"https://serpapi.com","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/serpapi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2017-12-15T21:31:23.000Z","updated_at":"2025-03-28T20:10:42.000Z","dependencies_parsed_at":"2023-12-22T16:45:02.135Z","dependency_job_id":"8a2c2409-2c40-43bb-8838-43ba6e1b886a","html_url":"https://github.com/serpapi/google-search-results-ruby","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpapi%2Fgoogle-search-results-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpapi%2Fgoogle-search-results-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpapi%2Fgoogle-search-results-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serpapi%2Fgoogle-search-results-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serpapi","download_url":"https://codeload.github.com/serpapi/google-search-results-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254582907,"owners_count":22095518,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","ruby","rubygems","serp-api"],"created_at":"2024-08-06T08:01:42.219Z","updated_at":"2025-05-16T18:09:36.901Z","avatar_url":"https://github.com/serpapi.png","language":"Ruby","readme":"# Google Search Results in Ruby\n\n[![serpapi-search-ruby](https://github.com/serpapi/google-search-results-ruby/actions/workflows/ruby.yml/badge.svg)](https://github.com/serpapi/google-search-results-ruby/actions/workflows/ruby.yml)\n[![Gem Version](https://badge.fury.io/rb/google_search_results.svg)](https://rubygems.org/gems/google_search_results)\n\nThis Ruby Gem is meant to scrape and parse results from Google, Bing, Baidu, Yandex, Yahoo, Ebay and more using [SerpApi](https://serpapi.com).\n\nThe following services are provided:\n\n  * [Search API](https://serpapi.com/search-api)\n  * [Location API](https://serpapi.com/locations-api)\n  * [Search Archive API](https://serpapi.com/search-archive-api)\n  * [Account API](https://serpapi.com/account-api)\n\nSerpApi.com provides a [script builder](https://serpapi.com/playground) to get you started quickly.\n\n## Installation\n\nModern Ruby must be already installed:\n\n```bash\n$ gem install google_search_results\n```\n\n[Link to the gem page](https://rubygems.org/gems/google_search_results/)\n\nTested Ruby versions:\n\n - 2.5\n - 3.0\n - 3.1\n - 3.2\n\nSee: [GitHub Actions](https://github.com/serpapi/google-search-results-ruby/blob/9cbd9d64786aeff9765a2417ae007a1fb43ab110/.github/workflows/ruby.yml#L16).\n\n## Quick start\n\n```ruby\nrequire 'google_search_results'\nsearch = GoogleSearch.new(q: \"coffee\", serp_api_key: \"secret_api_key\")\nhash_results = search.get_hash\n ```\n\nThis example runs a search about \"coffee\" using your secret api key.\n\nThe SerpApi.com service (backend)\n - searches on Google using the search: q = \"coffee\"\n - parses the messy HTML responses\n - return a standardizes JSON response\nThe class GoogleSearch\n - Format the request to SerpApi.com server\n - Execute GET http request\n - Parse JSON into Ruby Hash using JSON standard library provided by Ruby\nEt voila..\n\nAlternatively, you can search:\n - Bing using BingSearch class\n - Baidu using BaiduSearch class\n - Yahoo using YahooSearch class\n - Yandex using YandexSearch class\n - Ebay using EbaySearch class\n - Home depot using HomeDepotSearch class\n - Youtube using YoutubeSearch class\n\nSee the [playground to generate your code.](https://serpapi.com/playground)\n\n### Summary\n- [Google Search Results in Ruby](#google-search-results-in-ruby)\n  - [Installation](#installation)\n  - [Quick start](#quick-start)\n- [Summary](#summary)\n  - [Guide](#guide)\n    - [How to set the private API key](#how-to-set-the-private-api-key)\n    - [Search API capability for Google](#search-api-capability-for-google)\n    - [Example by specification](#example-by-specification)\n    - [Location API](#location-api)\n    - [Search Archive API](#search-archive-api)\n    - [Account API](#account-api)\n    - [Search Google Images](#search-google-images)\n    - [Search Google News](#search-google-news)\n    - [Search Google Shopping](#search-google-shopping)\n    - [Google Search By Location](#google-search-by-location)\n    - [Batch Asynchronous search](#batch-asynchronous-search)\n  - [Supported search engine](#supported-search-engine)\n    - [Google search API](#google-search-api)\n    - [Bing search API](#bing-search-api)\n    - [Baidu search API](#baidu-search-api)\n    - [Yahoo search API](#yahoo-search-api)\n    - [Yandex search API](#yandex-search-api)\n    - [Ebay search API](#ebay-search-api)\n    - [Generic SerpApi search](#generic-serpapi-search)\n- [Error management](#error-management)\n- [Change log](#change-log)\n- [Roadmap](#roadmap)\n- [Conclusion](#conclusion)\n- [Contributing](#contributing)\n\n## Guide\n### How to set the private API key\nThe api_key can be set globally using a singleton pattern.\n\n```ruby\nGoogleSearch.api_key = \"secret_api_key\"\nsearch = GoogleSearch.new(q: \"coffee\")\n```\n\nor api_key can be provided for each search.\n\n```ruby\nsearch = GoogleSearch.new(q: \"coffee\", api_key: \"secret_api_key\")\n```\n\nTo get the key simply copy/paste from [serpapi.com/dashboard](https://serpapi.com/dashboard).\n\n### Search API capability for Google\n\n```ruby\nsearch_params = {\n  q: \"search\",\n  google_domain: \"Google Domain\",\n  location: \"Location Requested\",\n  device: \"desktop|mobile|tablet\",\n  hl: \"Google UI Language\",\n  gl: \"Google Country\",\n  safe: \"Safe Search Flag\",\n  num: \"Number of Results\",\n  start: \"Pagination Offset\",\n  api_key: \"private key\", # copy paste from https://serpapi.com/dashboard\n  tbm: \"nws|isch|shop\",\n  tbs: \"custom to be search criteria\",\n  async: true|false # allow async\n}\n\n# define the search search\nsearch = GoogleSearch.new(search_params)\n\n# override an existing parameter\nsearch.params[:location] = \"Portland,Oregon,United States\"\n\n# search format return as raw html\nhtml_results = search.get_html\n\n# search format returns a Hash\nhash_results = search.get_hash\n\n# search as raw JSON format\njson_results = search.get_json\n```\n\n(the full documentation)[https://serpapi.com/search-api].\n\nMore search API are documented on [SerpApi.com](http://serpapi.com).\n\nYou will find more hands on examples below.\n\n### Example by specification\nWe love true open source, continuous integration and Test Drive Development (TDD).\n We are using RSpec to test [our infrastructure around the clock](https://travis-ci.org/serpapi/google-search-results-ruby) to achieve the best QoS (Quality Of Service).\n\nThe directory test/ includes specification/examples.\n\nSet your api key.\n\n```bash\nexport API_KEY=\"your secret key\"\n```\n\nInstall RSpec\n\n```bash\ngem install rspec\n```\n\nTo run the test:\n\n```bash\nrspec test\n```\n\nor if you prefers Rake\n\n```bash\nrake test\n```\n\n### Location API\n\n```ruby\nlocation_list = GoogleSearch.new(q: \"Austin\", limit: 3).get_location\npp location_list\n```\n\nit prints the first 3 location matching Austin (Texas, Texas, Rochester)\n\n```ruby\n[\n  {\n    id: \"585069bdee19ad271e9bc072\",\n    google_id: 200635,\n    google_parent_id: 21176,\n    name: \"Austin, TX\",\n    canonical_name: \"Austin,TX,Texas,United States\",\n    country_code: \"US\",\n    target_type: \"DMA Region\",\n    reach: 5560000,\n    gps: [-97.7430608, 30.267153],\n    keys: [\"austin\", \"tx\", \"texas\", \"united\", \"states\"]\n  },\n  #...\n]\n```\n\n### Search Archive API\nThis API allows to retrieve previous search.\nTo do so run a search to save a `search_id`.\n\n```ruby\nsearch = GoogleSearch.new(q: \"Coffee\", location: \"Portland\")\noriginal_search = search.get_hash\nsearch_id = original_search[:search_metadata][:id]\n```\n\nNow let retrieve the previous search from the archive.\n\n```ruby\nsearch = GoogleSearch.new\narchive_search = search.get_search_archive(search_id)\npp archive_search\n```\n\nit prints the search from the archive.\n\n### Account API\n\n```ruby\nsearch = GoogleSearch.new\npp search.get_account\n```\nit prints your account information.\n\n### Search Google Images\n\n```ruby\nsearch = GoogleSearch.new(q: 'cofffe', tbm: \"isch\")\nimage_results_list = search.get_hash[:images_results]\nimage_results_list.each do |image_result|\n  puts image_result[:original]\nend\n```\n\nTo download the image: `wget #{image_result[:original]}`\n\nthis code prints all the images links,\n and download image if you un-comment the line with wget (linux/osx tool to download image).\n\n### Search Google News\n\n```ruby\nsearch = GoogleSearch.new({\n  q: 'cofffe', # search search\n  tbm: \"nws\", # news\n  tbs: \"qdr:d\", # last 24h\n  num: 10\n})\n\n3.times do |offset|\n  search.params[:start] = offset * 10\n  news_results_list = search.get_hash[:news_results]\n  news_results_list.each do |news_result|\n    puts \"#{news_result[:position] + offset * 10} - #{news_result[:title]}\"\n  end\nend\n```\n\nthis script prints the first 3 pages of the news title for the last 24h.\n\n### Search Google Shopping\n\n```ruby\nsearch = GoogleSearch.new({\n  q: 'cofffe', # search search\n  tbm: \"shop\", # shopping\n  tbs: \"tbs=p_ord:rv\" # by best review\n})\nshopping_results_list = search.get_hash[:shopping_results]\nshopping_results_list.each do |shopping_result|\n  puts \"#{shopping_result[:position]} - #{shopping_result[:title]}\"\nend\n```\n\nThis script prints all the shopping results order by review order with position.\n\n### Google Search By Location\n\nWith SerpApi.com, we can build Google search from anywhere in the world.\nThis code is looking for the best coffee shop per city.\n\n```ruby\n[\"new york\", \"paris\", \"berlin\"].each do |city|\n    # get location from the city name\n    location = GoogleSearch.new({q: city, limit: 1}).get_location.first[:canonical_name]\n\n    # get top result\n    search = GoogleSearch.new({\n      q: 'best coffee shop',\n      location: location,\n      num: 1,  # number of result\n      start: 0 # offset\n    })\n    top_result = search.get_hash[:organic_results].first\n\n    puts \"top coffee result for #{location} is: #{top_result[:title]}\"\n  end\n```\n\n### Batch Asynchronous search\n\nWe do offer two ways to boost your searches thanks to `async` parameter.\n - Non-blocking - async=true  (recommended)\n - Blocking - async=false - it's more compute intensive because the search would need to hold many connections.\n\n```ruby\ncompany_list = %w(microsoft apple nvidia)\n\nputs \"submit batch of asynchronous searches\"\nsearch = GoogleSearch.new({async: true})\n\nsearch_queue = Queue.new\ncompany_list.each do |company|\n  # set search\n  search.params[:q] = company\n\n  # store request into a search_queue - no-blocker\n  result = search.get_hash()\n  if result[:search_metadata][:status] =~ /Cached|Success/\n    puts \"#{company}: search done\"\n    next\n  end\n\n  # add result to the search queue\n  search_queue.push(result)\nend\n\nputs \"wait until all searches are cached or success\"\nsearch = GoogleSearch.new\nwhile !search_queue.empty?\n  result = search_queue.pop\n  # extract search id\n  search_id = result[:search_metadata][:id]\n\n  # retrieve search from the archive - blocker\n  search_archived = search.get_search_archive(search_id)\n  if search_archived[:search_metadata][:status] =~ /Cached|Success/\n    puts \"#{search_archived[:search_parameters][:q]}: search done\"\n    next\n  end\n\n  # add result to the search queue\n  search_queue.push(result)\nend\n\nsearch_queue.close\nputs 'all searches completed'\n  ```\nThis code shows a simple implementation to run a batch of asynchronously searches.\n\n\n## Supported search engine\n### Google search API\n\n```ruby\nGoogleSearch.api_key = \"\"\nsearch = GoogleSearch.new(q: \"Coffee\", location: \"Portland\")\npp search.get_hash\n```\n\nhttps://serpapi.com/search-api\n\n### Bing search API\n\n```ruby\nBingSearch.api_key = \"\"\nsearch = BingSearch.new(q: \"Coffee\", location: \"Portland\")\npp search.get_hash\n```\n\nhttps://serpapi.com/bing-search-api\n\n### Baidu search API\n\n```ruby\nBaiduSearch.api_key = \"\"\nsearch = BaiduSearch.new(q: \"Coffee\")\npp search.get_hash\n```\n\nhttps://serpapi.com/baidu-search-api\n\n### Yahoo search API\n\n```ruby\nYahooSearch.api_key = \"\"\nsearch = YahooSearch.new(p: \"Coffee\")\npp search.get_hash\n```\n\nhttps://serpapi.com/yahoo-search-api\n\n### Yandex search API\n\n```ruby\nYandexSearch.api_key = \"\"\nsearch = YandexSearch.new(text: \"Coffee\")\npp search.get_hash\n```\n\nhttps://serpapi.com/yandex-search-api\n\n### Ebay search API\n\n```ruby\nEbaySearch.api_key = \"\"\nsearch = EbaySearch.new(_nkw: \"Coffee\")\npp search.get_hash\n```\n\nhttps://serpapi.com/ebay-search-api\n\n### Youtube search API\n\n```ruby\nYoutubeySearch.api_key = \"\"\nsearch = YoutubeSearch.new(search_query: \"Coffee\")\npp search.get_hash\n```\n\nhttps://serpapi.com/youtube-search-api\n\n### Homedepot search API\n\n```ruby\nHomedepotSearch.api_key = \"\"\nsearch = HomedepotSearch.new(q: \"Coffee\")\npp search.get_hash\n```\n\nhttps://serpapi.com/home-depot-search-api\n\n### Walmart search API\n\n```ruby\nWalmartSearch.api_key = \"\"\nsearch = WalmartSearch.new(query: \"Coffee\")\npp search.get_hash\n```\n\nhttps://serpapi.com/walmart-search-api\n\n### Duckduckgo search API\n\n```ruby\nDuckduckgoSearch.api_key = \"\"\nsearch = DuckduckgoSearch.new(query: \"Coffee\")\npp search.get_hash\n```\n\nhttps://serpapi.com/duckduckgo-search-api\n\n### Naver search API\n\n```ruby\nsearch = NaverSearch.new(query: \"Coffee\", api_key: \"secretApiKey\")\npp search.get_hash\n```\n\nhttps://serpapi.com/duckduckgo-search-api\n\n### Apple store search API\n\n```ruby\nsearch = AppleStoreSearch.new(term: \"Coffee\", , api_key: \"secretApiKey\")\npp search.get_hash\n```\n\nhttps://serpapi.com/duckduckgo-search-api\n\n### Generic SerpApi search\n\n```ruby\nSerpApiSearch.api_key = ENV['API_KEY']\nquery = {\n  p: \"Coffee\",\n  engine: \"youtube\"\n}\nsearch = SerpApiSearch.new(query)\nhash = search.get_hash\npp hash[:organic_results]\n```\n\nsee: google-search-results-ruby/test/search_api_spec.rb\n\n\n### Error management\n\nThis library follows the regular raise an exception when something goes wrong provided by Ruby.\n Any networking related exception will be returned as is. \n  Anything related to the client layer will be returned as a SerpApiException.\n   A SerpApiException might be caused by a bug in the library.\n   A networking problem will be caused by either SerpApi.com or your internet.\n\n# Change log\n * 2.2 \n   - add apple store search engine\n   - add naver search engine\n * 2.1 - Add more search engine: Youtube, Duckduckgo, Homedepot, Walmart\n      - improve error management and documentation.\n * 2.0 - API simplified( GoogleSearchResults -\u003e GoogleSearch), fix gem issue with 2.6+ Ruby, Out Of Box step to verify the package before delivery.\n * 1.3.2 - rename variable client to search for naming consistency\n * 1.3 - support for all major search engine\n * 1.2 - stable versino to support goole and few more search engine\n * 1.1 - client connection improvement to allow multi threading and fiber support\n * 1.0 - first stable version with Google engine search with Google image\n\n# Roadmap\n * 2.1 Improve exception / HTTP status handling\n\n# Conclusion\nSerpApi supports all the major search engines. Google has the more advance support with all the major services available: Images, News, Shopping and more..\nTo enable a type of search, the field tbm (to be matched) must be set to:\n\n * isch: Google Images API.\n * nws: Google News API.\n * shop: Google Shopping API.\n * any other Google service should work out of the box.\n * (no tbm parameter): regular Google search.\n\nThe field `tbs` allows to customize the search even more.\n\n[The full documentation is available here.](https://serpapi.com/search-api)\n\n# Contributing\n\nContributions are welcome, feel to submit a pull request!\n\nTo run the tests:\n\n```bash\nexport API_KEY=\"your api key\"\nrake test\n```\n","funding_links":[],"categories":["Ruby"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserpapi%2Fgoogle-search-results-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserpapi%2Fgoogle-search-results-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserpapi%2Fgoogle-search-results-ruby/lists"}