# TypeScript SDK

We offer a TypeScript SDK to make interacting with our APIs simple and predictable. It is available on NPM [here](https://www.npmjs.com/package/@youdotcom-oss/sdk).
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](https://you.com/platform/).

#### Install the SDK

```bash
npm add @youdotcom-oss/sdk
```

#### Run a search

Now, you can perform a simple search to retrieve results from general web and news sources.

```typescript
import { You } from "@youdotcom-oss/sdk";

// Initialize the SDK with your API key
const you = new You({
  apiKeyAuth: "YOUR_API_KEY", 
});

async function main() {
  // Perform a search
  const results = await you.search({
    query: "latest AI developments",
  });

  // Access the results
  console.log(results);
}

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:

```typescript
import { You } from "@youdotcom-oss/sdk";
import { Freshness, Country } from "@youdotcom-oss/sdk/models";

const you = new You({
  apiKeyAuth: "YOUR_API_KEY",
});

async function main() {
  const results = await you.search({
    query: "renewable energy",
    count: 10,
    freshness: Freshness.Week,
    country: Country.Us,
  });

  console.log(results);
}

main();
```

Its capabilities don't end there. Learn more about the Search API in the [Search API reference](/api-reference/search/v1-search), and the TypeScript SDK by visiting the open source repository on [GitHub](https://github.com/youdotcom-oss/youdotcom-typescript-sdk/).

## Response structure

The Search API returns a `SearchResponse` object (see [documentation](https://github.com/youdotcom-oss/youdotcom-typescript-sdk/blob/main/docs/models/operations/searchresponse.md)):

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

```typescript
import { You } from "@youdotcom-oss/sdk";
import { YouError } from "@youdotcom-oss/sdk/models/errors";

const you = new You({ apiKeyAuth: "YOUR_API_KEY" });

async function main() {
  try {
    const results = await you.search({ query: "your query" });
    console.log(results);
  } catch (error) {
    if (error instanceof YouError) {
      console.error(`Search failed: ${error.message}`);
      console.error(`Status code: ${error.statusCode}`);
    } else {
      console.error("An unexpected error occurred:", error);
    }
  }
}

main();
```

## Learn more

For more information on how to use the SDK, refer to the official [NPM page](https://www.npmjs.com/package/@youdotcom-oss/sdk) or the open source repository on [GitHub](https://github.com/youdotcom-oss/youdotcom-typescript-sdk).