0
# Tavily Python
1
2
A comprehensive Python wrapper for the Tavily API that enables intelligent web search, content extraction, web crawling, and website mapping capabilities. Designed for seamless integration into AI applications, RAG systems, and research tools with built-in error handling and support for both synchronous and asynchronous operations.
3
4
## Package Information
5
6
- **Package Name**: tavily-python
7
- **Language**: Python
8
- **Installation**: `pip install tavily-python`
9
- **Requirements**: Python ≥3.6
10
11
## Core Imports
12
13
```python
14
from tavily import TavilyClient, AsyncTavilyClient
15
```
16
17
**Note**: The legacy `Client` class is also available but deprecated. Use `TavilyClient` instead:
18
19
```python
20
from tavily import Client # Deprecated - use TavilyClient instead
21
```
22
23
For error handling:
24
25
```python
26
from tavily import (
27
TavilyClient,
28
InvalidAPIKeyError,
29
UsageLimitExceededError,
30
MissingAPIKeyError,
31
BadRequestError
32
)
33
```
34
35
Additional error types are available directly from the errors module (used internally by the client):
36
37
```python
38
from tavily.errors import ForbiddenError, TimeoutError
39
```
40
41
**Note**: `ForbiddenError` and `TimeoutError` are internal exception classes used by the client but not exported in the main package. They can be imported directly from the errors module if needed for advanced error handling.
42
43
For hybrid RAG functionality:
44
45
```python
46
from tavily import TavilyHybridClient
47
```
48
49
## Basic Usage
50
51
```python
52
from tavily import TavilyClient
53
54
# Initialize client with API key
55
client = TavilyClient(api_key="tvly-YOUR_API_KEY")
56
57
# Perform a basic search
58
response = client.search("What is machine learning?")
59
print(response)
60
61
# Get search context for RAG applications
62
context = client.get_search_context(
63
query="Latest developments in AI",
64
max_tokens=4000
65
)
66
67
# Extract content from URLs
68
content = client.extract(["https://example.com/article"])
69
70
# Crawl a website
71
crawl_results = client.crawl(
72
"https://docs.python.org",
73
max_depth=2,
74
limit=10
75
)
76
```
77
78
## Architecture
79
80
The Tavily Python wrapper is built around several key components:
81
82
- **Client Classes**: Synchronous (`TavilyClient`) and asynchronous (`AsyncTavilyClient`) API clients
83
- **Hybrid RAG**: Integration with vector databases for combined local and web search
84
- **Error Handling**: Comprehensive exception hierarchy for robust error management
85
- **Token Management**: Utilities for managing response sizes and token limits
86
- **Proxy Support**: Built-in support for HTTP/HTTPS proxies
87
88
This design enables flexible integration patterns while maintaining simplicity for basic use cases and power for advanced applications.
89
90
## Capabilities
91
92
### Web Search Operations
93
94
Comprehensive web search functionality including basic and advanced search modes, topic-focused searches, time-constrained queries, and specialized Q&A and company information searches.
95
96
```python { .api }
97
def search(
98
query: str,
99
search_depth: Literal["basic", "advanced"] = None,
100
topic: Literal["general", "news", "finance"] = None,
101
max_results: int = None,
102
**kwargs
103
) -> dict: ...
104
105
def get_search_context(
106
query: str,
107
max_tokens: int = 4000,
108
**kwargs
109
) -> str: ...
110
111
def qna_search(
112
query: str,
113
search_depth: Literal["basic", "advanced"] = "advanced",
114
**kwargs
115
) -> str: ...
116
```
117
118
[Search Operations](./search.md)
119
120
### Content Extraction and Web Crawling
121
122
Extract content from individual URLs or crawl entire websites with intelligent navigation, content filtering, and structured data extraction capabilities.
123
124
```python { .api }
125
def extract(
126
urls: Union[List[str], str],
127
extract_depth: Literal["basic", "advanced"] = None,
128
format: Literal["markdown", "text"] = None,
129
**kwargs
130
) -> dict: ...
131
132
def crawl(
133
url: str,
134
max_depth: int = None,
135
max_breadth: int = None,
136
instructions: str = None,
137
**kwargs
138
) -> dict: ...
139
```
140
141
[Content Operations](./content.md)
142
143
### Website Structure Mapping
144
145
Discover and map website structures without extracting full content, useful for understanding site architecture and finding relevant pages before detailed crawling.
146
147
```python { .api }
148
def map(
149
url: str,
150
max_depth: int = None,
151
max_breadth: int = None,
152
instructions: str = None,
153
**kwargs
154
) -> dict: ...
155
```
156
157
[Website Mapping](./mapping.md)
158
159
### Asynchronous Operations
160
161
Full async/await support for all API operations, enabling high-performance concurrent requests and integration with async frameworks.
162
163
```python { .api }
164
class AsyncTavilyClient:
165
async def search(self, query: str, **kwargs) -> dict: ...
166
async def extract(self, urls: Union[List[str], str], **kwargs) -> dict: ...
167
async def crawl(self, url: str, **kwargs) -> dict: ...
168
async def map(self, url: str, **kwargs) -> dict: ...
169
```
170
171
[Async Operations](./async.md)
172
173
### Hybrid RAG Integration
174
175
Combine Tavily's web search capabilities with local vector database searches for enhanced RAG applications, supporting MongoDB with custom embedding and ranking functions.
176
177
```python { .api }
178
class TavilyHybridClient:
179
def __init__(
180
self,
181
api_key: str,
182
db_provider: Literal['mongodb'],
183
collection,
184
index: str,
185
**kwargs
186
): ...
187
188
def search(
189
self,
190
query: str,
191
max_results: int = 10,
192
save_foreign: bool = False,
193
**kwargs
194
) -> list: ...
195
```
196
197
[Hybrid RAG](./hybrid-rag.md)
198
199
## Error Handling
200
201
All API operations can raise specific exceptions for different error conditions:
202
203
```python { .api }
204
class InvalidAPIKeyError(Exception): ...
205
class UsageLimitExceededError(Exception): ...
206
class MissingAPIKeyError(Exception): ...
207
class BadRequestError(Exception): ...
208
class ForbiddenError(Exception): ...
209
class TimeoutError(Exception): ...
210
```
211
212
Handle errors appropriately in your applications:
213
214
```python
215
from tavily import TavilyClient, InvalidAPIKeyError, UsageLimitExceededError, BadRequestError
216
from tavily.errors import ForbiddenError, TimeoutError
217
218
client = TavilyClient(api_key="your-key")
219
220
try:
221
results = client.search("your query")
222
except InvalidAPIKeyError:
223
print("Invalid API key provided")
224
except UsageLimitExceededError:
225
print("API usage limit exceeded")
226
except ForbiddenError:
227
print("Access forbidden")
228
except TimeoutError as e:
229
print(f"Request timed out after {e.timeout} seconds")
230
except BadRequestError as e:
231
print(f"Bad request: {e}")
232
except Exception as e:
233
print(f"Unexpected error: {e}")
234
```
235
236
## Types
237
238
```python { .api }
239
# Type aliases for parameter constraints
240
SearchDepth = Literal["basic", "advanced"]
241
Topic = Literal["general", "news", "finance"]
242
TimeRange = Literal["day", "week", "month", "year"]
243
ExtractDepth = Literal["basic", "advanced"]
244
ContentFormat = Literal["markdown", "text"]
245
AnswerMode = Union[bool, Literal["basic", "advanced"]]
246
RawContentMode = Union[bool, Literal["markdown", "text"]]
247
248
# Common parameter types
249
Domains = Sequence[str]
250
Paths = Sequence[str]
251
```