> ## Documentation Index
> Fetch the complete documentation index at: https://help.decodo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> The official TypeScript SDK for the Decodo Web Scraping API, with strongly typed targets, IDE autocomplete, and sync, async, and batch scraping methods.

<Info>
  View the [TypeScript SDK GitHub repository](https://github.com/Decodo/sdk-ts) for the latest installation instructions, examples, and source code.
</Info>

Build strongly typed scraping workflows for search engines, eCommerce platforms, social media, AI tools, and more with the official Decodo TypeScript SDK for [Web Scraping API](https://decodo.com/scraping/web).

* Fully typed targets and parameters with IDE autocomplete
* Sync, async, and batch scraping methods
* Native `fetch` support; requires Node.js 18 or later
* Typed error hierarchy for safer integrations

## What is the Decodo TypeScript SDK?

The Decodo TypeScript SDK provides a typed interface for interacting with Decodo targets like Google, Amazon, TikTok, Reddit, YouTube, ChatGPT, Perplexity, and more. Instead of manually constructing HTTP requests and validating payloads, you work with fully typed methods and target-specific parameters directly in your editor.

## Why use the SDK?

* **Strong typing and autocomplete** – target parameters are fully typed for better editor support and fewer mistakes.
* **Unified scraping interface** – work with search engines, eCommerce platforms, social media, and AI tools through one SDK.
* **Async and batch workflows** – create scraping tasks, poll task status, and process batches at scale.
* **Typed errors** – handle authentication, validation, timeout, and rate-limit failures safely.
* **Minimal setup** – uses native `fetch`, no additional HTTP client required.

## Requirements

* Node.js 18 or later, for native `fetch`
* TypeScript 5.0 or later, recommended for best type inference

## Installation

```bash theme={null}
npm install --save @decodo/sdk-ts
```

## Quick start

Create a new project:

```bash theme={null}
mkdir scrape-with-decodo
cd scrape-with-decodo
npm init -y
npm install --save @decodo/sdk-ts
touch main.js
```

Get your Web Scraping API Basic Auth token from the [**Decodo dashboard**](https://dashboard.decodo.com/welcome). Keep it out of your source by storing it in an environment variable:

```text theme={null}
export DECODO_TOKEN=your_token
```

Then create `main.js` and initialize the client with the environment variable:

```typescript theme={null}
// main.js
import { DecodoClient, Target } from '@decodo/sdk-ts';

const client = new DecodoClient({
  webScrapingApi: {
    token: process.env.DECODO_TOKEN!,
  },
});

const result = await client.webScrapingApi.scrape({
  target: Target.GoogleSearch,
  query: 'coffee shops',
  geo: 'United States',
  parse: true,
});

console.log(JSON.stringify(result, null, 2));
```

Run the script:

```bash theme={null}
node main.js
```

## Configuration

```typescript theme={null}
const client = new DecodoClient({
  webScrapingApi: {
    token: '<token>',
  },
  timeoutMs: 120_000, // optional, request timeout in ms (default: 180000)
});
```

| Parameter   | Description                                          |
| ----------- | ---------------------------------------------------- |
| `token`     | Web Scraping API Basic Auth token from the dashboard |
| `timeoutMs` | Request timeout in milliseconds (default: 180000)    |

## Web Scraping API

Access the API via `client.webScrapingApi`. The examples below assume `Target` is already imported, along with `DecodoClient` where needed:

```typescript theme={null}
import { DecodoClient, Target } from '@decodo/sdk-ts';
```

### Sync scrape

Waits for the scraping result before returning:

```typescript theme={null}
const result = await client.webScrapingApi.scrape({
  target: Target.AmazonProduct,
  query: 'B09H74FXNW',
  parse: true,
});
```

### Async scrape

Creates a scraping task and returns immediately. Poll separately for task status and results:

```typescript theme={null}
const task = await client.webScrapingApi.scrapeAsync({
  target: Target.GoogleSearch,
  query: 'laptop reviews',
  parse: true,
});

const meta = await client.webScrapingApi.getStatus(task.id);
console.log(meta.status); // 'pending' | 'done' | 'faulted'

const results = await client.webScrapingApi.getResults(task.id);
```

### Batch scrape

Send multiple queries or URLs in a single request:

```typescript theme={null}
const batch = await client.webScrapingApi.scrapeBatch({
  target: Target.GoogleSearch,
  query: ['coffee', 'tea', 'juice'],
  parse: true,
});

const coffeeTaskId = batch.queries[0].id;
await client.webScrapingApi.getResults(coffeeTaskId);
```

## Supported targets

Each target accepts one primary input parameter (`url`, `query`, `product_id`, or `prompt`) together with optional configuration.

### Search engines

| Target                        | Description                       | Example                                                               |
| ----------------------------- | --------------------------------- | --------------------------------------------------------------------- |
| `Target.GoogleSearch`         | Google Search results for a query | `{ target: Target.GoogleSearch, query: "coffee shops" }`              |
| `Target.GoogleMaps`           | Google Maps search results        | `{ target: Target.GoogleMaps, query: "coffee shops brooklyn" }`       |
| `Target.GoogleShoppingSearch` | Google Shopping search results    | `{ target: Target.GoogleShoppingSearch, query: "laptop" }`            |
| `Target.GoogleSuggest`        | Google Autocomplete suggestions   | `{ target: Target.GoogleSuggest, query: "coffee" }`                   |
| `Target.GoogleLens`           | Google Lens reverse image search  | `{ target: Target.GoogleLens, query: "https://example.com/cat.jpg" }` |
| `Target.BingSearch`           | Bing Search results               | `{ target: Target.BingSearch, query: "electric vehicles" }`           |

### eCommerce

| Target                  | Description                           | Example                                                                |
| ----------------------- | ------------------------------------- | ---------------------------------------------------------------------- |
| `Target.AmazonProduct`  | Amazon product detail page by ASIN    | `{ target: Target.AmazonProduct, query: "B09H74FXNW" }`                |
| `Target.AmazonSearch`   | Amazon search results                 | `{ target: Target.AmazonSearch, query: "laptop" }`                     |
| `Target.AmazonPricing`  | Amazon pricing and offers             | `{ target: Target.AmazonPricing, query: "B09H74FXNW" }`                |
| `Target.WalmartProduct` | Walmart product page by product ID    | `{ target: Target.WalmartProduct, product_id: "15296401808" }`         |
| `Target.TargetProduct`  | Target.com product page by product ID | `{ target: Target.TargetProduct, product_id: "92186007" }`             |
| `Target.Ecommerce`      | Generic eCommerce page with parser    | `{ target: Target.Ecommerce, url: "https://example.com/product/123" }` |

### Social media

| Target                   | Description             | Example                                                                       |
| ------------------------ | ----------------------- | ----------------------------------------------------------------------------- |
| `Target.RedditPost`      | Reddit post by URL      | `{ target: Target.RedditPost, url: "https://reddit.com/r/nba/..." }`          |
| `Target.RedditSubreddit` | Reddit subreddit by URL | `{ target: Target.RedditSubreddit, url: "https://reddit.com/r/nba/" }`        |
| `Target.YoutubeVideo`    | YouTube video by ID     | `{ target: Target.YoutubeVideo, query: "dFu9aKJoqGg" }`                       |
| `Target.YoutubeSearch`   | YouTube search results  | `{ target: Target.YoutubeSearch, query: "ambient music" }`                    |
| `Target.TiktokPost`      | TikTok post by URL      | `{ target: Target.TiktokPost, url: "https://www.tiktok.com/@nba/video/..." }` |

### AI tools

| Target                | Description                      | Example                                                                        |
| --------------------- | -------------------------------- | ------------------------------------------------------------------------------ |
| `Target.Chatgpt`      | ChatGPT response for a prompt    | `{ target: Target.Chatgpt, prompt: "What are the top three dog breeds?" }`     |
| `Target.Perplexity`   | Perplexity response for a prompt | `{ target: Target.Perplexity, prompt: "What causes seasonal allergies?" }`     |
| `Target.Gemini`       | Gemini response for a prompt     | `{ target: Target.Gemini, prompt: "What are the top three dog breeds?" }`      |
| `Target.GoogleAiMode` | Google AI Mode response          | `{ target: Target.GoogleAiMode, query: "What are the top three dog breeds?" }` |

### Universal scraping

| Target             | Description                       | Example                                                                |
| ------------------ | --------------------------------- | ---------------------------------------------------------------------- |
| `Target.Universal` | Any URL via the universal scraper | `{ target: Target.Universal, url: "https://example.com" }`             |
| `Target.Google`    | Raw Google URL scraping           | `{ target: Target.Google, url: "https://google.com/search?q=laptop" }` |
| `Target.Amazon`    | Raw Amazon URL scraping           | `{ target: Target.Amazon, url: "https://amazon.com/dp/B09H74FXNW" }`   |

<Note>
  `Target.UniversalEcommerce` isn't included in the table because it doesn't accept a primary input parameter such as `url`, `query`, `product_id`, or `prompt`. It only accepts optional configuration fields such as `callback_url`.
</Note>

For the full target list and parameter details, see [**Target list**](/docs/web-scraping-api-targets) and [**Parameters**](/docs/web-scraping-api-parameters).

## Error handling

The SDK throws typed errors that map to API error codes:

```typescript theme={null}
import {
  DecodoError,
  AuthenticationError,
  RateLimitError,
  ValidationError,
  TimeoutError,
  Target,
} from '@decodo/sdk-ts';

try {
  await client.webScrapingApi.scrape({
    target: Target.GoogleSearch,
    query: 'test',
    parse: true,
  });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // 401/403 - bad credentials
  } else if (err instanceof RateLimitError) {
    // 429 - too many requests
  } else if (err instanceof ValidationError) {
    // 422 - invalid parameters
    console.log(err.errors);
  } else if (err instanceof TimeoutError) {
    // request timed out
  }
}
```

`AuthenticationError`, `RateLimitError`, and `ValidationError` extend `DecodoError`. `TimeoutError` sits outside the `DecodoError` hierarchy, so handle it separately.

***

## Related

* [**CLI**](/docs/cli) – Run Decodo scraping workflows from the command line.
* [**Python SDK**](/docs/python-sdk) – Integrate the Web Scraping API into Python projects.
* [**Go SDK**](/docs/go-sdk) – Integrate the Web Scraping API into Go projects.
* [**MCP Server**](/docs/mcp) – Connect AI agents and MCP-compatible tools to Decodo.
* [GitHub repository ](https://github.com/Decodo/sdk-ts)– View the TypeScript SDK source code, examples, and latest releases.

***

<Columns cols={2}>
  <Card title="Support" href="https://direct.lc.chat/12092754" cta="Let's chat!">
    Need help or just want to say hello? Our support is available 24/7. \
    You can also reach us anytime via email at [support@decodo.com](mailto:support@decodo.com).
  </Card>

  <Card title="Feedback" href="mailto:feedback@decodo.com" cta="Share feedback">
    Can't find what you're looking for? Request an article! \
    Have feedback? Share your thoughts on how we can improve.
  </Card>
</Columns>