@@ -21,20 +21,32 @@ toc: true
2121- [ Installation] ( #installation )
2222- [ Usage] ( #usage )
2323 - [ ScavioWebSearch] ( #scaviowebsearch )
24+ - [ Parameters] ( #parameters )
25+ - [ Beyond web search] ( #beyond-web-search )
2426- [ License] ( #license )
2527
2628## Overview
2729
28- [ Scavio] ( https://scavio.dev ) is a unified search API built for AI agents. It provides real-time
29- search across Google, YouTube, Amazon, Walmart, Reddit, TikTok, and more through a single API,
30- returning structured results with content and source URLs.
30+ [ Scavio] ( https://scavio.dev ) is a unified search API built for AI agents. One key reaches
31+ real-time data across Google, Amazon, Walmart, Target, eBay, Home Depot, YouTube, Reddit, TikTok,
32+ TikTok Shop, Instagram, X, Threads, Kuaishou, LinkedIn, Indeed, Glassdoor, Zillow, Redfin,
33+ Booking.com, Airbnb, Tripadvisor, Yelp, the Apple App Store, Google Play, SEC EDGAR, Companies
34+ House, G2, Capterra, Google Ads Transparency and the Meta Ad Library, plus an extract endpoint
35+ that turns any URL into HTML, Markdown or plain text. Everything comes back as structured JSON,
36+ with no scraping or proxies to run.
3137
32- This integration provides:
33- - ` ScavioWebSearch ` : Searches the web using Scavio's Google web search endpoint and returns results
34- as Haystack ` Document ` objects along with source URLs.
38+ This integration is deliberately small. It ships ** one** component:
39+
40+ - ` ScavioWebSearch ` : searches the web using Scavio's Google web search endpoint and returns
41+ results as Haystack ` Document ` objects along with source URLs.
42+
43+ That makes it a drop-in peer of Haystack's other web-search components, so it slots into an
44+ existing pipeline without rewiring. The rest of Scavio's coverage is reachable from Haystack as
45+ well, but through the MCP server or the Python SDK rather than as one component per endpoint --
46+ see [ Beyond web search] ( #beyond-web-search ) .
3547
3648You need a Scavio API key to use this integration. You can get one at
37- [ dashboard.scavio.dev] ( https://dashboard.scavio.dev ) .
49+ [ dashboard.scavio.dev] ( https://dashboard.scavio.dev/sign-up ) .
3850
3951## Installation
4052
@@ -79,13 +91,68 @@ async def main():
7991asyncio.run(main())
8092```
8193
82- #### Parameters
94+ ### Parameters
95+
96+ The component takes three arguments:
8397
8498- ** ` api_key ` ** : API key for Scavio. Defaults to the ` SCAVIO_API_KEY ` environment variable.
8599- ** ` top_k ` ** : Maximum number of results to return. Defaults to 10.
86- - ** ` search_params ` ** : Additional parameters passed to the Scavio Google search endpoint. Supported
87- keys include ` country_code ` , ` language ` , ` page ` , ` search_type ` , ` device ` , ` nfpr ` , ` light_request ` .
100+ - ** ` search_params ` ** : Additional parameters forwarded to the Scavio Google search endpoint. Set
101+ them once on the constructor, or pass ` search_params ` to ` run ` / ` run_async ` to replace them for
102+ a single call.
103+
104+ #### ` search_params ` keys
105+
106+ | Key | Description |
107+ | --- | --- |
108+ | ` gl ` | Country of the search, ISO 3166-1 alpha-2 (e.g. ` us ` ). |
109+ | ` hl ` | UI language, ISO 639-1 (e.g. ` en ` ). |
110+ | ` start ` | Result ** offset** , not a page number: ` 0 ` is the first page, ` 10 ` the second, and so on up to ` 990 ` . |
111+ | ` google_domain ` | Regional Google domain (e.g. ` google.co.uk ` ). |
112+ | ` location ` | Canonical location name; encoded to a UULE string for you. |
113+ | ` uule ` | Pre-encoded UULE location string. Takes priority over ` location ` . |
114+ | ` device ` | ` desktop ` or ` mobile ` . |
115+ | ` lr ` | Language restrict (e.g. ` lang_en ` ). |
116+ | ` cr ` | Country restrict (e.g. ` countryUS ` ). |
117+ | ` safe ` | Set to ` active ` to enable SafeSearch. |
118+ | ` nfpr ` | ` True ` disables spelling correction and auto-fixes. |
119+ | ` filter ` | ` "0" ` disables the omitted / similar-results filter. |
120+ | ` time_period ` | One of ` last_hour ` , ` last_day ` , ` last_week ` , ` last_month ` , ` last_year ` . |
121+ | ` resolve_ai_overview ` | Resolve a deferred AI Overview. Enabled server-side by default. |
122+
123+ ``` python
124+ web_search = ScavioWebSearch(
125+ top_k = 5 ,
126+ search_params = {" gl" : " de" , " hl" : " de" , " time_period" : " last_week" },
127+ )
128+ ```
129+
130+ #### Legacy keys
131+
132+ Earlier versions of this page documented a different set of names. Three of them are still
133+ accepted and translated for you, so existing pipelines keep working:
134+
135+ | Legacy key | Translated to |
136+ | --- | --- |
137+ | ` country_code ` | ` gl ` |
138+ | ` language ` | ` hl ` |
139+ | ` page ` | ` start ` , as ` (page - 1) * 10 ` |
140+
141+ Two more, ` search_type ` and ` light_request ` , belonged to a retired version of the endpoint. They
142+ are accepted but ignored -- passing them has no effect on the request. Drop them.
143+
144+ ## Beyond web search
145+
146+ ` scavio-haystack ` wraps a single endpoint on purpose. To reach the rest of Scavio's coverage from
147+ a Haystack agent, use either:
148+
149+ - the ** MCP server** at [ mcp.scavio.dev] ( https://mcp.scavio.dev ) , which exposes the full endpoint
150+ set as tools to any MCP-capable agent; or
151+ - the ** Python SDK** (` pip install scavio ` ), called from a custom Haystack component or a
152+ ` @tool ` -decorated function.
153+
154+ The endpoint reference lives at [ scavio.dev/docs] ( https://scavio.dev/docs ) .
88155
89- ### License
156+ ## License
90157
91158` scavio-haystack ` is distributed under the terms of the [ Apache-2.0] ( https://spdx.org/licenses/Apache-2.0.html ) license.
0 commit comments