# Plugins

> Source: https://scrape.do/documentation/async-api/plugins/

Use structured scraping plugins with the Async API for bulk data extraction

Plugins let you extract structured data from supported platforms using the Async API. Instead of sending raw URLs, you specify a plugin key and parameters for each task; the API handles session management, geo-targeting, and response parsing automatically.

---

## Request Structure

```bash
POST https://q.scrape.do/api/v1/jobs
X-Token: YOUR_TOKEN
Content-Type: application/json
```

```json
{
  "Plugin": {
    "Key": "<plugin_key>",
    "Params": [
      { "param1": "value1", "param2": "value2" },
      { "param1": "value3", "param2": "value4" }
    ]
  },
  "GeoCode": "us",
  "WebhookURL": "https://example.com/webhook",
  "WebhookHeaders": { "Authorization": "Bearer your-token" }
}
```

> [!NOTE]
> `Targets` and `Plugin` are mutually exclusive. Using both returns `400 Bad Request`.
> Each entry in `Params` becomes one task in the job. Maximum **1000 params per job**.

---

## Supported Plugins

Use the page sidebar to jump to a specific plugin's section.

| Key | Platform | Output | Description |
|-----|----------|--------|-------------|
| `amazon/pdp` | Amazon | Structured JSON | Product Detail Page |
| `amazon/search` | Amazon | Structured JSON | Search results |
| `amazon/offer-listing` | Amazon | Structured JSON | All seller offers |
| `walmart/store` | Walmart | HTML / JSON | Store-scoped request |
| `lowes/store` | Lowes | HTML / JSON | Store-scoped request |
| `google/search` | Google | Structured JSON | SERP results |
| `google/search/ai-mode` | Google | Structured JSON | AI Mode (`udm=50`) response |
| `google/search/ai-overview` | Google | Structured JSON | AI Overview follow-up |
| `google/shopping` | Google | Structured JSON | Shopping product results |
| `google/shopping/product` | Google | Structured JSON | Full product page (first ~5 sellers) |
| `google/shopping/product/stores` | Google | Structured JSON | Next batch of sellers (continuation) |
| `google/maps/search` | Google | Structured JSON | Maps places list |
| `google/maps/place` | Google | Structured JSON | Maps place details |
| `google/maps/reviews` | Google | Structured JSON | Paginated place reviews |
| `google/hotels` | Google | Structured JSON | Hotels listings |
| `google/hotels/detail` | Google | Structured JSON | Per-vendor offer shelf for one property |
| `google/flights` | Google | Structured JSON | Flights itineraries + price insights |
| `google/news` | Google | Structured JSON | News articles, topics, clusters |
| `google/trends` | Google | Structured JSON | Trends data for a keyword |
| `google/trending` | Google | Structured JSON | Currently trending searches |
| `google/youtube` | Google | Structured JSON | YouTube search results |
| `google/play-store` | Google | Structured JSON | Play Store app search |
| `google/play-store/product` | Google | Structured JSON | Play Store app detail page |
| `google/play-store/reviews` | Google | Structured JSON | Play Store app reviews |
| `chatgpt/chat` | OpenAI | Structured JSON | ChatGPT reply for a prompt |

---

## Amazon Plugins

### `amazon/pdp` - Product Detail Page

