# Python SDK

We offer a Python SDK to make interacting with our APIs simple and predictable. It is available on PyPI [here](https://pypi.org/project/youdotcom/).
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](https://you.com/platform/).

#### Install the SDK

```bash
pip install youdotcom
```

#### Run a search

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

```python
import os
from youdotcom import You

# Initialize the SDK with your API key
you = You("YOUR_API_KEY")

# Perform a search
results = you.search.unified(
    query="latest AI developments"
)

# Access the results
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 renewable energy from the past week limited to 10 results per source type (either general `web`, or `news`), you simply write the following:

```python
from youdotcom.models import Freshness, Country

results = you.search.unified(
    query="renewable energy",
    count=10,
    freshness=Freshness.WEEK,
    country=Country.US,
)
```

Its capabilities don't end there. Learn more about the Search API in the [Search API reference](/api-reference/search/v1-search), and the Python SDK by visiting the open source repository on [GitHub](https://github.com/youdotcom-oss/youdotcom-python-sdk/).

## Response structure

The Search API returns a `GetV1SearchResponse` object (see [documentation](https://github.com/youdotcom-oss/youdotcom-python-sdk/blob/main/docs/models/getv1searchresponse.md)):

* **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:

```python
import os
from youdotcom import You, errors

api_key = os.getenv("YOU_API_KEY")

try:
    with You(api_key_auth=api_key) as you:
        results = you.search.unified(query="your query")
        print(results)
except errors.YouError as e:
    print(f"Search failed: {e.message}")
    print(f"Status code: {e.status_code}")
```

## Learn more

For more information on how to use the SDK, refer to the official [PyPI page](https://pypi.org/project/youdotcom/) or the open source repository on [GitHub](https://github.com/youdotcom-oss/youdotcom-python-sdk).