fetchserp 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3cd4f221a3c82a7cbbe3f8f30f2ad30d34033d98090ddaabe716dd6710b7e93c
-  data.tar.gz: 334c72468085154f231e4cc5de15002fc208e4aeeabcc04a67d4c79a40e7a21f
+  metadata.gz: aee8e95fe03152c7170f302c9dc12708b6dd34be523518d19d68d06806faf1f0
+  data.tar.gz: 9e5bf93d85115a71444f7d012d91e202565e050ba22126e008ddbca3cf17f8ea
 SHA512:
-  metadata.gz: d7e76b461290d590368bf47e5892cf161d8255011259a6bbffa488c8c4959700146ac99597d9f1bd15a9529741f2270543996c117440319ed94b8162b32460f7
-  data.tar.gz: 69c53b9825c3d84eccdb6770eab3552e335882ad9ea59b40e5b69cec10a5372d6b9699227bb52f0aa51eb0170d33249a3dc30028e315f99b5cb26dc2777bdcd6
+  metadata.gz: 7b5f79d83dab6a5ac4a608aa47c90b8571a1cc9d898faa41f02f062ead8efd6cd93aef3d91a48d529d131fab0beafe987be01004d204fb1c08f57b42219db75c
+  data.tar.gz: e36ebed82d26a5e684a7010ed5b1ddab57c9081c030466e9e60fadbfc5da040e6d8e4862d1e8b3b62ddbb92d52d34d6f5e5bbf99c33bc65bef7a115f28b729f2

data/README.md

@@ -7,7 +7,7 @@ A lightweight, hand-crafted Ruby SDK for the FetchSERP REST API.
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "fetchserp", git: "https://github.com/fetchserp/fetchserp-ruby.git"
+gem "fetchserp", "~> 0.1"
 ```
 
 Then bundle install:
@@ -16,6 +16,22 @@ Then bundle install:
 bundle install
 ```
 
+## Authentication
+
+An API key is required for **all** requests. You can create a free account and grab your key at <https://fetchserp.com/> — every new account starts with **250 free credits** so you can test the endpoints immediately.
+
+Set it in your environment (recommended):
+
+```bash
+export FETCHSERP_API_KEY="your-secret-token"
+```
+
+or pass it directly when instantiating the client:
+
+```ruby
+client = FetchSERP.new(api_key: "your-secret-token")
+```
+
 ## Quick Start
 
 ```ruby
@@ -30,6 +46,10 @@ puts response.data
 # Fetch Google SERP results
 serp = client.serp(query: "best ruby gems", country: "us")
 puts serp.data["results"]
+
+# Get ranking positions for a domain/keyword
+ranking = client.ranking(keyword: "serp api", domain: "fetchserp.com", pages_number: 5)
+puts ranking.data["results"]
 ```
 
 The client will raise `FetchSERP::Error` on any HTTP error (network, 4xx, 5xx) so you can handle failures gracefully.
@@ -43,12 +63,14 @@ The client will raise `FetchSERP::Error` on any HTTP error (network, 4xx, 5xx) s
 * `/api/v1/keywords_suggestions`
 * `/api/v1/long_tail_keywords_generator`
 * `/api/v1/page_indexation`
+* `/api/v1/playwright_mcp`
 * `/api/v1/ranking`
 * `/api/v1/scrape`
 * `/api/v1/scrape_domain`
 * `/api/v1/scrape_js`
 * `/api/v1/scrape_js_with_proxy`
 * `/api/v1/serp`
+* `/api/v1/serp_ai_mode`
 * `/api/v1/serp_html`
 * `/api/v1/serp_js` & `/api/v1/serp_js/{uuid}`
 * `/api/v1/serp_text`