Returns structured JSON with price, images, rating, buy box, reviews, BSR, and more.

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "amazon/pdp",
      "Params": [
        { "asin": "B0CQMTCR9T", "zipcode": "32095", "geocode": "us" },
        { "asin": "B0DFK5Y3PQ", "zipcode": "10001", "geocode": "us" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `asin` | yes | Amazon ASIN (10 chars) |
| `geocode` | yes | Marketplace country code (`us`, `gb`, `de`, etc.) |
| `zipcode` *or* `countryName` | yes | Localizes price and availability. Pass exactly one. `zipcode` for marketplaces with ZIP-level delivery (`10001` for `us`, `EC1A 1BB` for `gb`, …); `countryName` otherwise. |
| `language` | no | Display language ISO-2 (`EN`, `DE`, `FR`, …). Must be supported for the chosen marketplace. |
| `super` | no | `true` for premium proxies |
| `include_html` | no | `true` to include raw HTML in response |

---

### `amazon/search` - Search Results

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "amazon/search",
      "Params": [
        { "keyword": "wireless earbuds", "zipcode": "32095", "geocode": "us" },
        { "keyword": "wireless earbuds", "zipcode": "32095", "geocode": "us", "page": 2 }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `keyword` | yes | Search query (URL-encoded) |
| `geocode` | yes | Marketplace country code |
| `zipcode` *or* `countryName` | yes | Localizes price and availability. Pass exactly one. |
| `page` | no | Page number ≥1 (default `1`) |
| `language` | no | Display language ISO-2. Must be supported for the chosen marketplace. |
| `super` | no | `true` for premium proxies |
| `include_html` | no | `true` to include raw HTML |

---

### `amazon/offer-listing` - All Seller Offers

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "amazon/offer-listing",
      "Params": [
        { "asin": "B0CQMTCR9T", "zipcode": "32095", "geocode": "us" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `asin` | yes | Amazon ASIN |
| `geocode` | yes | Marketplace country code |
| `zipcode` *or* `countryName` | yes | Localizes price and availability. Pass exactly one. |
| `language` | no | Display language ISO-2 |
| `super` | no | `true` for premium proxies |
| `include_html` | no | `true` to include raw HTML |

---

## Walmart & Lowes Plugins

### `walmart/store` - Store-Scoped Request

Fetches a Walmart URL with store-specific session cookies. Raw HTML response.

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "walmart/store",
      "Params": [
        { "url": "https://www.walmart.com/ip/123456", "zipcode": "72712", "storeid": 100 }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `url` | yes | Full Walmart URL (must be `walmart` domain) |
| `zipcode` | conditional | Required with `storeid`, or omit both for a random store |
| `storeid` | conditional | Required with `zipcode`, or omit both for a random store |
| `disableretry` | no | `true` to disable retry logic |
| `transparentresponse` | no | `true` to return raw response |
| `timeout` | no | Custom timeout in ms |

---

### `lowes/store` - Store-Scoped Request

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "lowes/store",
      "Params": [
        { "url": "https://www.lowes.com/pd/item/123", "zipcode": "28202", "storeid": "0595" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `url` | yes | Full Lowes URL on `lowes.com`. Must match an accepted path pattern (see below). |
| `zipcode` | yes | Numeric zip code (digits only) |
| `storeid` | yes | Numeric Lowes store ID (digits only) |
| `disableretry` | no | `true` to disable retry logic |
| `transparentresponse` | no | `true` to return raw response on timeout (instead of `502`) |
| `timeout` | no | Per-request timeout in ms (default: system max) |

**Accepted URL patterns:**

| Pattern | Example |
|---------|---------|
| `/pd/<slug>/<itemId>` | `https://www.lowes.com/pd/Disney-Airblown-Holiday-Stitch/5016066683` |
| `/wpd/<itemId>/productdetail/<storeId>/<auth>/<zipCode>` | `https://www.lowes.com/wpd/1000002288/productdetail/0208/Guest/92253` |
| `/<2-letter-state>/<category>/<id>/products` | `https://www.lowes.com/pl/power-tools/4294607842/products` |
| `/search…` | `https://www.lowes.com/search?searchTerm=socket+holder` |
| `/collections/api/items/<groupId>/COLL_MANDATORY/<storeId>/<auth>/<zipCode>` | (Collections API) |
| `/purchase/api/cart/cartitems` | Cart-add API endpoint |

URLs that don't match return `400 valid lowes url expected`. For `/wpd/…` URLs, the `<storeId>` and `<zipCode>` path segments must match the `storeid` and `zipcode` params exactly, otherwise the task fails with `400 valid lowes url expected` and the message `Please ensure that url match with the provided zipcode and storeid parameters.`

**Response shape depends on the URL pattern.** `/pd/…` and `/search…` return rendered HTML, while `/wpd/…` and `/pl/…/products` return JSON from Lowes' own product APIs (`productDetails` and a paginated item list respectively).

> [!WARNING]
> Validation happens **per task, not at job creation**. A job with an invalid URL, a missing `zipcode`, or a missing `storeid` is still accepted with `200 Job created successfully`; the individual task then finishes with `Status: "error"` and a `400` body such as `{"error":"zipcode is required"}`. Always check task status, not just job status.

> [!NOTE]
> Async plugin jobs always issue `GET`. The gateway's `POST /plugin/lowes/store` variant (cart-add and similar mutating endpoints) is not yet available through the Async API.

---

## Google Plugins

All Google plugins return structured JSON and use premium proxies internally — no `super` flag needed.

### `google/search` - SERP Results

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/search",
      "Params": [
        { "q": "web scraping api", "gl": "us", "hl": "en" },
        { "q": "web scraping api", "gl": "gb", "hl": "en", "start": 10 }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `q` | yes | Search query |
| `gl` | no | Country code (default `us`) |
| `hl` | no | Language code (default `en`) |
| `google_domain` | no | Google domain (default `google.com`) |
| `device` | no | `desktop` or `mobile` |
| `start` | no | Result offset (default `0`) |
| `include_html` | no | `true` to include raw HTML |

---

### `google/search/ai-mode` - AI Mode

Returns Google's AI Mode (`udm=50`) response — ordered text blocks, source references, and shopping cards.

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/search/ai-mode",
      "Params": [
        { "q": "best web scraping tools 2025", "gl": "us" },
        { "q": "how does web scraping work", "gl": "gb", "hl": "en" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `q` | yes | Search query |
| `gl` / `hl` / `google_domain` | no | Standard localization |
| `location` / `uule` | no | Location targeting (UULE overrides `location`) |
| `device` | no | `desktop` or `mobile` |
| `safe` | no | `active` to enable SafeSearch |
| `include_html` | no | `true` to include raw AI Mode HTML |

---

### `google/search/ai-overview` - AI Overview Follow-up

Returns the AI Overview block when Google renders one for a query. The plugin handles both fetch hops internally — pass a query, get parsed content back.

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/search/ai-overview",
      "Params": [
        { "q": "best running shoes for flat feet", "gl": "us" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `q` | yes | Search query |
| `gl` / `hl` / `google_domain` | no | Standard localization |
| `location` / `uule` | no | Location targeting (UULE overrides `location`) |
| `device` | no | `desktop` or `mobile` |
| `safe` | no | `active` to enable SafeSearch |

> [!NOTE]
> AI Overview is A/B-tested and not every query qualifies. Requests for queries Google does not return an AI Overview for fail with an explicit error and are **not charged**.

---

### `google/shopping` - Shopping Products

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/shopping",
      "Params": [
        { "q": "laptop", "min_price": 500, "max_price": 1500 },
        { "q": "wireless headphones", "sort_by": 1, "free_shipping": true }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `q` | yes | Search query |
| `min_price` / `max_price` | no | Price range filter (integer) |
| `sort_by` | no | `0` relevance, `1` price asc, `2` price desc |
| `free_shipping` / `on_sale` | no | Boolean filters |
| `shoprs` | no | Opaque filter token from a previous response |
| `device` | no | `desktop` or `mobile` |
| `start` | no | Pagination offset |
| `hl` / `gl` / `google_domain` / `location` / `uule` | no | Standard localization |

Each result carries a `catalog_id` (durable, persistable) and an `immersive_product_page_token` (short-lived) — pass either to `google/shopping/product` to expand a product.

---

### `google/shopping/product` - Product Page

Returns the full product page: title, brand, gallery, description, ratings, the first ~5 sellers, and a `next_page_token` for paginating the rest.

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/shopping/product",
      "Params": [
        { "catalog_id": "12153035126592663857", "q": "PodTrak P8 ZP8", "gl": "us" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `catalog_id` | * | Region-scoped, durable. Pair with `q` to look up a product. |
| `immersive_product_page_token` (alias `page_token`) | * | Short-lived (~hours). Returned by `google/shopping`. |
| `product_id` | * | Stable lightweight ID. Forces compact mode (title + sellers table). |
| `q` | conditional | Required when using `catalog_id` |
| `sort_by` | no | Seller sort: `base_price`, `total_price`, `promotion`, `seller_rating`. Always forces compact mode regardless of which identifier you pass. |
| `device` | no | `desktop` (default), `mobile`, `tablet` |
| `hl` / `gl` / `google_domain` / `location` / `uule` | no | Standard localization |

> [!NOTE]
> One of `catalog_id`, `immersive_product_page_token`, or `product_id` is required. When multiple are supplied, precedence is `catalog_id` > `immersive_product_page_token` > `product_id`. Catalog IDs are region-specific — if you need US, DE, and FR sellers for the same product, search once per region and persist each `catalog_id`.

---

### `google/shopping/product/stores` - More Sellers

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/shopping/product/stores",
      "Params": [
        { "catalog_id": "17422476796203286923", "next_page_token": "eyJ2Ijoic3RvcmVzLTEi..." }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `catalog_id` | yes | Same catalog ID used to fetch the product page. Must match the `catalog_id` encoded inside the token — mismatch returns `400`. |
| `next_page_token` | yes | `next_page_token` from the previous step's response |

> [!NOTE]
> The locale (`q`, `gl`, `hl`) used by the upstream call is carried **inside** `next_page_token`. Any `hl` / `gl` values you pass here are **ignored** in favor of the token-embedded ones so the response stays deterministic across replays.

---

### `google/maps/search` - Maps Places List

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/maps/search",
      "Params": [
        { "q": "pizza new york", "ll": "@40.7128,-74.0060,13z" },
        { "q": "hotels chicago", "start": 20, "hl": "en", "gl": "us" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `q` | yes | Search query |
| `ll` | no | Lat/lng/zoom pin: `@lat,lng,zoomz` |
| `start` | no | Page offset (multiples of 20) |
| `hl` / `gl` / `google_domain` | no | Standard localization |

---

### `google/maps/place` - Maps Place Details

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/maps/place",
      "Params": [
        { "place_id": "ChIJLSsVbGBZwokRR0LlGBSvMOI" },
        { "data_cid": "16313085445244584615" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `place_id` | * | Google Place ID (`ChIJ...`). One of `place_id` or `data_cid` is required |
| `data_cid` | * | Numeric CID |
| `hl` / `gl` / `google_domain` | no | Standard localization |

> [!NOTE]
> Place endpoint **does not** accept `data_id`. Use `place_id` or `data_cid`.

---

### `google/maps/reviews` - Maps Reviews

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/maps/reviews",
      "Params": [
        { "data_id": "0x864c28f004653715:0x57c504dbf0bc93a0", "num": 20 },
        { "data_id": "0x864c28f004653715:0x57c504dbf0bc93a0", "sort_by": "newestFirst" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `data_id` | * | Place ID in `0xHEX:0xHEX` format. One of `data_id` or `place_id` is required |
| `place_id` | * | Place ID in `ChIJ...` format |
| `num` | no | Reviews per page (1–20, default `10`) |
| `sort_by` | no | `newestFirst`, `ratingHigh`, or `ratingLow` |
| `topic_id` / `query` | no | Filter by topic or keyword (mutually exclusive) |
| `next_page_token` | no | Cursor from previous response's `pagination.next_page_token` |

---

### `google/hotels` - Hotels Listings

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/hotels",
      "Params": [
        { "q": "Bali hotels", "check_in_date": "2026-05-01", "check_out_date": "2026-05-03" },
        { "q": "Paris hotels", "check_in_date": "2026-05-01", "check_out_date": "2026-05-03", "hotel_class": "4,5", "free_cancellation": true, "currency": "EUR" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `q` | yes | Hotel search query (use simple `"<City> hotels"` form) |
| `check_in_date` / `check_out_date` | yes | `YYYY-MM-DD` |
| `sort_by` | no | `3` price, `8` rating, `13` reviewed |
| `min_price` / `max_price` | no | Price filter (integer) |
| `rating` | no | `7` (3.5+), `8` (4.0+), `9` (4.5+) |
| `hotel_class` | no | Comma-separated star ratings 2–5 |
| `brands` / `amenities` / `property_types` | no | Comma-separated codes |
| `free_cancellation` / `eco_certified` / `special_offers` | no | Boolean filters |
| `next_page_token` | no | Pagination cursor |
| `hl` / `gl` / `currency` | no | Standard localization |

> [!NOTE]
> Occupancy parameters (adults, children, children ages) are **not supported**. Results always reflect 2 adults, 0 children.

Each property in the response carries a `detail_token` — pass it to `google/hotels/detail` to fetch the live per-vendor offer shelf.

---

### `google/hotels/detail` - Per-Vendor Offer Shelf

Returns each booking source's `rate_per_night`, `total_rate`, and quoted occupancy for a single property — sponsored ("Featured options") and organic ("All options") entries unified into one ranked list.

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/hotels/detail",
      "Params": [
        { "detail_token": "<token>", "check_in_date": "2026-05-15", "check_out_date": "2026-05-17", "currency": "USD" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `detail_token` | yes | The `detail_token` from a `google/hotels` listing response |
| `check_in_date` / `check_out_date` | yes | `YYYY-MM-DD` |
| `currency` | no | ISO 4217 (default `USD`) |
| `hl` / `gl` | no | Standard localization |

---

### `google/flights` - Flights Itineraries

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/flights",
      "Params": [
        { "departure_id": "JFK", "arrival_id": "LAX", "outbound_date": "2026-06-15" },
        { "departure_id": "IST", "arrival_id": "LHR", "outbound_date": "2026-07-01", "return_date": "2026-07-15", "travel_class": 3, "currency": "EUR" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `departure_id` / `arrival_id` | yes | IATA codes (comma-separated for multi-airport) |
| `outbound_date` | yes | `YYYY-MM-DD` |
| `return_date` | no | `YYYY-MM-DD` for round trip |
| `type` | no | `1` round trip, `2` one way (auto-inferred) |
| `adults` / `children` / `infants_in_seat` / `infants_on_lap` | no | Passenger counts |
| `travel_class` | no | `1` economy, `2` premium economy, `3` business, `4` first |
| `stops` | no | `0` any, `1` nonstop, `2` ≤1 stop, `3` ≤2 stops |
| `sort_by` | no | `1`–`6` (top, price, dep, arr, duration, emissions) |
| `include_airlines` / `exclude_airlines` | no | Comma-separated IATA codes (mutually exclusive) |
| `hl` / `gl` / `currency` | no | Standard localization |

> [!WARNING]
> Multi-city (`type=3`), `max_price`, `max_duration`, and `bags` are not yet supported and return `400` if passed.

---

### `google/news` - News Articles

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/news",
      "Params": [
        { "q": "openai", "so": "1" },
        { "topic_token": "CAAqJggKIiBDQkFTRWdvSUwy..." },
        { "kgmid": "/m/02_286" }
      ]
    }
  }'
```

Pass **exactly one** driver per task:

| Driver | Fetches |
|--------|---------|
| `q` | Keyword search |
| `topic_token` | Topic stream |
| `section_token` | Section within a topic |
| `story_token` | Full-coverage story page |
| `publication_token` | Publisher feed |
| `kgmid` | Knowledge Graph entity (e.g., `/m/02_286` = New York City) |

Optional: `so` (`0` relevance, `1` date; search mode only), `hl`, `gl`.

---

### `google/trends` - Trends Data

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/trends",
      "Params": [
        { "q": "bitcoin", "geo": "US" },
        { "q": "ethereum", "geo": "US", "data_type": "RELATED_QUERIES" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `q` | yes | Search keyword |
| `geo` | no | Location code (e.g., `US`, `GB`, `US-CA`) |
| `hl` | no | Language code (default `en`) |
| `date` | no | Time range (default `today 12-m`) |
| `data_type` | no | Widget filter: `TIMESERIES`, `GEO_MAP_0`, `RELATED_QUERIES`, `RELATED_TOPICS` |
| `cat` | no | Category ID |
| `gprop` | no | Google property: web, `images`, `news`, `youtube`, `froogle` |

---

### `google/trending` - Currently Trending Searches

Returns currently trending search topics from Google Trends — the same data shown on [trends.google.com/trending](https://trends.google.com/trending).

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/trending",
      "Params": [
        { "geo": "US" },
        { "geo": "GB", "cat": 17, "hours": 48 }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `geo` | yes (or set top-level `GeoCode`) | Country code (e.g., `US`, `GB`) |
| `hours` | no | Time window: `4`, `24` (default), `48`, `168` |
| `cat` | no | Category ID (`0` all, `17` sports, `18` technology, …) |
| `sort` | no | `relevance` (default), `search_volume`, `recency`, `title` |
| `status` | no | `all` (default) or `active` |
| `hl` | no | Language code (default `en`) |

---

### `google/youtube` - YouTube Search

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/youtube",
      "Params": [
        { "search_query": "best laptop 2025" },
        { "search_query": "tech reviewer", "sp": "EgIQAg==" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `search_query` (alias `q`) | yes | Search terms |
| `sp` | no | YouTube's opaque filter/sort token (also used for pagination — extract from `pagination.next`) |
| `device` | no | `desktop` (default) or `mobile` |
| `hl` / `gl` | no | Standard localization |

---

### `google/play-store` - App Search

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/play-store",
      "Params": [
        { "q": "weather" },
        { "chart": "topselling_free" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `q` / `apps_category` / `chart` | yes | Pass at least one. `apps_category` accepts `ART_AND_DESIGN`, `MEDICAL`, `GAME_PUZZLE`, etc. `chart` accepts `topselling_free`, `topselling_paid`, `topgrossing`. |
| `num` | no | Results per page (1–100, default `20`) |
| `next_page_token` | no | Pagination token from a previous response |
| `store_device` | no | `phone`, `tablet`, `tv`, `chromebook`, `watch`, `car` |
| `age` | no | Age filter (only with `apps_category=FAMILY`) |
| `hl` / `gl` | no | Standard localization |

---

### `google/play-store/product` - App Detail

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/play-store/product",
      "Params": [
        { "product_id": "com.discord" },
        { "product_id": "com.whatsapp" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `product_id` | yes | App package identifier (e.g., `com.discord`) |
| `hl` / `gl` | no | Standard localization |

---

### `google/play-store/reviews` - App Reviews

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "google/play-store/reviews",
      "Params": [
        { "product_id": "com.tapblaze.coffeebusiness" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `product_id` | yes | App package identifier |
| `sort_by` | no | `1` most relevant (default; only supported value at this time) |
| `next_page_token` | no | Pagination token from a previous response |
| `hl` / `gl` | no | Standard localization |

---

## ChatGPT Plugin

### `chatgpt/chat` - ChatGPT Reply

Sends a prompt to ChatGPT and returns the assembled reply as JSON. No browser automation or session management on your side — pass a prompt, get a structured response.

```bash
curl -X POST "https://q.scrape.do/api/v1/jobs" \
  --header "X-Token: YOUR_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "Plugin": {
      "Key": "chatgpt/chat",
      "Params": [
        { "q": "Explain quantum entanglement in one sentence" },
        { "q": "Was sind die wichtigsten Nachrichten heute", "geoCode": "de" }
      ]
    }
  }'
```

| Param | Required | Description |
|-------|----------|-------------|
| `q` | yes | Prompt text (max **1024 characters**; each call is standalone — no conversation continuity) |
| `model` | no | Model selector (`auto` default; e.g., `gpt-5`, `gpt-4o`). Unknown values fall back to `auto`. |
| `geoCode` | no | ISO-3166-1 alpha-2 country (case-insensitive). Sets reply language: `us` (English), `de`, `tr`, `jp`, … |
| `raw_sse` | no | `1` to include the raw upstream stream body alongside the assembled response. Alias: `include_raw=1`. |

---

## GeoCode Behavior

`GeoCode` can be set at two levels:

| Level | Example | Applies to |
|-------|---------|-----------|
| Top-level | `"GeoCode": "us"` | All tasks in the job |
| Per-param | `{ "geocode": "us", ... }`, `{ "gl": "us", ... }`, `{ "country": "sg", ... }`, etc. | That task only |

Top-level `GeoCode` is translated into the per-task query parameter the target plugin expects, with per-plugin value normalization:

| Plugin family | Injected param | Value normalization |
|---------------|----------------|---------------------|
| `amazon/*`, `walmart/*`, `lowes/*` | `geocode` | verbatim |
| `google/trends`, `google/trending` | `geo` | uppercased |
| All other `google/*` (search, shopping, maps, hotels, flights, news, youtube, play-store, …) | `gl` | lowercased |
| `chatgpt/chat` | `geoCode` | verbatim (gateway is case-insensitive) |

Specifying `GeoCode` at both levels (when the per-param key matches what the plugin expects, case-insensitive) returns `400`:

```
geoCode must not be specified both at top level and in plugin params
```

---

## Webhooks

Plugin jobs share the same webhook contract as regular Async API jobs — set `WebhookURL` (and optionally `WebhookHeaders`) on the job, and each completed task triggers a delivery with the task result. Retry policy, signature header, and domain blacklist behavior are identical. See [Create Job](/documentation/async-api/create-job) for the full payload shape and delivery semantics.

```json
{
  "Plugin": { "Key": "amazon/pdp", "Params": [...] },
  "WebhookURL": "https://example.com/webhook",
  "WebhookHeaders": { "Authorization": "Bearer your-token" }
}
```

---

## Error Codes

| Status | Message | Cause |
|--------|---------|-------|
| `400` | `plugin key is required` | `Plugin.Key` is empty |
| `400` | `unsupported plugin key: <key>` | Unknown plugin key |
| `400` | `plugin params are required` | `Plugin.Params` is empty |
| `400` | `targets cannot be used together with plugin` | Both `Targets` and `Plugin` provided |
| `400` | `top-level GeoCode is not supported for plugin <key> (set geo per-param if the plugin needs it)` | Plugin has no geo parameter |
| `400` | `geoCode must not be specified both at top level and in plugin params (conflicts with <param> for <key>)` | GeoCode conflict (top-level + per-param) |
| `400` | `plugin params exceed limit of 1000 (got N)` | Too many param entries |