Skip to content

Commit bc06eee

Browse files
authored
Update Scavio integration: current Google search params, accurate scope (#564)
* scavio: document google v2 search params; drop retired v1 keys * scavio: license heading to h2 to match toc
1 parent 1fbacee commit bc06eee

1 file changed

Lines changed: 78 additions & 11 deletions

File tree

‎integrations/scavio.md‎

Lines changed: 78 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -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

3648
You 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():
7991
asyncio.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

Comments
 (0)