*** title: Search overview subtitle: 'Get structured, LLM-optimized search results from web and news sources.' 'og:title': You.com Search API | LLM-Ready Web & News Results 'og:description': >- Get structured, LLM-optimized search results from web and news sources. Perfect for AI agents, RAG applications, and real-time information retrieval. ----------------------------------------------------------------------------- ## What is the You.com Search API? The You.com Search API delivers high-quality, structured web and news results optimized for programmatic access in AI applications. 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 full-page content. ## 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. **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 * Full article content (HTML or Markdown) via live crawling All results are returned in clean, structured JSON format requiring no HTML parsing or post-processing. *** ## Key features ### Live crawling — full page content per result With snippets alone, you get \~100–200 words of extracted text per result. With `livecrawl` enabled, you get the full page content—often 2,000–10,000 words of HTML or Markdown. This is what unlocks deep RAG, comprehensive synthesis, and knowledge base construction from search results. Add `livecrawl` to any search request and each matching result gains a `contents` object with the full page content in your chosen format. Crawl `web`, `news` or `all` results. Set `livecrawl_formats` to `markdown` (recommended for LLMs) or `html`. ```python startLine={5} from youdotcom import You from youdotcom.models import LiveCrawl, LiveCrawlFormats with You(api_key_auth="api_key") as you: # Livecrawl both web and news results res = you.search.unified( query="latest AI developments", count=5, livecrawl=LiveCrawl.ALL, livecrawl_formats=LiveCrawlFormats.MARKDOWN, ) # Access live-crawled content from web results if res.results and res.results.web: for result in res.results.web: if result.contents: print(f"Web: {result.title}") print(f"Content: {result.contents.markdown[:200]}...\n") # Access live-crawled content from news results if res.results and res.results.news: for result in res.results.news: if result.contents: print(f"News: {result.title}") print(f"Content: {result.contents.markdown[:200]}...\n") ``` ```typescript import { You } from "@youdotcom-oss/sdk"; import { LiveCrawl, LiveCrawlFormats } from "@youdotcom-oss/sdk/models"; const you = new You({ apiKeyAuth: "api_key", }); async function run() { // Livecrawl both web and news results const result = await you.search({ query: "latest AI developments", count: 5, livecrawl: LiveCrawl.All, livecrawlFormats: LiveCrawlFormats.Markdown, }); // Access live-crawled content from both web and news results result.results?.web?.forEach((r) => { if (r.contents?.markdown) { console.log(`Web: ${r.title}`); console.log(`Content: ${r.contents.markdown.slice(0, 200)}...\n`); } }); result.results?.news?.forEach((r) => { if (r.contents?.markdown) { console.log(`News: ${r.title}`); console.log(`Content: ${r.contents.markdown.slice(0, 200)}...\n`); } }); } run(); ``` ```curl # Livecrawl both web and news results curl -G https://ydc-index.io/v1/search \ -H "X-API-Key: api_key" \ --data-urlencode "query=latest AI developments" \ -d count=5 \ -d livecrawl=all \ -d livecrawl_formats=markdown ``` **Need content from specific URLs you already have?** Use the [Contents API](/contents/overview) instead — it takes a list of URLs directly, without requiring a search query. ### 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. ```json maxLines=20 { "results": { "web": [ // Web search results { "url": "https://example.com/article", "title": "Article Title", "description": "Brief description of the content", "snippets": [ "Relevant excerpt from the page", "Another relevant passage" ], "thumbnail_url": "https://example.com/image.jpg", "page_age": "2025-11-15T10:30:00", "authors": ["Author Name"], "favicon_url": "https://example.com/favicon.ico", "contents": { // Included when livecrawl is "web" or "all" "markdown": "# Article Title\n\nFull page content..." } } ], "news": [ // News articles (when relevant) { "title": "Breaking News Article", "description": "News article summary", "url": "https://news.com/article", "page_age": "2025-11-15T14:00:00", "thumbnail_url": "https://news.com/image.jpg", "contents": { // Included when livecrawl is "news" or "all" "markdown": "# Breaking News\n\nFull article content..." } } ] }, "metadata": { "search_uuid": "942ccbdd-7705-4d9c-9d37-4ef386658e90", "query": "your search query", "latency": 0.342 } } ``` ### 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](/search/search-operators) ### 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 | Parameter | Type | Description | | ------------------- | ------- | ----------------------------------------------------------------------------------------------------- | | `query` | string | Your search query (supports [search operators](/search/search-operators)) | | `count` | integer | Max results per section (default varies, max 100) | | `freshness` | string | `day`, `week`, `month`, `year`, or date range | | `country` | string | Country code (e.g., `US`, `GB`, `FR`) | | `language` | string | BCP 47 language code (e.g., `EN`, `JP`, `DE`) | | `offset` | integer | For pagination (0-9) | | `safesearch` | string | `off`, `moderate` (default), `strict` | | `livecrawl` | string | `web`, `news`, or `all` | | `livecrawl_formats` | string | `html` or `markdown` | | `crawl_timeout` | integer | Maximum livecrawl timeout in seconds (`1-60`, default `10`). Applies only when `livecrawl` is enabled | [View full API reference](/api-reference/search/v1-search) *** ## 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. See a working RAG app that lets users ask AI questions about their own private documents. ```python from youdotcom import You # Initialize you = You("YOUR_KEY") # Search and extract context def get_context(query): response = you.search.unified(query=query, count=5) snippets = [] if response.results and response.results.web: for result in response.results.web: if result.snippets: snippets.extend(result.snippets) return "\n".join(snippets) context = get_context("quantum computing") # Feed to your LLM 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. See a working app that runs a web search and returns the top results. ### 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: ```python from youdotcom import You from youdotcom.models import Freshness with You(api_key_auth="api_key") as you: # Find PDFs about climate change from .edu sites published this year res = you.search.unified( query="climate change site:.edu filetype:pdf", freshness=Freshness.YEAR, ) # Print PDF results with their URLs if res.results and res.results.web: for result in res.results.web: print(f"{result.title}") print(f" PDF URL: {result.url}") ``` ```typescript import { You } from "@youdotcom-oss/sdk"; import { Freshness } from "@youdotcom-oss/sdk/models"; const you = new You({ apiKeyAuth: "api_key", }); async function run() { // Find PDFs about climate change from .edu sites published this year const result = await you.search({ query: "climate change site:.edu filetype:pdf", freshness: Freshness.Year, }); console.log(result); } run(); ``` ```curl # Find PDFs about climate change from .edu sites published this year curl -G 'https://ydc-index.io/v1/search' \ -H 'X-API-Key: api_key' \ --data-urlencode 'query=climate change site:.edu filetype:pdf' \ -d 'freshness=year' ``` ### Pagination Use `offset` to retrieve additional pages of results. The offset value (0-9) skips that many pages, so `offset=1` with `count=10` returns results 11-20. ```python from youdotcom import You with You(api_key_auth="api_key") as you: # Get the second page of results res = you.search.unified( query="machine learning", count=10, offset=1, ) print(res.results.web) ``` ```typescript import { You } from "@youdotcom-oss/sdk"; const you = new You({ apiKeyAuth: "api_key", }); async function run() { // Get the second page of results const result = await you.search({ query: "machine learning", count: 10, offset: 1, }); console.log(result); } run(); ``` ```curl # Get the second page of results (results 11-20) curl -G 'https://ydc-index.io/v1/search' \ -H 'X-API-Key: api_key' \ --data-urlencode 'query=machine learning' \ -d 'count=10' \ -d 'offset=1' ``` ### Geographic targeting Narrow down on results by country: ```python from youdotcom import You from youdotcom.models import Country # Get Swiss results with You(api_key_auth="api_key") as you: res = you.search.unified( query="best restaurants in geneva", country=Country.CH, ) # Print restaurant results with descriptions if res.results and res.results.web: for result in res.results.web: print(f"{result.title}") if result.description: print(f" {result.description}\n") ``` ```typescript import { You } from "@youdotcom-oss/sdk"; import { Country } from "@youdotcom-oss/sdk/models"; const you = new You({ apiKeyAuth: "api_key", }); async function run() { // Get Swiss results const result = await you.search({ query: "best restaurants in geneva", country: Country.Ch, }); console.log(result); } run(); ``` ```curl # Get Swiss results curl -G 'https://ydc-index.io/v1/search' \ -H 'X-API-Key: api_key' \ -d 'query=best restaurants in geneva' \ -d 'country=CH' ``` Refer to the [ISO 3166-2](https://en.wikipedia.org/wiki/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: ```python if results.get("results", {}).get("web"): # Process results else: # 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. Use search operators and query parameters Use search operators and specify [query parameters](/api-reference/search/v1-search#request.query) 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](https://you.com/platform/upgrade) or contact [api@you.com](mailto:api@you.com). *** ## Next steps Use our Postman collections to learn and experiment on your own Run In Postman Explore the complete API documentation with all parameters and response schemas Master advanced search operators to refine your queries Learn from practical examples and integration guides Get your API key and make your first search in 5 minutes ***