Search overview

What is the You.com Search API?

The You.com Search API delivers high-quality, structured web and news results optimized for AI applications and programmatic access. Designed for developers building RAG systems, AI agents, knowledge bases, and data-driven applications, our Search API returns clean, structured data with rich metadata, relevant snippets, and optional full-page content.

TL;DR: A fast, LLM-ready search API that returns structured JSON with web and news results. Perfect for feeding context into AI models, building knowledge systems, and powering data-driven applications.

How it works

The Search API processes your query and returns unified results from both web and news sources in a single request. Each result includes:

1. Core tnformation: URLs, titles, and descriptions
2. LLM-ready snippets: Query-aware text excerpts - the best snippets to answer your query will be provided
3. Rich metadata: Publication dates, authors, thumbnails, and favicons
4. Full page content: Live-crawled HTML or Markdown on demand

Our intelligent classification system automatically determines when to include news results based on query intent, ensuring you get the most relevant information for your use case.

What you get

Every search returns structured JSON with two main result types:

Web results

• Relevant web pages from across the internet
• Multiple text snippets per result for context
• Publication dates and author information
• Thumbnail images and favicons for UI display

News results (when relevant)

• Recent news articles from authoritative sources
• Article summaries and headlines
• Publication timestamps for freshness
• Associated images and metadata

All results are returned in clean, structured JSON format requiring no HTML parsing or post-processing.

Key features

Unified web & news results

Get both web pages and news articles in a single API call. Our classification system automatically determines when to include news results based on query intent.

1
{
2
  "results": {
3
    "web": [ // Web search results
4
      {
5
        "url": "https://example.com/article",
6
        "title": "Article Title",
7
        "description": "Brief description of the content",
8
        "snippets": [
9
          "Relevant excerpt from the page",
10
          "Another relevant passage"
11
        ],
12
        "thumbnail_url": "https://example.com/image.jpg",
13
        "page_age": "2025-11-15T10:30:00",
14
        "authors": ["Author Name"],
15
        "favicon_url": "https://example.com/favicon.ico"
16
      }
17
    ],
18
    "news": [ // News articles (when relevant)
19
      {
20
        "title": "Breaking News Article",
21
        "description": "News article summary",
22
        "url": "https://news.com/article",
23
        "page_age": "2025-11-15T14:00:00",
24
        "thumbnail_url": "https://news.com/image.jpg"
25
      }
26
    ]
27
  },
28
  "metadata": {
29
    "search_uuid": "942ccbdd-7705-4d9c-9d37-4ef386658e90",
30
    "query": "your search query",
31
    "latency": 0.342
32
  }
33
}

LLM-optimized output

Every result includes:

• Snippets: Pre-extracted relevant text excerpts
• Descriptions: Clean summaries without HTML clutter
• Metadata: Publication dates, authors, thumbnails, favicons
• Structured JSON: No parsing required, ready for AI consumption

Advanced search operators

Build powerful and precise search queries using search operators:

• site:domain.com - Search within specific domains
• filetype:pdf - Filter by file type
• +term / -term - Include/exclude specific terms
• Boolean operators: AND, OR, NOT

Learn more about search operators →

Live crawling

Retrieve full HTML or Markdown content from search results on-demand. Perfect for deep content analysis or building comprehensive knowledge bases.

1
from youdotcom import You
2
from youdotcom.types.typesafe_models import LiveCrawl, LiveCrawlFormats, print_search
3
4
with You(api_key_auth="YOUR_API_KEY") as you:
5
  res = you.search.unified(
6
    query="artificial intelligence in farming",
7
    count=1,
8
    livecrawl=LiveCrawl.WEB,
9
    livecrawl_formats=LiveCrawlFormats.MARKDOWN,
10
  )
11
12
  print_search(res)

Global coverage

Target results by geographic region using the country parameter (ISO 3166-2 country codes) and filter by language using the language parameter (BCP 47 language codes).

Freshness controls

Filter results by recency:

• day - Last 24 hours
• week - Last 7 days
• month - Last 30 days
• year - Last 365 days
• YYYY-MM-DDtoYYYY-MM-DD - Custom date range

