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 Information: 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. Optional Full 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 intelligent classification automatically determines when to include news results based on query intent.

1
{
2
  "results": {
3
    "web": [...],  // Web search results
4
    "news": [...]  // News articles (when relevant)
5
  }
6
}

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

Refine your searches with powerful operators:

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

Learn more about Search Operators →

Live Crawling

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

$
curl 'https://api.ydc-index.io/v1/search?query=AI&livecrawl=web&livecrawl_formats=markdown' \
>
  -H 'X-API-Key: YOUR_API_KEY'

Global Coverage

Support for 35+ countries with geographic targeting to get region-specific results. Perfect for localized applications or international deployments.

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

Quick Start

Get started with a simple search in under 30 seconds:

$
curl -X GET \
>
  'https://api.ydc-index.io/v1/search?query=artificial%20intelligence&count=5' \
>
  -H 'X-API-Key: YOUR_API_KEY'

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.

API Endpoints

/v1/search - Primary Search Endpoint

The main endpoint for unified web and news search.

Base URL: https://api.ydc-index.io/v1/search

Method: GET

Key Parameters:

View Full API Reference →

Response Structure

Every search returns structured JSON with two main sections:

1
{
2
  "results": {
3
    "web": [
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": [
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
    "request_uuid": "942ccbdd-7705-4d9c-9d37-4ef386658e90",
30
    "query": "your search query",
31
    "latency": 0.342
32
  }
33
}

Advanced Features

Search Operators Example

Combine operators for powerful, precise searches:

$
# Find PDFs about climate change from .edu sites published this year
>
curl 'https://api.ydc-index.io/v1/search?query=climate+change+site:.edu+filetype:pdf&freshness=year' \
>
  -H 'X-API-Key: YOUR_API_KEY'

Pagination Example

Retrieve multiple pages of results:

1
# Get results 11-20 (offset=1, count=10)
2
params = {
3
    "query": "machine learning",
4
    "count": 10,
5
    "offset": 1  # offset * count = starting position
6
}

Geographic Targeting

Get region-specific results narrowed down by country:

$
# Get Swiss results
>
curl 'https://api.ydc-index.io/v1/search?query=restaurants&country=CH' \
>
  -H 'X-API-Key: YOUR_API_KEY'

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

Integration Examples

Building a RAG Application

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
# Use in your LLM prompt
17
context = get_context("quantum computing")

1
from youdotcom import You
2
from youdotcom.types.typesafe_models import AgentType
3
4
# Initialize
5
you = You("YOUR_KEY")
6
7
# Combine Search API with Agents
8
# Step 1: Get raw data with Search API
9
search_results = you.search.unified(query=query)
10
11
# Step 2: Let Agent synthesize
12
agent_response = you.agents.runs.create(
13
    agent=AgentType.EXPRESS,
14
    input=search_results
15
)

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. Leverage Search Operators

Use operators to reduce noise and get more relevant results:

• site: for domain-specific searches
• filetype: for document searches
• +term for must-include keywords

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