Python SDK

We offer an official Python SDK to make interacting with our APIs simple and predicatable. It is available on PyPI here. Now you can get started with our APIs with just a few lines of code.

Quickstart

Get an API key

Get one for free on the You.com platform.

Install the SDK

$
pip install youdotcom

Run a search

Now, you can perform a simple search to retrieve results from general web and news sources.

1
import os
2
from youdotcom import You
3
4
# Initialize the SDK with your API key
5
you = You("YOUR_API_KEY")
6
7
# Perform a search
8
results = you.search.unified(
9
    query="latest AI developments"
10
)
11
12
# Access the results
13
print(results)

That’s it! You now have a comprehensive set of search results combining web and news sources.

What’s next?

Our search API offers several powerful 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 US about renewal energy from the past week limited to 10 results per source type (either general web, or news), you simply write the following:

1
from youdotcom.types.typesafe_models import Freshness, Country
2
3
results = you.search.unified(
4
    query="renewable energy",
5
    count=10,
6
    freshness=Freshness.WEEK,
7
    country=Country.US,
8
)

Its capabilities don’t end there. Learn more in the Search API reference, and use the interactive playground to experiment.

Response structure

The Search API returns a GetV1SearchResponse object (see documentation):

• results: Contains search results.

  • web: An array of web result objects. Each object may include:
    • url: The URL of the web page.
    • title: The title of the web page.
    • description: A brief description of the web page.
    • snippets: An array of relevant text snippets from the page.
    • thumbnail_url: (Optional) URL to a thumbnail image representing the page.
    • page_age: (Optional) Timestamp or date indicating the age of the page.
    • favicon_url: (Optional) URL to the favicon of the website.
  • news: An array of news result objects. Each object may include:
    • url: The URL of the news article.
    • title: The title of the news article.
    • description: A brief description of the news article.
    • thumbnail_url: (Optional) URL to a thumbnail image representing the article.
    • page_age: (Optional) Timestamp or date indicating the age of the article.

• metadata: Information about the search query and results.

  • query: The search query used to retrieve the results.
  • search_uuid: Unique UUID identifying the search request.
  • latency: The latency (in seconds) of the search call.

Error handling

Always handle potential errors when making API requests:

1
...
2
3
api_key = os.getenv("YOU_API_KEY")
4
5
try:
6
    with You(api_key_auth=api_key) as you:
7
        results = you.search.unified(query="your query")
8
        print(results)
9
except YouError as e:
10
    print(f"Search failed: {e.message}")
11
    print(f"Status code: {e.status_code}")

Learn more

For more information on how to use the SDK, refer to the official PyPI page or the open source repository on GitHub.