Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 4 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ Query a vast range of data at scale, including web search results, flight schedu

## Installation

Ruby 2.7 and later are supported. To achieve an optimal performance, the latest version is recommended. Check 2.7.8 vs 3.4.4 [performance comparison](#Performance-Comparison).
Ruby 2.7 and higher are supported. To achieve an optimal performance, the latest version is recommended. Check 2.7.8 vs 3.4.4 [performance comparison](#Performance-Comparison).

Other versions, such as Ruby 1.9, Ruby 2.x, and JRuby, are compatible with [legacy SerpApi library](https://github.com/serpapi/google-search-results-ruby), which is still supported. To upgrade to the latest library, check our [migration guide](#Migration-quick-guide).

Expand Down Expand Up @@ -1093,11 +1093,9 @@ Most notable improvements:
- Reduce logic complexity in our implementation. (faster performance)
- Better documentation.

## Supported Ruby version.
Ruby versions validated by Github Actions:
- 3.1
- 3.4
* doc: [Github Actions.](https://github.com/serpapi/serpapi-ruby/actions/workflows/ci.yml)
## Supported Ruby versions

Ruby 2.7 and higher is supported.

## Developer Guide
### Key goals
Expand Down
52 changes: 25 additions & 27 deletions README.md.erb
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<%-
def snippet(format, path, demo = false)
def snippet(format, path, demo = false)
lines = File.new(path).readlines
if demo
# skip comment
Expand All @@ -20,13 +20,13 @@ end
-%>
# SerpApi Ruby Library

[![serpapi-ruby](https://github.com/serpapi/serpapi-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/serpapi/serpapi-ruby/actions/workflows/ci.yml) [![Gem Version](https://badge.fury.io/rb/serpapi.svg)](https://badge.fury.io/rb/serpapi)
[![serpapi-ruby](https://github.com/serpapi/serpapi-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/serpapi/serpapi-ruby/actions/workflows/ci.yml) [![Gem Version](https://badge.fury.io/rb/serpapi.svg)](https://badge.fury.io/rb/serpapi)

Integrate search data into your AI workflow, RAG / fine-tuning, or Ruby application using this official wrapper for [SerpApi](https://serpapi.com).
Integrate search data into your AI workflow, RAG / fine-tuning, or Ruby application using this official wrapper for [SerpApi](https://serpapi.com).

SerpApi supports Google, Google Maps, Google Shopping, Baidu, Yandex, Yahoo, eBay, App Stores, and [more](https://serpapi.com).
SerpApi supports Google, Google Maps, Google Shopping, Baidu, Yandex, Yahoo, eBay, App Stores, and [more](https://serpapi.com).

Query a vast range of data at scale, including web search results, flight schedules, stock market data, news headlines, and [more](https://serpapi.com).
Query a vast range of data at scale, including web search results, flight schedules, stock market data, news headlines, and [more](https://serpapi.com).

## Features
* `persistent` → Keep socket connection open to save on SSL handshake / reconnection (2x faster). [Search at scale](#Search-At-Scale)
Expand All @@ -36,7 +36,7 @@ Query a vast range of data at scale, including web search results, flight schedu

## Installation

Ruby 2.7 and later are supported. To achieve an optimal performance, the latest version is recommended. Check 2.7.8 vs 3.4.4 [performance comparison](#Performance-Comparison).
Ruby 2.7 and higher are supported. To achieve an optimal performance, the latest version is recommended. Check 2.7.8 vs 3.4.4 [performance comparison](#Performance-Comparison).

Other versions, such as Ruby 1.9, Ruby 2.x, and JRuby, are compatible with [legacy SerpApi library](https://github.com/serpapi/google-search-results-ruby), which is still supported. To upgrade to the latest library, check our [migration guide](#Migration-quick-guide).

Expand All @@ -45,7 +45,7 @@ Other versions, such as Ruby 1.9, Ruby 2.x, and JRuby, are compatible with [lega
gem 'serpapi', '~> 1.0', '>= 1.0.3'
```

### Gem
### Gem
```bash
$ gem install serpapi
```
Expand Down Expand Up @@ -139,7 +139,7 @@ Search API enables `async` search.
- Non-blocking (`async=true`) : the development is more complex, but this allows handling many simultaneous connections.
- Blocking (`async=false`) : it is easy to write the code but more compute-intensive when the parent process needs to hold many connections.

Here is an example of asynchronous searches using Ruby
Here is an example of asynchronous searches using Ruby
```ruby
require 'serpapi'

Expand Down Expand Up @@ -204,9 +204,9 @@ end
responses = threads.map(&:value)
```

The code aims to demonstrate how thread pools can be used to
improve performance by executing multiple tasks concurrently. In
this case, it makes multiple HTTP requests to an API endpoint using
The code aims to demonstrate how thread pools can be used to
improve performance by executing multiple tasks concurrently. In
this case, it makes multiple HTTP requests to an API endpoint using
a thread pool of persistent connections.

Note: `gem install connection_pool` to run this example.
Expand All @@ -228,7 +228,7 @@ benchmark: (demo/demo_thread_pool.rb)
| 3.4.8 | 0.018644 | 4 | 0.004661 |
| 4.0.0 | 0.017302 | 4 | 0.004326 |

Ruby 4.0.0 shows a slight improvement over Ruby 3.4.8, but the difference is not significant using thread.
Ruby 4.0.0 shows a slight improvement over Ruby 3.4.8, but the difference is not significant using thread.
Ractor could be considered for a more efficient use of resources but it's still in the experimental stage.

Note: in this benchmark, `thread == HTTP connections`.
Expand Down Expand Up @@ -508,25 +508,25 @@ see: [https://serpapi.com/yelp-search-api](https://serpapi.com/yelp-search-api)
4. **SerpApi Optimization**: Shows consistent ~2.2x improvement with persistent connections regardless of Ruby version
5. **Ruby 4.0.0 Performance**: Shows mixed results with some regressions compared to 3.4.4, particularly for HTTP.rb persistent connections. Ruby 4.0.0 was just released for Christmas 2025, and HTTP.rb has not been optimized for it yet.

The older library (google-search-results-ruby) was performing at 55 req/s on Ruby 2.7.8, which is 2x slower than the current version (serpapi-ruby) on Ruby 3.4.4 or 4.0.0.
The older library (google-search-results-ruby) was performing at 55 req/s on Ruby 2.7.8, which is 2x slower than the current version (serpapi-ruby) on Ruby 3.4.4 or 4.0.0.

**Context** This benchmark was performed on warmup search results using a MacBook Pro 2025 connected via Wi-Fi 6.0 home network on AT&T fiber from Austin, TX (no network optimization).
**Context** This benchmark was performed on warmup search results using a MacBook Pro 2025 connected via Wi-Fi 6.0 home network on AT&T fiber from Austin, TX (no network optimization).

## Migration quick guide

If you were already using [google-search-results-ruby gem](https://github.com/serpapi/google-search-results-ruby), here are the changes.

```
# load library
# old way
# old way
require 'google_search_results'
# new way
require 'serpapi'

# define a search
# old way to describe the search
search = GoogleSearch.new(search_params)
# new way
# new way
default_parameter = {api_key: "secret_key", engine: "google"}
client = SerpApi::Client.new(default_parameter)
# an instance of the serpapi client is created
Expand All @@ -553,7 +553,7 @@ raw_html = client.html(params)
hash_results = search.get_hash
# new way
results = client.search(params)
# where params is the search parameters (override the default search parameters in the constructor).
# where params is the search parameters (override the default search parameters in the constructor).

# search as raw JSON format
# old way
Expand All @@ -574,11 +574,9 @@ Most notable improvements:
- Reduce logic complexity in our implementation. (faster performance)
- Better documentation.

## Supported Ruby version.
Ruby versions validated by Github Actions:
- 3.1
- 3.4
* doc: [Github Actions.](https://github.com/serpapi/serpapi-ruby/actions/workflows/ci.yml)
## Supported Ruby versions

Ruby 2.7 and higher is supported.

## Change logs
* [2025-11-17] 1.0.2 Implement `inspect` functions for client
Expand All @@ -605,7 +603,7 @@ This project source code and coding style was inspired by the most awesome Ruby
- [Cloudfare](https://rubygems.org/gems/cloudflare/versions/2.1.0)
- [rest-client](https://rubygems.org/gems/rest-client)
- [stripe](https://rubygems.org/gems/stripe)

### Code quality expectations
- 0 lint offense: `rake lint`
- 100% tests passing: `rake test`
Expand All @@ -616,7 +614,7 @@ This project source code and coding style was inspired by the most awesome Ruby
### Class diagram
```mermaid
classDiagram
Application *-- serpapi
Application *-- serpapi
serpapi *-- Client
class Client {
engine String
Expand All @@ -636,7 +634,7 @@ classDiagram
### search() : Sequence diagram
```mermaid
sequenceDiagram
Client->>SerpApi.com: search() : http request
Client->>SerpApi.com: search() : http request
SerpApi.com-->>SerpApi.com: query search engine
SerpApi.com-->>SerpApi.com: parse HTML into JSON
SerpApi.com-->>Client: JSON string payload
Expand All @@ -659,12 +657,12 @@ The class SerpApi::Client (client side / ruby):
Et voila!

## Continuous integration
We love [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) (CI) and [Test-Driven Development](https://en.wikipedia.org/wiki/Test-driven_development) (TDD) at SerpApi.
We love [continuous integration](https://en.wikipedia.org/wiki/Continuous_integration) (CI) and [Test-Driven Development](https://en.wikipedia.org/wiki/Test-driven_development) (TDD) at SerpApi.
We use RSpec and Github Actions to test our infrastructure around the clock, and that includes all changes to our clients.

The directory spec/ includes specification which serves the dual purposes of examples and functional tests.

Set your secret API key in your shell before running a test.
Set your secret API key in your shell before running a test.
The SerpApi key can be obtained from [serpapi.com/signup](https://serpapi.com/users/sign_up?plan=free).
```bash
export SERPAPI_KEY="your_secret_key"
Expand Down
16 changes: 5 additions & 11 deletions serpapi.gemspec
Original file line number Diff line number Diff line change
@@ -1,19 +1,14 @@

if RUBY_VERSION < '2.1.0'
load File.join(File.dirname(__FILE__), 'lib/serpapi/version')
else
require_relative 'lib/serpapi/version'
end
require_relative 'lib/serpapi/version'

Gem::Specification.new do |s|
s.name = 'serpapi'
s.version = SerpApi::VERSION
s.summary = 'Official Ruby library for SerpApi.com'
s.description = 'Integrate powerful search functionality into your Ruby application with SerpApi. SerpApi offers official
support for Google, Google Maps, Google Shopping, Baidu, Yandex, Yahoo, eBay, App Stores, and more.
Access a vast range of data, including web search results, local business listings, and product
s.description = 'Integrate powerful search functionality into your Ruby application with SerpApi. SerpApi offers official
support for Google, Google Maps, Google Shopping, Baidu, Yandex, Yahoo, eBay, App Stores, and more.
Access a vast range of data, including web search results, local business listings, and product
information.'
s.authors = ['victor benarbia', 'Julien Khaleghy']
s.authors = ['Victor Benarbia', 'Julien Khaleghy']
s.email = 'victor@serpapi.com'
s.files = Dir['{lib}/serpapi.rb'] + Dir['{lib}/serpapi/*.rb']
s.require_paths = ['lib']
Expand All @@ -30,5 +25,4 @@ information.'
s.add_development_dependency 'yard', '~>0.9.28'
s.add_development_dependency 'rubocop', '~>1.75.7'
s.add_development_dependency 'csv'

end
Loading