TypeScript SDK | You.com | You.com

We offer a TypeScript SDK to make interacting with our APIs simple and predictable. It is available on npm here. Now you can get started with our APIs with just a few lines of code.

Install our docs MCP server

This documentation ships with a Docs MCP Server that gives any MCP-enabled agent a searchDocs tool to search every page here and get back relevant passages with source URLs — no API key required. Point your client at https://you.com/docs/_mcp/server. See the Docs MCP Server guide for setup and examples.

Quickstart

Get an API Key

Get one for free on the You.com platform.

Install the SDK

$ npm add @youdotcom-oss/sdk

Run a Search

Perform a simple search to retrieve results from general web and news sources.

1 import { You } from "@youdotcom-oss/sdk";
2 
3 // Initialize the SDK with your API key
4 const you = new You({
5   apiKeyAuth: process.env.YDC_API_KEY,
6 });
7 
8 async function main() {
9   // Perform a search
10   const results = await you.search({
11     query: "latest AI developments",
12   });
13 
14   // Access the results
15   console.log(results);
16 }
17 
18 main();

That’s it. You now have a comprehensive set of search results combining web and news sources.

What’s next?

The Web Search API offers filters that can help you find exactly what you need, whether you want to go broader or narrower. For example, to find recent information in the United States about renewable energy from the past week limited to 10 results per source type, either web or news, write:

1 import { You } from "@youdotcom-oss/sdk";
2 import { Freshness, Country } from "@youdotcom-oss/sdk/models";
3 
4 const you = new You({
5   apiKeyAuth: process.env.YDC_API_KEY,
6 });
7 
8 async function main() {
9   const results = await you.search({
10     query: "renewable energy",
11     count: 10,
12     freshness: Freshness.Week,
13     country: Country.Us,
14   });
15 
16   console.log(results);
17 }
18 
19 main();

Learn more about the Web Search API in the Web Search API reference, and the TypeScript SDK by visiting the open source repository on GitHub.

Response Structure

The Web Search API returns a SearchResponse object (see documentation):

results.web

An array of web result objects. Each object may include url, title, description, snippets, thumbnailUrl, pageAge, and faviconUrl.

results.news

An array of news article objects. Each object may include url, title, description, thumbnailUrl, and pageAge.

metadata

Information about the search query and response, including query, searchUuid, and latency.

Error Handling

Always handle potential errors when making API requests:

1 import { You } from "@youdotcom-oss/sdk";
2 import { YouError } from "@youdotcom-oss/sdk/models/errors";
3 
4 const you = new You({ apiKeyAuth: process.env.YDC_API_KEY });
5 
6 async function main() {
7   try {
8     const results = await you.search({ query: "your query" });
9     console.log(results);
10   } catch (error) {
11     if (error instanceof YouError) {
12       console.error(`Search failed: ${error.message}`);
13       console.error(`Status code: ${error.statusCode}`);
14     } else {
15       console.error("An unexpected error occurred:", error);
16     }
17   }
18 }
19 
20 main();

Learn More

npm Package

Install and inspect the published TypeScript SDK package.

GitHub Repository

Read the source, generated model docs, and release history.

Web Search API Reference

Full Web Search API parameters and response schema.