@@ -70,12 +92,14 @@ Below is the full list of convenience helpers exposed by `FetchSERP::Client`. Al
 | `keywords_suggestions(url: nil, keywords: nil, **opts)` | `GET /api/v1/keywords_suggestions` | one of `url` or `keywords` |
 | `long_tail_keywords_generator(keyword:, **opts)` | `GET /api/v1/long_tail_keywords_generator` | `keyword` |
 | `page_indexation(domain:, keyword:)` | `GET /api/v1/page_indexation` | `domain`, `keyword` |
+| `playwright_mcp(prompt:, **opts)` | `GET /api/v1/playwright_mcp` | `prompt` |
 | `ranking(keyword:, domain:, **opts)` | `GET /api/v1/ranking` | `keyword`, `domain` |
 | `scrape(url:)` | `GET /api/v1/scrape` | `url` |
 | `scrape_domain(domain:, **opts)` | `GET /api/v1/scrape_domain` | `domain` |
 | `scrape_js(url:, js_script: nil)` | `POST /api/v1/scrape_js` | `url` |
 | `scrape_js_with_proxy(url:, country:, js_script: nil)` | `POST /api/v1/scrape_js_with_proxy` | `url`, `country` |
 | `serp(query:, **opts)` | `GET /api/v1/serp` | `query` |
+| `serp_ai_mode(query:, **opts)` | `GET /api/v1/serp_ai_mode` | `query` |
 | `serp_html(query:, **opts)` | `GET /api/v1/serp_html` | `query` |
 | `serp_js(query:, **opts)` | `GET /api/v1/serp_js` | `query` |
 | `serp_js_content(uuid:)` | `GET /api/v1/serp_js/{uuid}` | `uuid` |
@@ -93,6 +117,25 @@ resp = client.keywords_suggestions(keywords: ["ruby sdk", "seo api"], country: "
 puts resp.data["keywords_suggestions"]
 ```
 
+### Example — Get SERP AI Overview and AI Mode
+
+```ruby
+client = FetchSERP.new(api_key: ENV["FETCHSERP_API_KEY"])
+
+# Get AI overview and AI mode response for a search query
+resp = client.serp_ai_mode(query: "ruby programming best practices")
+```
+
+### Example — Remote control browser with Playwright MCP
+
+```ruby
+client = FetchSERP.new(api_key: ENV["FETCHSERP_API_KEY"])
+
+# Use GPT-4.1 to remote control a browser via Playwright MCP
+resp = client.playwright_mcp(prompt: "Navigate to google.com and search for 'ruby gems'")
+puts resp.data["response"]
+```
+
 ### Handling errors
 
 Any 4xx/5xx response raises `FetchSERP::Error` which includes `status` and raw `body` so you can debug:

data/lib/fetchserp/client.rb

@@ -51,6 +51,11 @@ module FetchSERP
       get("/api/v1/page_indexation", params)
     end
 
+    # Playwright MCP - uses GPT-4.1 to remote control a browser via a Playwright MCP server
+    def playwright_mcp(**params)
+      get("/api/v1/playwright_mcp", params)
+    end
+
     def ranking(**params)
       get("/api/v1/ranking", params)
     end
@@ -79,6 +84,12 @@ module FetchSERP
       get("/api/v1/serp_html", params)
     end
 
+    # SERP AI Overview and AI Mode - returns AI overview and AI mode response for the query
+    # Less reliable than the 2-step process but returns results in under 30 seconds
+    def serp_ai_mode(**params)
+      get("/api/v1/serp_ai_mode", params)
+    end
+
     # Step 1: returns uuid
     def serp_js(**params)
       get("/api/v1/serp_js", params)

data/lib/fetchserp/version.rb

@@ -1,3 +1,3 @@
 module FetchSERP
-  VERSION = "0.1.1"
+  VERSION = "0.1.3"
 end 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: fetchserp
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.3
 platform: ruby
 authors:
 - FetchSERP
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-06-19 00:00:00.000000000 Z
+date: 2025-07-14 00:00:00.000000000 Z
 dependencies: []
 description: A lightweight Ruby client for interacting with the FetchSERP API. Provides
   helpers for authentication and convenient Ruby methods for each endpoint.