Runnable examples

Simple Search

Your first API call in 2 minutes—fetch real-time web results in under 20 lines.

View as MarkdownOpen in Claude

If you’re new to the You.com API, this is the right place to begin. Before building RAG pipelines or research agents, you need to understand the foundation: the Search API. Send a query. Get back accurate web and news results.

The Search API gives you direct access to You.com’s search index—the same index that powers our Research API and our own search engine. You get titles, URLs, and descriptions for the most relevant pages on the web, fast. Then you decide what to do with them: filter them, rank them, display them in a UI, or feed them into a language model to synthesize an answer.

This example shows the simplest possible way to call it: a Python script and a small Next.js web app you can deploy to Vercel.

Try It Live

Run a real Search API request right here—no setup, no separate app to deploy. Open the Try It panel below, paste your API key, edit the query, and send it against the live endpoint.

POST
/v1/search
1curl -X POST https://ydc-index.io/v1/search \
2     -H "X-API-Key: <apiKey>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "query": "What are the latest geopolitical updates from India",
6  "count": 10,
7  "include_domains": [
8    "timesofindia.indiatimes.com",
9    "ndtv.com",
10    "thehindu.com"
11  ]
12}'
Try it
Response
1{
2  "results": {
3    "web": [
4      {
5        "url": "https://timesofindia.indiatimes.com/topic/geopolitics/news",
6        "title": "Geopolitics News | Latest News on Geopolitics - Times of India",
7        "description": "European nations, particularly Denmark and Norway, are scrutinizing Chinese-made Yutong buses over security fears. Operators worry that 'over-the-air' software updates could allow remote immobilization of the fleet, mirroring concerns over Chinese tech in 5G networks. This potential vulnerability, inherent in connected vehicles, raises geopolitical questions about reliance on foreign manufacturers. India ...",
8        "snippets": [
9          "European nations, particularly Denmark and Norway, are scrutinizing Chinese-made Yutong buses over security fears. Operators worry that 'over-the-air' software updates could allow remote immobilization of the fleet, mirroring concerns over Chinese tech in 5G networks. This potential vulnerability, inherent in connected vehicles, raises geopolitical questions about reliance on foreign manufacturers. India secures 3rd place in Oz think tank's Asia Power Index",
10          "Nations like New Zealand, parts of Australia, Iceland, and select South American and African countries are frequently cited as potentially more resilient to widespread conflict and its devastating aftermath. India-EU summit: FTA, defence and connectivity among key outcomes, EU seeks Paris commitment ... Pheasant Island, a tiny river island between Spain and France, uniquely swaps sovereignty every six months. This geopolitical gem's alternating control stems from the 1659 Treaty of the Pyrenees, a testament to centuries of cooperation.",
11          "Check out for the latest news on geopolitics along with geopolitics live news at Times of India",
12          "Despite massive viewership, he feels his content tackling geopolitical issues is too risky for corporate partners, leading him to expect no further wins. Economy enters H2 on stable footing: Finance ministry ... India's economy enters the second half of FY26 on a stable footing, supported by contained inflation, resilient domestic demand, and supportive policies. While global uncertainties pose risks to exports and capital flows, strong public capital expenditure and firming rural and urban demand are expected to maintain growth momentum."
13        ],
14        "thumbnail_url": "https://static.toiimg.com/photo/47529300.cms",
15        "favicon_url": "https://you.com/favicon?domain=timesofindia.indiatimes.com&size=128"
16      },
17      {
18        "url": "https://www.ndtv.com/topic/geopolitical",
19        "title": "Geopolitical: Latest News, Photos, Videos on Geopolitical - NDTV.COM",
20        "description": "Find Geopolitical Latest News, Videos & Pictures on Geopolitical and see latest updates, news, information from NDTV.COM. Explore more on Geopolitical.",
21        "snippets": [
22          "Gold surged above $4,000 an ounce to hit a record on Wednesday, driven by investors seeking safety from mounting economic and geopolitical uncertainty, alongside expectations of further interest rate cuts by the US Federal Reserve. In a landmark development that could reshape regional geopolitics, Afghan Foreign Minister Amir Khan Muttaqi of the Taliban government is all set to visit India on October 9.",
23          "IndiGo flight 6E1703 from Kolkata touched down in the southern Chinese city of Guangzhou shortly before 4:00 am, officially resuming nonstop air links that had been suspended since 2020 due to the pandemic and subsequent geopolitical tensions.",
24          "China's new visa programme aimed at attracting foreign tech talent launches this week, a move seen boosting Beijing's fortunes in its geopolitical rivalry with Washington as a new US visa policy prompts would-be applicants to search for alternatives.",
25          "India's defence manufacturing is not only about Atmanirbharta, but also about making in India and selling to the world, according to industry leaders at the NDTV Defence Summit 2025."
26        ],
27        "thumbnail_url": "https://cdn.ndtv.com/common/images/ogndtv.png",
28        "favicon_url": "https://you.com/favicon?domain=www.ndtv.com&size=128"
29      }
30    ],
31    "news": [
32      {
33        "title": "India entering golden era of defence innovation: Rajnath",
34        "description": "New Delhi, Nov 25 (PTI) Amid a rapidly changing world and evolving geopolitics, India must move beyond a reactive approach and adopt a \"proactive\" outlook to make itself future-ready, Defence Minister Rajnath Singh said on Tuesday.",
35        "page_age": "2025-11-25T12:31:29",
36        "thumbnail_url": "https://static.theprint.in/wp-content/uploads/2023/06/theprint_default_image_new.jpg",
37        "url": "https://theprint.in/india/india-entering-golden-era-of-defence-innovation-rajnath/2791865/"
38      },
39      {
40        "title": "India-Pakistan Tensions: Geopolitical Fallout and Regional Stability",
41        "description": "As tensions between India and Pakistan persist following recent military exchanges, analysts assess the broader geopolitical implications for South Asia and global powers.",
42        "page_age": "2025-11-20T08:15:00",
43        "thumbnail_url": "https://cdn.ndtv.com/common/images/ogndtv.png",
44        "url": "https://www.ndtv.com/india-news/india-pakistan-tensions-geopolitical-fallout-2025"
45      }
46    ]
47  },
48  "metadata": {
49    "search_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
50    "query": "What are the latest geopolitical updates from India",
51    "latency": 0.6842031478881836
52  }
53}

