Plugins

Plugins let you extract structured data from supported platforms (Amazon and the full Google Scraper API suite, including Search, Maps, Shopping, Flights, Hotels, News, Trends, and AI Mode) 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

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

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

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

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
`google/search`	Google	Structured JSON	SERP results
`google/search/ai-mode`	Google	Structured JSON	AI Mode response
`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/shopping`	Google	Structured JSON	Shopping product results
`google/flights`	Google	Structured JSON	Flights itineraries + price insights
`google/hotels`	Google	Structured JSON	Hotels listings
`google/news`	Google	Structured JSON	News articles, topics, clusters
`google/trends`	Google	Structured JSON	Trends data
`walmart/store`	Walmart	Raw HTML	Store-scoped request
`lowes/store`	Lowes	Raw HTML	Store-scoped request

google/search/ai-overview is not available as an async plugin. It requires a session_key from a prior google/search call (90-second TTL) and must be called directly on the gateway.

Amazon Plugins

`amazon/pdp` - Product Detail Page

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

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
`geocode`	yes	Country code (`us`, `gb`, `de`, etc.)
`zipcode`	yes	Zip/postal code
`super`	no	`true` for premium proxies
`include_html`	no	`true` to include raw HTML in response

`amazon/search` - Search Results

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
`geocode`	yes	Country code
`zipcode`	yes	Zip/postal code
`page`	no	Page number (default `1`)
`include_html`	no	`true` to include raw HTML

`amazon/offer-listing` - All Seller Offers

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" }
      ]
    }
  }'

Google Plugins

All Google plugins return structured JSON and use premium proxies internally. No super flag needed.

`google/search` - SERP Results

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

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" }
      ]
    }
  }'

`google/maps/search` - Maps Places List

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

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

Place endpoint does not accept data_id. Use place_id or data_cid.

`google/maps/reviews` - Maps Reviews

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/shopping` - Shopping Products

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

`google/flights` - Flights Itineraries

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

Multi-city (type=3), max_price, max_duration, and bags are not yet supported and return 400 if passed.

`google/hotels` - Hotels Listings

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

Occupancy parameters (adults, children, children ages) are not supported. Results always reflect 2 adults, 0 children.

`google/news` - News Articles

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

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`

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", ... }`	That task only

Setting both returns 400. Top-level GeoCode only applies to Amazon, Walmart, and Lowes plugins. Google plugins use per-param gl or geo. Top-level GeoCode has no effect on them.

Webhooks

Plugin jobs support webhooks. Each completed task triggers a webhook delivery:

{
  "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`	`geoCode must not be specified both at top level and in plugin params`	GeoCode conflict
`400`	`plugin params exceed limit of 1000 (got N)`	Too many param entries