1  ---
  2  title: Websearch
  3  id: websearch-api
  4  description: Web search engine for Haystack.
  5  slug: "/websearch-api"
  6  ---
  7  
  8  <a id="serper_dev"></a>
  9  
 10  # Module serper\_dev
 11  
 12  <a id="serper_dev.SerperDevWebSearch"></a>
 13  
 14  ## SerperDevWebSearch
 15  
 16  Uses [Serper](https://serper.dev/) to search the web for relevant documents.
 17  
 18  See the [Serper Dev website](https://serper.dev/) for more details.
 19  
 20  Usage example:
 21  ```python
 22  from haystack.components.websearch import SerperDevWebSearch
 23  from haystack.utils import Secret
 24  
 25  websearch = SerperDevWebSearch(top_k=10, api_key=Secret.from_token("test-api-key"))
 26  results = websearch.run(query="Who is the boyfriend of Olivia Wilde?")
 27  
 28  assert results["documents"]
 29  assert results["links"]
 30  
 31  # Example with domain filtering - exclude subdomains
 32  websearch_filtered = SerperDevWebSearch(
 33      top_k=10,
 34      allowed_domains=["example.com"],
 35      exclude_subdomains=True,  # Only results from example.com, not blog.example.com
 36      api_key=Secret.from_token("test-api-key")
 37  )
 38  results_filtered = websearch_filtered.run(query="search query")
 39  ```
 40  
 41  <a id="serper_dev.SerperDevWebSearch.__init__"></a>
 42  
 43  #### SerperDevWebSearch.\_\_init\_\_
 44  
 45  ```python
 46  def __init__(api_key: Secret = Secret.from_env_var("SERPERDEV_API_KEY"),
 47               top_k: Optional[int] = 10,
 48               allowed_domains: Optional[list[str]] = None,
 49               search_params: Optional[dict[str, Any]] = None,
 50               *,
 51               exclude_subdomains: bool = False)
 52  ```
 53  
 54  Initialize the SerperDevWebSearch component.
 55  
 56  **Arguments**:
 57  
 58  - `api_key`: API key for the Serper API.
 59  - `top_k`: Number of documents to return.
 60  - `allowed_domains`: List of domains to limit the search to.
 61  - `exclude_subdomains`: Whether to exclude subdomains when filtering by allowed_domains.
 62  If True, only results from the exact domains in allowed_domains will be returned.
 63  If False, results from subdomains will also be included. Defaults to False.
 64  - `search_params`: Additional parameters passed to the Serper API.
 65  For example, you can set 'num' to 20 to increase the number of search results.
 66  See the [Serper website](https://serper.dev/) for more details.
 67  
 68  <a id="serper_dev.SerperDevWebSearch.to_dict"></a>
 69  
 70  #### SerperDevWebSearch.to\_dict
 71  
 72  ```python
 73  def to_dict() -> dict[str, Any]
 74  ```
 75  
 76  Serializes the component to a dictionary.
 77  
 78  **Returns**:
 79  
 80  Dictionary with serialized data.
 81  
 82  <a id="serper_dev.SerperDevWebSearch.from_dict"></a>
 83  
 84  #### SerperDevWebSearch.from\_dict
 85  
 86  ```python
 87  @classmethod
 88  def from_dict(cls, data: dict[str, Any]) -> "SerperDevWebSearch"
 89  ```
 90  
 91  Serializes the component to a dictionary.
 92  
 93  **Returns**:
 94  
 95  Dictionary with serialized data.
 96  
 97  <a id="serper_dev.SerperDevWebSearch.run"></a>
 98  
 99  #### SerperDevWebSearch.run
100  
101  ```python
102  @component.output_types(documents=list[Document], links=list[str])
103  def run(query: str) -> dict[str, Union[list[Document], list[str]]]
104  ```
105  
106  Use [Serper](https://serper.dev/) to search the web.
107  
108  **Arguments**:
109  
110  - `query`: Search query.
111  
112  **Raises**:
113  
114  - `SerperDevError`: If an error occurs while querying the SerperDev API.
115  - `TimeoutError`: If the request to the SerperDev API times out.
116  
117  **Returns**:
118  
119  A dictionary with the following keys:
120  - "documents": List of documents returned by the search engine.
121  - "links": List of links returned by the search engine.
122  
123  <a id="searchapi"></a>
124  
125  # Module searchapi
126  
127  <a id="searchapi.SearchApiWebSearch"></a>
128  
129  ## SearchApiWebSearch
130  
131  Uses [SearchApi](https://www.searchapi.io/) to search the web for relevant documents.
132  
133  Usage example:
134  ```python
135  from haystack.components.websearch import SearchApiWebSearch
136  from haystack.utils import Secret
137  
138  websearch = SearchApiWebSearch(top_k=10, api_key=Secret.from_token("test-api-key"))
139  results = websearch.run(query="Who is the boyfriend of Olivia Wilde?")
140  
141  assert results["documents"]
142  assert results["links"]
143  ```
144  
145  <a id="searchapi.SearchApiWebSearch.__init__"></a>
146  
147  #### SearchApiWebSearch.\_\_init\_\_
148  
149  ```python
150  def __init__(api_key: Secret = Secret.from_env_var("SEARCHAPI_API_KEY"),
151               top_k: Optional[int] = 10,
152               allowed_domains: Optional[list[str]] = None,
153               search_params: Optional[dict[str, Any]] = None)
154  ```
155  
156  Initialize the SearchApiWebSearch component.
157  
158  **Arguments**:
159  
160  - `api_key`: API key for the SearchApi API
161  - `top_k`: Number of documents to return.
162  - `allowed_domains`: List of domains to limit the search to.
163  - `search_params`: Additional parameters passed to the SearchApi API.
164  For example, you can set 'num' to 100 to increase the number of search results.
165  See the [SearchApi website](https://www.searchapi.io/) for more details.
166  
167  The default search engine is Google, however, users can change it by setting the `engine`
168  parameter in the `search_params`.
169  
170  <a id="searchapi.SearchApiWebSearch.to_dict"></a>
171  
172  #### SearchApiWebSearch.to\_dict
173  
174  ```python
175  def to_dict() -> dict[str, Any]
176  ```
177  
178  Serializes the component to a dictionary.
179  
180  **Returns**:
181  
182  Dictionary with serialized data.
183  
184  <a id="searchapi.SearchApiWebSearch.from_dict"></a>
185  
186  #### SearchApiWebSearch.from\_dict
187  
188  ```python
189  @classmethod
190  def from_dict(cls, data: dict[str, Any]) -> "SearchApiWebSearch"
191  ```
192  
193  Deserializes the component from a dictionary.
194  
195  **Arguments**:
196  
197  - `data`: The dictionary to deserialize from.
198  
199  **Returns**:
200  
201  The deserialized component.
202  
203  <a id="searchapi.SearchApiWebSearch.run"></a>
204  
205  #### SearchApiWebSearch.run
206  
207  ```python
208  @component.output_types(documents=list[Document], links=list[str])
209  def run(query: str) -> dict[str, Union[list[Document], list[str]]]
210  ```
211  
212  Uses [SearchApi](https://www.searchapi.io/) to search the web.
213  
214  **Arguments**:
215  
216  - `query`: Search query.
217  
218  **Raises**:
219  
220  - `TimeoutError`: If the request to the SearchApi API times out.
221  - `SearchApiError`: If an error occurs while querying the SearchApi API.
222  
223  **Returns**:
224  
225  A dictionary with the following keys:
226  - "documents": List of documents returned by the search engine.
227  - "links": List of links returned by the search engine.