What You’ll Build

The simplest possible example of the You.com Search API—pass a query, get back web results. No agents, no chaining, no extra dependencies. The unified endpoint returns title, URL, and description for the top results, ready to feed an LLM or render in a UI.

Prerequisites

Get a You.com API key

Sign up at you.com/platform to get your API key. The free tier includes 100 requests/day.

Install the SDK for your language:

$pip install youdotcom        # Python ≥ 3.10
$npm install @youdotcom-oss/sdk   # Node ≥ 20

Run It

The quickest way to see the API in action is the command line.

simple_search.py
1"""Simple Search — the "hello world" of the You.com Search API."""
2
3import sys
4
5from youdotcom import You
6
7# take query from command line args, or use a default
8query = sys.argv[1] if len(sys.argv) > 1 else "best programming languages 2026"
9
10# initialize the client with your API key
11you = You()
12
13# run the search
14response = you.search(query=query, count=5)
15
16# print each result
17for result in response.results.web:
18    print(f"{result.title}")
19    print(f"  {result.url}")
20    print(f"  {result.description}")
21    print()

Run it:

$export YDC_API_KEY="your-api-key-here"
$python simple_search.py "what is retrieval augmented generation"

No query? No problem—the example falls back to a default one, so python simple_search.py works too.

What you get back:

Each result has a title, URL, and a short description pulled from the page—clean, structured, and ready to use:

Title: What is RAG (Retrieval-Augmented Generation)? | IBM
  https://www.ibm.com/topics/retrieval-augmented-generation
  RAG is an AI framework that combines the strengths of traditional information
  retrieval systems with the capabilities of generative large language models.

Next Steps

Research Agent

Instead of raw results, get a synthesized, cited answer written by an agent that reads the web for you.

Contents Extraction

Turn any URL into clean Markdown—ideal for LLM ingestion.

Search API Reference

Full docs for filtering by freshness, country, language, and more.

Resources