All optional parameters you can control

View full API reference →

Quickstart

Get started with a simple search in under 30 seconds:

1
import os
2
from youdotcom import You
3
from youdotcom.types.typesafe_models import print_search
4
5
# Initialize the SDK with your API key
6
you = You("YOU_API_KEY")
7
8
# Perform a search
9
results = you.search.unified(
10
    query="global birth rate trends",
11
    count=5
12
)
13
14
# Access the results
15
print_search(results)

Common use cases

RAG (Retrieval-Augmented Generation)

Use search snippets to provide context to your LLM without hallucination. The structured snippets are perfect for feeding directly into your prompt.

1
from youdotcom import You
2
3
# Initialize
4
you = You("YOUR_KEY")
5
6
# Search and extract context
7
def get_context(query):
8
    response = you.search.unified(query=query, count=5)
9
    snippets = []
10
    if response.results and response.results.web:
11
        for result in response.results.web:
12
            if result.snippets:
13
                snippets.extend(result.snippets)
14
    return "\n".join(snippets)
15
16
context = get_context("quantum computing")
17
18
# Feed to your LLM
19
prompt = f"Based on this information:\n{context}\n\nAnswer: {user_question}"

AI agent knowledge retrieval

Give your AI agents access to real-time web information. Perfect for building agents that need up-to-date facts, news, or specialized domain knowledge.

News monitoring & alerts

Track breaking news, competitor mentions, or industry trends. The automatic news classification ensures you get timely articles when relevant.

Content research & analysis

Gather comprehensive information from multiple sources for content creation, competitive intelligence, or market research.

Knowledge base construction

Use live crawling to build comprehensive knowledge bases with full-page content in clean Markdown format.

Examples of advanced search capabilites

Search operators

Combine operators for powerful, precise searches:

1
from youdotcom import You
2
from youdotcom.types.typesafe_models import Freshness, print_search
3
4
with You(=YOUR_API_KEY") as you:
5
  # Find PDFs about climate change from .edu sites published this year
6
  res = you.search.unified(
7
      query="climate change site:.edu filetype:pdf",
8
      freshness=Freshness.YEAR,
9
  )
10
11
  print_search(res)

Pagination

Retrieve multiple pages of results:

1
from youdotcom import You
2
from youdotcom.types.typesafe_models import print_search
3
4
with You(api_key_auth="YOUR_API_KEY") as you:
5
  res = you.search.unified(
6
    query="machine learning",
7
    count=10,
8
    offset=1,
9
  )
10
11
  print_search(res)

Geographic targeting

Narrow down on results by country:

1
from youdotcom import You
2
from youdotcom.types.typesafe_models import Country, print_search
3
4
# Get Swiss results
5
with You(api_key_auth="YOUR_API_KEY") as you:
6
  res = you.search.unified(
7
    query="best restaurants in geneva",
8
    country=Country.CH,
9
  )
10
11
  print_search(res)

Refer to the ISO 3166-2 standard for a list of country codes.

Best practices

1. Use snippets for RAG

The snippets array is pre-processed for LLM consumption. Use it directly instead of crawling full pages when possible.

2. Implement caching

Cache frequent queries to reduce API calls and improve response times. Consider a 5-15 minute TTL for most use cases.

3. Handle empty results

Always check if results.web or results.news arrays are empty before processing:

1
if results.get("results", {}).get("web"):
2
    # Process results
3
else:
4
    # Handle no results case

4. Use appropriate count values

• For RAG: count=5-10 is usually sufficient
• For UI display: count=20-50 for pagination
• For data gathering: count=100 (max) for comprehensive coverage

5. Utilize search operators and query parameters

Use search operators and specify query parameters in the request to reduce noise and get more relevant results.

Rate limits & pricing

The Search API is optimized for high-throughput applications with generous rate limits. Pricing is based on:

• Number of API calls
• Use of optional features (live crawling)
• Result count per request

For detailed pricing and rate limit information, visit you.com/platform/upgrade or contact api@you.com.

Next steps