Python SDK

We offer a Python SDK to make interacting with our APIs simple and predictable. It covers the Web Search, Answer, Contents, Research, and Finance Research APIs, and is available on PyPI here. Now you can get started with our APIs with just a few lines of code.

Quickstart

$
pip install youdotcom

1
from youdotcom import You
2
3
# Initialize the SDK — it reads your key from YDC_API_KEY
4
you = You()
5
6
# Perform a search
7
results = you.search(
8
    query="latest AI developments"
9
)
10
11
# Access the results
12
print(results)

What’s next?

The Web Search API offers filters that can help you find exactly what you need, whether you want to go broader or narrower. For example, to find recent information in the United States about renewable energy from the past week limited to 10 results per source type, either web or news, write:

1
from youdotcom import You
2
from youdotcom.models import Freshness, Country
3
4
with You() as you:
5
    results = you.search(
6
        query="renewable energy",
7
        count=10,
8
        freshness=Freshness.WEEK,
9
        country=Country.US,
10
    )

Learn more about the Web Search API in the Web Search API reference, and the Python SDK by visiting the open source repository on GitHub.

Response Structure

The Web Search API returns a SearchResponse object (see documentation):

Long-Running Research

Research at deep, exhaustive, or frontier effort can run for minutes, which is long enough to exceed a client timeout or tie up a worker. Run those in background mode and let the SDK handle the task lifecycle. The helpers live in youdotcom.research_helpers, which is a separate import from the client itself.

1
from youdotcom import You
2
from youdotcom.models import ResearchEffort
3
from youdotcom.research_helpers import research_and_wait
4
5
with You() as you:
6
    task = research_and_wait(
7
        you,
8
        input="Which global cities improved air quality the most over the past 10 years?",
9
        research_effort=ResearchEffort.FRONTIER,
10
        timeout_s=600,
11
    )
12
    print(task.status)
13
    print(task.result.output["content"])

Pick the helper that matches how your code is shaped:

Every helper has an _async counterpart (research_and_wait_async, poll_research_task_async, stream_research_async, research_background_async) for use with asyncio.

For the full background task lifecycle, including the raw endpoints behind these helpers, see the Research API guide.

Error Handling

Always handle potential errors when making API requests:

1
from youdotcom import You, errors
2
3
try:
4
    with You() as you:
5
        results = you.search(query="your query")
6
        print(results)
7
except errors.YouError as e:
8
    print(f"Search failed: {e.message}")
9
    print(f"Status code: {e.status_code}")

Learn More