TypeScript SDK

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.

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

Now, you can 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: "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?

Our search API offers several powerful 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 US about renewable energy from the past week limited to 10 results per source type (either general web, or news), you simply write the following:

1
import { You } from "@youdotcom-oss/sdk";
2
import { Freshness, Country } from "@youdotcom-oss/sdk/models";
3
4
const you = new You({
5
  apiKeyAuth: "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();

Its capabilities don’t end there. Learn more about the Search API in the Search API reference, and the TypeScript SDK by visiting the open source repository on GitHub.

Response structure

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

• results: Contains search results.

  • web: An array of web result objects. Each object may include:
    • url: The URL of the web page.
    • title: The title of the web page.
    • description: A brief description of the web page.
    • snippets: An array of relevant text snippets from the page.
    • thumbnailUrl: (Optional) URL to a thumbnail image representing the page.
    • pageAge: (Optional) Timestamp or date indicating the age of the page.
    • faviconUrl: (Optional) URL to the favicon of the website.
  • news: An array of news result objects. Each object may include:
    • url: The URL of the news article.
    • title: The title of the news article.
    • description: A brief description of the news article.
    • thumbnailUrl: (Optional) URL to a thumbnail image representing the article.
    • pageAge: (Optional) Timestamp or date indicating the age of the article.

• metadata: Information about the search query and results.

  • query: The search query used to retrieve the results.
  • searchUuid: Unique UUID identifying the search request.
  • latency: The latency (in seconds) of the search call.

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: "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

For more information on how to use the SDK, refer to the official NPM page or the open source repository on GitHub.