> For clean Markdown of any page, append `.md` to the page URL.
> Documentation index: https://you.com/docs/llms.txt (section indexes: append `/llms.txt` to any section URL).
> Search these docs: Docs MCP at https://you.com/docs/_mcp/server (`searchDocs`, no API key).
> Call live You.com APIs: Product MCP at https://api.you.com/mcp (keyless `?profile=free` exposes `you-search` and `you-discover`. Research and finance use `/mcp/research`, `/mcp/finance`, or `?tools=` on `/mcp`). To pick an API or integration path, call `you-discover` on that server instead of guessing.
> OpenAPI: https://you.com/docs/openapi.json—auth header `X-API-Key`, env `YDC_API_KEY`.

# Web Search API Quickstart

The Web Search API returns real-time web and news results as structured, LLM-ready JSON. Feed the results into your prompt to ground a model in fresh information.

> **Info**
>
> Get an API key at [you.com/platform](https://you.com/platform). The samples below read `YDC_API_KEY`. See the [site Quickstart](/docs/quickstart) for the five-API tour and [API key management](/docs/administration/api-keys) for best practices.

```python
from youdotcom import You

with You() as you:
    results = you.search(query="global birth rate trends", count=5)

    for result in results.results.web:
        print(result.title)
        print(result.url)
        if result.snippets:
            print(result.snippets[0])
```

```typescript
const response = await fetch("https://ydc-index.io/v1/search", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.YDC_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "global birth rate trends",
    count: 5,
  }),
});

const result = await response.json();

result.results?.web?.forEach((r) => {
  console.log(r.title, r.url);
  console.log(r.snippets?.[0]);
});
```

```curl
curl -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "global birth rate trends",
    "count": 5
  }'
```

You'll get back structured JSON like this:

```json maxLines=20
{
  "results": {
    "web": [
      {
        "url": "https://www.worldbank.org/en/topic/population",
        "title": "Population | World Bank",
        "description": "The World Bank tracks global birth rate and population trends.",
        "snippets": [
          "Global fertility rates have declined significantly over the past five decades, falling from an average of 5 births per woman in 1960 to around 2.3 today."
        ],
        "page_age": "2025-10-01T00:00:00",
        "favicon_url": "https://ydc-index.io/favicon?domain=worldbank.org&size=128"
      }
    ]
  },
  "metadata": {
    "query": "global birth rate trends",
    "search_uuid": "a1b2c3d4-0000-0000-0000-000000000000",
    "latency": 0.38
  }
}
```

> **TypeScript, MCP, or the Python SDK**
>
> TypeScript and JavaScript have three paths. Use `fetch` against the REST APIs when the application needs the JSON. Use [`@youdotcom-oss/mcp`](https://www.npmjs.com/package/@youdotcom-oss/mcp), or the hosted server at `https://api.you.com/mcp`, when an agent should call the tools. Use the [Python SDK](/docs/integrations/python-sdk) when you want a typed client that tracks new API fields. The `@youdotcom-oss/sdk` package is deprecated.

## Add Full Page Content

Search results already include snippets. Use `extraction` with `extraction_mode: "full_page"` to attach clean Markdown or HTML for each result. See [Retrieve page content](/docs/guides/search/retrieve-page-content) for highlights, cache vs. live crawl, and pricing.

```python
from youdotcom import You
from youdotcom.models import Extraction, ExtractionFormat, ExtractionMode

with You() as you:
    results = you.search(
        query="global birth rate trends",
        count=5,
        extraction=Extraction(
            extraction_mode=ExtractionMode.FULL_PAGE,
            full_page={"extraction_formats": [ExtractionFormat.MARKDOWN]},
        ),
    )

    for result in results.results.web:
        if result.contents and result.contents.markdown:
            print(result.title)
            print(result.contents.markdown[:400])
```

```typescript
const response = await fetch("https://ydc-index.io/v1/search", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.YDC_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "global birth rate trends",
    count: 5,
    extraction: {
      extraction_mode: "full_page",
      full_page: {
        extraction_formats: ["markdown"],
      },
    },
  }),
});

const result = await response.json();

result.results?.web?.forEach((r) => {
  if (r.contents?.markdown) {
    console.log(r.title);
    console.log(r.contents.markdown.slice(0, 400));
  }
});
```

```curl
curl -X POST https://ydc-index.io/v1/search \
  -H "X-API-Key: $YDC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "global birth rate trends",
    "count": 5,
    "extraction": {
      "extraction_mode": "full_page",
      "full_page": {
        "extraction_formats": ["markdown"]
      }
    }
  }'
```

#### [Try in Postman](https://www.postman.com/youdotcom/you-com-api-workspace/collection/46015159-83118dc1-7279-49f6-893d-4c18b8163008)

Fork the Web Search API collection, add your API key to the `production` environment, and hit Send.

## Next Steps

#### [Web Search API Overview](/docs/guides/search)

How the API works, what you get, pricing, and when to use each feature

#### [Retrieve page content](/docs/guides/search/retrieve-page-content)

Highlights vs. full page content, extraction source, and crawl timeout

#### [API reference](/docs/api-reference/search/v1-search)

Full parameter reference, request/response schemas, and playground

#### [Site Quickstart](/docs/quickstart)

Try Answer, Contents, Research, and Finance Research in one tour