***

## title: Simple Search

<DemoPreview href="https://you.com/examples/search/" thumbnailUrl="https://cdn.you.com/img/docs/SimpleSearchTemplateThumbnail.png" thumbnailDarkUrl="https://cdn.you.com/img/docs/SimpleSearchTemplateThumbnailDark.png" />

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.

***

## Prerequisites

<Card title="Get a You.com API key" icon="key" href="https://you.com/platform">
  Sign up at you.com/platform to get your API key.
</Card>

***

## Run It

<Tabs>
  <Tab title="Python" language="python">
    The quickest way to see the API in action is the command line.

    ```bash
    pip install -r requirements.txt
    export YDC_API_KEY="your-api-key-here"
    python simple_search.py "what is retrieval augmented generation"
    ```

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

    **What you get back:**

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

    Each result has a title, URL, and a short description pulled from the page. Clean, structured, ready to use.
  </Tab>

  <Tab title="Web App" language="typescript">
    The repo also includes a Next.js web app if you'd rather see it in a browser.

    ```bash
    cp .env.example .env.local
    # edit .env.local and add your key
    npm install
    npm run dev
    ```

    Open [localhost:3000](http://localhost:3000), type a query, and the results show up as cards with favicons. The search happens server-side so your API key never touches the browser.

    **Deploy to Vercel:**

    <Steps>
      <Step title="Push to GitHub">
        Push this repo to your GitHub account.
      </Step>

      <Step title="Import on Vercel">
        Import it at [vercel.com/new](https://vercel.com/new).
      </Step>

      <Step title="Add your API key">
        Add `YDC_API_KEY` as an environment variable in your Vercel project settings.
      </Step>

      <Step title="Deploy">
        Hit deploy. Vercel auto-detects Next.js and handles the rest.
      </Step>
    </Steps>
  </Tab>
</Tabs>

***

## How It Works

Both the script and the web app do the same three things:

1. Take a search query
2. Call the You.com Search API via the Python or TypeScript SDK
3. Display the title, URL, and description for each result

The web app just adds a layer of UI on top: a search input, result cards with favicons, and You.com branding. The API route (`app/api/search/route.ts`) keeps your key server-side.

***

## What's Next

<CardGroup cols={3}>
  <Card title="Research API" icon="flask" href="/api-reference/research/v1-research">
    Instead of raw results, get a synthesized, cited answer written by an agent that reads the web for you.
  </Card>

  <Card title="Private RAG" icon="lock" href="/examples/private-rag">
    Use your own documents to ground an LLM response — no web search needed.
  </Card>

  <Card title="Search API Reference" icon="book" href="/api-reference/search/v1-search">
    Full docs for filtering by freshness, country, language, and more.
  </Card>
</CardGroup>

***

## Resources

* [Search API Reference](/api-reference/search/v1-search)
* [Python SDK on PyPI](https://pypi.org/project/youdotcom/) (`pip install youdotcom`)
* [TypeScript SDK on npm](https://www.npmjs.com/package/@youdotcom-oss/sdk) (`npm install @youdotcom-oss/sdk`)
* [GitHub: ydc-simple-search-sample](https://github.com/youdotcom-oss/ydc-simple-search-sample)
* [Live Demo](https://you.com/examples/search)
* [Discord](https://discord.com/invite/youdotcom/)