Plugins
View as MarkdownUse 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
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" }
]
},
"GeoCode": "us",
"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.
Param Values
Each key in a Params entry is sent to the plugin as one query parameter.
| Value type | How it is sent |
|---|---|
| String | As-is |
| Number | Exact text as written (2619533011 stays 2619533011, never 2.619533011e+09) |
| Boolean | true / false |
null | Treated as "not set"; the param is left out |
| Array / object | Rejected with 400. Send lists as a comma-separated string, e.g. "hotel_class": "4,5" |
- Send ZIP codes and store IDs with leading zeros as strings (
"02134","0595"). As a JSON number they lose the zero. token,asyncandproxy_keyare reserved (in any casing) and rejected with400. The API sets them on every request, and the job's token is always the one billed.- Two keys in one entry that differ only in case (
hlandHL) are rejected with400. Use the lowercase form documented below; some plugins (google/lens) read keys case-sensitively.
HTTP Method
Plugin jobs use GET by default. Only lowes/store also accepts "Method": "POST"; every other method/key combination returns 400 at job creation. The job-level Body is sent with every task in the 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 |
amazon/deals | Amazon | Structured JSON | Discounted product grid |
amazon/bestsellers | Amazon | Structured JSON | Best Sellers / New Releases chart |
amazon/seller | Amazon | Structured JSON | Seller profile |
amazon | Amazon | HTML | Raw page fetched for a ZIP code |
walmart/store | Walmart | HTML / JSON | Store-scoped request |
walmart/search | Walmart | Structured JSON | Search results |
walmart/product | Walmart | Structured JSON | Product detail |
samsclub/store | Sam's Club | HTML / JSON | Club-scoped request |
lowes/store | Lowes | HTML / JSON | Store-scoped request |
homedepot/product | Home Depot | HTML / JSON | Store-scoped product request |
homedepot/stores | Home Depot | Structured JSON | Store locator |
google/search | Structured JSON | SERP results | |
google/search/ai-mode | Structured JSON | AI Mode (udm=50) response | |
google/shopping | Structured JSON | Shopping product results | |
google/shopping/product | Structured JSON | Full product page and sellers | |
google/shopping/product/stores | Structured JSON | Next batch of sellers (continuation) | |
google/maps/search | Structured JSON | Maps places list | |
google/maps/place | Structured JSON | Maps place details | |
google/maps/reviews | Structured JSON | Paginated place reviews | |
google/hotels | Structured JSON | Hotels listings | |
google/hotels/detail | Structured JSON | Per-vendor offer shelf for one property | |
google/flights | Structured JSON | Flights itineraries + price insights | |
google/news | Structured JSON | News articles, topics, clusters | |
google/trends | Structured JSON | Trends data for a keyword | |
google/trending | Structured JSON | Currently trending searches | |
google/youtube | Structured JSON | YouTube search results | |
google/youtube/video | Structured JSON | YouTube video detail | |
google/lens | Structured JSON | Image search | |
google/food | Structured JSON | Restaurant pickup / delivery providers | |
google/play-store | Structured JSON | Play Store app search | |
google/play-store/product | Structured JSON | Play Store app detail page | |
google/play-store/reviews | Structured JSON | Play Store app reviews | |
chatgpt/chat | OpenAI | Structured JSON | ChatGPT reply for a prompt |
chatgpt/v2/chat | OpenAI | Structured JSON | ChatGPT reply (ads-capable route) |
gemini/chat | Structured JSON | Gemini reply for a prompt | |
naver/ai-search | Naver | Structured JSON | Naver AI search answer |
waze/alerts | Waze | Structured JSON | Traffic alerts in a bounding box |
carrefour/search | Carrefour | Structured JSON | Search results |
carrefour/product | Carrefour | Structured JSON | Product detail |
carrefour/rapid/search | Carrefour | Structured JSON | Search results (rapid delivery catalogue) |
carrefour/rapid/product | Carrefour | Structured JSON | Product detail (rapid delivery catalogue) |
shein | Shein | HTML | Product page |
trip/search | Trip.com | Structured JSON | Flight search |
trip/detail | Trip.com | Structured JSON | Fare detail |
google/search/ai-overview is not available as an Async API plugin: it needs a short-lived session_key from a previous google/search call. To get a deferred AI Overview in an async job, set await_ai_overview=true on google/search instead.
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 (10 chars) |
geocode (alias country) | yes | Marketplace country code (us, gb, de, etc.) |
zipcode or countryName | no | Localizes price and availability to a delivery location. Pass at most one. zipcode for marketplaces with ZIP-level delivery (10001 for us, EC1A 1BB for gb, …); countryName otherwise. Validated only when set. |
language | no | Display language ISO-2 (EN, DE, FR, …). Must be supported for the chosen marketplace. |
currency | no | ISO-4217 display currency |
device | no | desktop (default) or mobile |
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 | Marketplace country code |
zipcode or countryName | no | Localizes price and availability. Pass at most one. Validated only when set. |
page | no | Page number ≥1 (default 1) |
node | no | Category node ID (string or integer) |
low_price / high_price | no | Price bounds |
s / rh / i | no | Raw Amazon sort key, refinement string and search index (department) |
field-keywords | no | Raw Amazon keyword field |
seller | no | Restrict results to one seller ID |
language | no | Display language ISO-2. Must be supported for the chosen marketplace. |
currency | no | ISO-4217 display currency |
device | no | desktop (default) or mobile |
super | no | true for premium proxies |
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" }
]
}
}'| Param | Required | Description |
|---|---|---|
asin | yes | Amazon ASIN |
geocode | yes | Marketplace country code |
zipcode or countryName | no | Localizes price and availability. Pass at most one. Validated only when set. |
page | no | Offer page, clamped to 1–50 |
language | no | Display language ISO-2 |
currency | no | ISO-4217 display currency |
device | no | desktop (default) or mobile |
super | no | true for premium proxies |
include_html | no | true to include raw HTML |
amazon/deals - Discounted Products
Returns the discounted product grid for a marketplace, optionally narrowed to a category node and price range.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "amazon/deals",
"Params": [
{ "geocode": "us" },
{ "geocode": "us", "node": "172282", "low_price": 20, "high_price": 100, "sort_by": "price_low_to_high" }
]
}
}'| Param | Required | Description |
|---|---|---|
geocode | yes (or set top-level GeoCode) | Marketplace country code. Deals are currently available for us only; other marketplaces return 400. |
node | no | Category node ID. Without it the grid spans the whole marketplace. |
low_price / high_price | no | Price bounds (digits, max two decimals) |
sort_by | no | e.g. relevance, price_low_to_high, average_review, newest_arrivals |
page | no | 1–20 (default 1) |
zipcode or countryName | no | Localizes prices to a delivery location. Pass at most one. |
rh / i / s | no | Raw Amazon refinement, search index and sort keys |
amazon_domain | no | Marketplace domain (e.g. amazon.com), an alternative to geocode |
language / currency / device | no | Display language, ISO-4217 currency, desktop (default) or mobile |
super | no | true for premium proxies |
include_html | no | true to include raw HTML |
amazon/bestsellers - Best Sellers Chart
Returns the Best Sellers (or New Releases) ranking for a category.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "amazon/bestsellers",
"Params": [
{ "category": "electronics", "geocode": "us" },
{ "category": "electronics", "geocode": "us", "page": 2, "type": "new-releases" }
]
}
}'| Param | Required | Description |
|---|---|---|
category | yes | Category slug, e.g. electronics. Slugs are marketplace-specific. |
geocode | yes | Marketplace country code |
type | no | bestsellers (default) or new-releases |
node | no | Category node ID, narrowing the chart to a sub-category |
page | no | 1 (positions 1–50) or 2 (51–100) |
load_more | no | true to also fetch the positions Amazon loads on scroll. Costs twice a standard request. |
zipcode or countryName | no | Localizes prices to a delivery location. Pass at most one. |
amazon_domain | no | Marketplace domain (e.g. amazon.de), an alternative to geocode |
language / currency | no | Display language and ISO-4217 currency |
super | no | true for premium proxies |
include_html | no | true to include raw HTML |
The Best Sellers chart is desktop-only. device=mobile returns 400 for this key.
amazon/seller - Seller Profile
Returns the seller's display name, description, rating summary and business details. Pairs with amazon/offer-listing, which reports the seller IDs offering an ASIN.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "amazon/seller",
"Params": [
{ "seller": "A2L77EE7U53NWQ", "geocode": "us" },
{ "seller": "AOPPU1CKKHCUB", "geocode": "de" }
]
}
}'| Param | Required | Description |
|---|---|---|
seller | yes | Amazon seller ID, e.g. A2L77EE7U53NWQ |
geocode | yes | Marketplace country code |
zipcode or countryName | no | Localizes the page to a delivery location. Pass at most one. |
amazon_domain | no | Marketplace domain (e.g. amazon.de), an alternative to geocode |
language / currency / device | no | Display language, ISO-4217 currency, desktop (default) or mobile |
super | no | true for premium proxies |
include_html | no | true to include raw HTML |
amazon - Raw HTML
Returns the raw Amazon HTML for any Amazon URL, rendered from the perspective of a ZIP code. Use it when the structured plugins do not cover the page you need.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "amazon",
"Params": [
{ "url": "https://www.amazon.com/dp/B0CQMTCR9T", "zipcode": "32095", "geocode": "us" }
]
}
}'| Param | Required | Description |
|---|---|---|
url | yes | Full Amazon URL (must be an amazon.* domain) |
geocode | yes | Marketplace country code |
zipcode or country_name | no | Delivery location. country_name applies where ZIP-level delivery does not. Validated only when set. |
language / currency | no | Display language and currency |
device | no | desktop (default) or mobile |
super | no | true for premium proxies |
timeout | no | Per-request timeout in ms |
This key always returns HTML. The top-level Output field is ignored for plugin jobs.
Walmart, Sam's Club, Lowes & Home Depot Plugins
These keys read no geo parameter, so a top-level GeoCode returns 400. Select the location with each plugin's own params (zipcode, storeid, store, clubid).
walmart/store - Store-Scoped Request
Fetches a Walmart URL with store-specific session cookies. Raw HTML response.
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" },
{ "url": "https://www.walmart.com/ip/789012" }
]
}
}'| 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. On walmart.ca, storeid alone is accepted. |
disableretry | no | true to disable retry logic |
transparentresponse | no | true to return raw response |
timeout | no | Custom timeout in ms |
walmart/search - Search Results
Returns structured search results (US only), scoped to a store or ZIP. Sponsored items are flagged "sponsored": true.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "walmart/search",
"Params": [
{ "q": "laptop", "zipcode": "10001" },
{ "q": "laptop", "store": "925", "page": 2 }
]
}
}'| Param | Required | Description |
|---|---|---|
q (alias query) | yes | Search keyword |
zipcode or store | yes | Pass exactly one. zipcode: 5-digit US ZIP. store: numeric store ID covered by the plugin (unknown IDs return 400). |
page | no | 1–100 (default 1) |
timeout | no | Timeout in ms (capped at the system maximum) |
walmart/product - Product Detail
Returns structured product detail (US only), scoped to a store or ZIP.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "walmart/product",
"Params": [
{ "item": "15586351437", "zipcode": "10001" },
{ "item": "15586351437", "store": "925" }
]
}
}'| Param | Required | Description |
|---|---|---|
item | yes | Numeric Walmart item ID (results[].item_id from walmart/search) |
zipcode or store | yes | Pass exactly one. Same rules as walmart/search. |
timeout | no | Timeout in ms (capped at the system maximum) |
samsclub/store - Club-Scoped Request
Fetches a Sam's Club URL with club-specific session cookies. Returns the upstream body as-is: HTML for pages, JSON for Sam's Club API endpoints.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "samsclub/store",
"Params": [
{ "url": "https://www.samsclub.com/ip/13791994380", "zipcode": "77065", "clubid": "8274" },
{ "url": "https://www.samsclub.com/s/coffee" }
]
}
}'| Param | Required | Description |
|---|---|---|
url | yes | Full samsclub.com URL (product, category, search or API) |
zipcode | conditional | 5-digit US ZIP. Send together with clubid, or omit both for a random club. |
clubid (alias storeid) | conditional | Club number matching the ZIP. An invalid ZIP/club pair returns 400. |
disableretry | no | true to disable retry logic |
transparentresponse | no | true to return a partial body on timeout (instead of 502) |
timeout | no | Timeout in ms |
lowes/store - Store-Scoped Request
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). Send as a string to keep leading zeros. |
disableretry | no | true to disable retry logic |
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).
URL and store 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.
lowes/store is the only plugin that accepts "Method": "POST" (cart-add and similar endpoints). The job-level Body is sent with every task and is always sent as content-type: application/json.
homedepot/product - Store-Scoped Product Request
Fetches a Home Depot URL for a specific store and returns the upstream body as-is.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "homedepot/product",
"Params": [
{ "url": "https://www.homedepot.com/p/315183357", "zipcode": "30339", "storeid": "0121" }
]
}
}'| Param | Required | Description |
|---|---|---|
url | yes | Full homedepot.com URL |
zipcode | yes | ZIP code (digits only) |
storeid | yes | Store ID (digits only, e.g. from homedepot/stores) |
disableretry | no | true to disable retry logic |
timeout | no | Timeout in ms (capped at the system maximum) |
homedepot/stores - Store Locator
Returns Home Depot stores near a ZIP code or coordinates: store ID, name, phone, distance and address.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "homedepot/stores",
"Params": [
{ "zipcode": "02134" },
{ "lat": "33.7490", "lng": "-84.3880", "pagesize": 5 }
]
}
}'| Param | Required | Description |
|---|---|---|
zipcode or lat + lng | yes | ZIP code (digits only), or both coordinates |
pagesize | no | Number of stores (default 20) |
disableretry | no | true to disable retry logic |
timeout | no | Timeout in ms (capped at the system maximum) |
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 (or url) | Search query |
url | no | A full Google search URL instead of q. See url mode below. |
gl | no | Country code (default us) |
hl | no | Language code (default en) |
google_domain | no | Google domain (default google.com) |
location / uule | no | Location targeting (UULE overrides location) |
device | no | desktop (default) or mobile |
start | no | Result offset, 0–100 (default 0) |
safe | no | active to enable SafeSearch |
time_period | no | Time filter |
nfpr | no | true to disable autocorrection |
lr / cr | no | Language restrict (lang_tr) / country restrict (countryTR) |
filter | no | 0 to disable the similar/omitted results filter |
tbs | no | Raw Google tbs filter string |
ludocid | no | Google local business ID (send as a string) |
include_html | no | true to include raw HTML |
resolvegoto | no | Default true: Google /goto?url= redirect links are replaced with their destination. false keeps them. |
await_ai_overview | no | true to wait for a deferred AI Overview and return it in the same response. 5 extra credits, charged only when the AI Overview is returned. |
cache | no | false skips the result cache and fetches a fresh page (no_cache=true is the older form) |
validateresult | no | true checks the returned page against the query and reports the verdict in the task's response headers (Scrape.do-Validation-*) |
url mode. When an entry has url and no q, every Google parameter is read from inside url. The only params allowed next to it are device, include_html, resolvegoto, await_ai_overview, cache, no_cache and validateresult (keys are case-insensitive). Anything else (gl, hl, start, …), or a top-level GeoCode, returns 400 at job creation. Put gl inside the url instead.
Pagination runs in order. Tasks in one job that share every parameter except start are treated as pages of the same search. They run one at a time in ascending start order; each page starts after the previous one finishes (success or error). Tasks without start, and different searches, still run in parallel.
google/search/ai-mode - AI Mode
Returns Google's AI Mode (udm=50) response — ordered text blocks, source references, and shopping cards.
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 (max 4096 bytes) |
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 |
resolvegoto | no | Default true: redirect links in references are replaced with their destination. false keeps them. |
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. Individual params take precedence when both are set. |
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, sellers, and a next_page_token for paginating the rest of the sellers.
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" },
{ "immersive_product_page_token": "eyJlaSI6...", "more_stores": true }
]
}
}'| Param | Required | Description |
|---|---|---|
catalog_id | * | Region-scoped, durable catalog ID (digits; send as a string) |
product_id | * | Product ID from a google/shopping result (send as a string) |
immersive_product_page_token (alias page_token) | * | Short-lived (~hours). Returned by google/shopping. |
q | no | Original search query (relevance hint) |
gpcid | no | Offer cluster ID. Only with catalog_id; not combinable with sort_by or all_stores. |
pvf | no | Token mode only. Narrows sellers to one variant (from product_results.variants[].options[].pvf). |
more_stores | no | Token mode only. Widens the seller list from ~5 to ~10. |
all_stores | no | true returns up to ~100 sellers in one call |
sort_by | no | Seller sort: base_price, total_price, promotion, seller_rating |
include_html | no | true to include raw HTML |
device | no | desktop (default), mobile, tablet |
hl / gl / google_domain / location / uule | no | Standard localization. With a token, locale defaults to the token's; an explicit value wins. |
One of catalog_id, product_id, or immersive_product_page_token is required. When multiple are supplied, precedence is catalog_id > product_id > immersive_product_page_token. 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
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 | product_results.next_page_token from a google/shopping/product response, or the token from a previous stores response. Tokens from gpcid requests are rejected. |
The locale (q, gl, hl) 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. For the same reason, a top-level GeoCode returns 400 for this key.
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: a non-negative multiple of 20, up to 100 |
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...) |
data_cid | * | Numeric CID (send as a string) |
data_id | * | Place ID in 0xHEX:0xHEX format |
menu | no | Default true. false drops the structured menu and keeps only the menu link (smaller responses for bulk runs). |
hl / gl / google_domain | no | Standard localization |
One of place_id, data_cid, or data_id is required. All three come from google/maps/search local_results[].
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": "newest" }
]
}
}'| Param | Required | Description |
|---|---|---|
data_id | * | Place ID in 0xHEX:0xHEX format (preferred). One of data_id or place_id is required. |
place_id | * | Place ID in ChIJ... format (needs an extra resolution step) |
num | no | Reviews per page (1–50, default 10) |
sort_by | no | relevance (default, alias most_relevant), newest, highest_rating, or lowest_rating |
topic_id | no | Filter by topic (from the response's topics[]) |
next_page_token | no | Cursor from previous response's pagination.next_page_token |
hl / gl / google_domain | no | Standard localization |
Free-text review filtering (query) is not supported and returns 400. Use topic_id.
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; check-out must be after check-in |
sort_by | no | 3 lowest price, 8 highest rating, 13 most reviewed. Omit for relevance; any other value, including 0, returns 400. |
min_price / max_price | no | Nightly price filter (integer, ≥ 0; max_price ≥ min_price) |
rating | no | 7 (3.5+), 8 (4.0+), 9 (4.5+) |
hotel_class | no | Comma-separated star ratings 2–5 |
amenities / property_types | no | Comma-separated codes (property_types=12 switches to vacation rentals) |
free_cancellation / eco_certified / special_offers | no | Boolean filters |
next_page_token | no | Pagination cursor |
limit | no | Results per page, 1–20 (default 20) |
hl / gl / currency | no | Standard localization |
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.
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 or property_token | yes | From a google/hotels listing response. detail_token is preferred (faster). |
check_in_date / check_out_date | yes | YYYY-MM-DD; check-out must be after check-in |
currency | no | ISO 4217 (default USD) |
q | no | Original listing query (relevance hint) |
hl / gl | 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 | conditional | YYYY-MM-DD. Required for round trip (type=1). |
type | no | 1 round trip, 2 one way (inferred from return_date when omitted) |
adults / children | no | 1–9 adults (default 1), 0–9 children (default 0) |
infants_in_seat / infants_on_lap | no | 0–4 each (default 0) |
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) |
show_hidden | no | true appends the itineraries Google folds behind "View more flights" to other_flights. Some carry no price. |
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/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) |
Tokens come from news_results[] entries in previous responses. Optional: so (0 relevance, 1 date; only with q or kgmid), hl, gl, google_domain.
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; default worldwide) |
hl | no | Language code (default en) |
date | no | Time range (default today 12-m) |
tz | no | Timezone offset in minutes from UTC (default 420) |
data_type | no | Widget filter: TIMESERIES, GEO_MAP, GEO_MAP_0, RELATED_QUERIES, RELATED_TOPICS |
cat | no | Category ID |
gprop | no | Google property: web, images, news, youtube, froogle |
region | no | Granularity for geo data: COUNTRY, REGION, DMA, CITY |
google/trending - Currently Trending Searches
Returns currently trending search topics from Google Trends — the same data shown on trends.google.com/trending.
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
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) |
num | no | Results to return, 1–30. Cannot be combined with sp. |
device | no | desktop (default) or mobile |
hl / gl | no | Standard localization |
google/youtube/video - YouTube Video Detail
Returns video metadata, channel, related videos and comments, with continuation tokens for each.
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/video",
"Params": [
{ "v": "dQw4w9WgXcQ" },
{ "v": "dQw4w9WgXcQ", "hl": "de", "gl": "de", "next_page_token": "Eg0SC2RRdzR3OVdnWGNR..." }
]
}
}'| Param | Required | Description |
|---|---|---|
v | yes | 11-character video ID. Required on paginated calls too. |
next_page_token | no | Any continuation from a previous response: related_videos_next_page_token, comments_next_page_token, a comments_sorting_token[].token, or a comment's replies_next_page_token |
hl / gl | no | Standard localization (default en / us). Invalid values return 400. |
google/lens - Image Search
Returns visual matches, exact-image matches and related searches for an image URL.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "google/lens",
"Params": [
{ "url": "https://example.com/images/sneaker.jpg" },
{ "url": "https://example.com/images/sneaker.jpg", "type": "visual", "q": "red", "gl": "gb" }
]
}
}'| Param | Required | Description |
|---|---|---|
url | yes | Public http(s) URL of the image |
type | no | all (default), visual, exact |
q | no | Text to refine the image search. Not allowed with type=exact. |
safe | no | active or off |
include_html | no | true to include the raw results page |
hl / gl | no | Standard localization (default en / us) |
Param keys are case-sensitive for google/lens. Send them lowercase exactly as listed (url, not URL); other casings are ignored.
google/food - Food Ordering Providers
Returns the pickup and delivery providers Google lists for a restaurant: provider name, order link, ETA and fees.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "google/food",
"Params": [
{ "mid": "/g/11x38c65wl" },
{ "mid": "11x38c65wl", "gl": "gb", "google_domain": "google.co.uk" }
]
}
}'| Param | Required | Description |
|---|---|---|
mid | yes | Google entity ID, /g/<id> or /m/<id>. A bare ID (11x38c65wl) is treated as /g/11x38c65wl. |
google_domain | no | Default google.com. Must be a valid Google domain. |
hl / gl | no | Standard localization |
google/play-store - App Search
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 and combines with apps_category. When q is set it wins. |
num | no | Results per page (1–100, default 20) |
next_page_token | no | Pagination token from a previous response. Malformed tokens return 400. |
store_device | no | phone, tablet, tv, chromebook, watch, car. Only with apps_category / chart. |
age | no | AGE_RANGE1 (up to 5), AGE_RANGE2 (6–8), AGE_RANGE3 (9–12). Only with apps_category=FAMILY. |
hl / gl | no | Standard localization |
google/play-store/product - App Detail
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). Invalid IDs return 400. |
hl / gl | no | Standard localization |
google/play-store/reviews - App 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/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 — others return 400) |
next_page_token | no | Pagination token from a previous response |
hl / gl | no | Standard localization |
ChatGPT Plugins
chatgpt/chat - ChatGPT Reply
Sends a prompt to ChatGPT and returns the assembled reply as JSON, with sources, citations, shopping cards and local-business results. No browser automation or session management on your side — pass a prompt, get a structured response.
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 2048 characters, slightly less for some regions such as hk) |
model | no | Model selector (auto default; e.g., gpt-5, gpt-4o) |
geoCode | no | ISO-3166-1 alpha-2 country (case-insensitive, default us). Sets the exit country and reply language: us (English), de, tr, jp, … Unknown or blocked countries return 400. |
raw_sse | no | 1 to include the raw upstream stream body alongside the assembled response. Alias: include_raw=1. |
shopping_placeholders | no | 1 to emit {{shopping:<id>}} tokens in output.markdown instead of inline product links |
ads_format | no | flat (default) or grouped (ads grouped by brand) |
Send single-turn prompts. Each task should be a standalone prompt. A conversation_id comes from a previous response, and async jobs cannot chain one task's output into the next. Tasks run concurrently, so a second turn on a conversation that is still answering returns 409, and a conversation expires 10 minutes after its last turn.
chatgpt/v2/chat - ChatGPT Reply (v2)
Same params and response as chatgpt/chat, plus follow_up_suggestions and richer local-business results. model is accepted but has no effect.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "chatgpt/v2/chat",
"Params": [
{ "q": "best tablet under 500 usd", "geoCode": "us" },
{ "q": "hair salon near me", "geoCode": "us", "ads_format": "grouped" }
]
}
}'v2 is the only route that returns sponsored ads (tool_data.ads). ChatGPT shows ads only on follow-up turns and mostly in the US, so single-turn async jobs normally return ads: [].
Gemini, Naver & Waze Plugins
These keys read no geo parameter, so a top-level GeoCode returns 400.
gemini/chat - Gemini Reply
Sends a prompt to Google Gemini and returns the reply as Markdown with grounding sources.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "gemini/chat",
"Params": [
{ "q": "compare the iphone 16 and pixel 9" },
{ "q": "rezept für käsespätzle", "hl": "de" }
]
}
}'| Param | Required | Description |
|---|---|---|
q | yes | Prompt text (max 4000 characters; each call is standalone) |
hl | no | Reply UI language, BCP-47 (e.g., en-US, de, pt-BR) |
naver/ai-search - Naver AI Search
Returns Naver's AI search answer for a query.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "naver/ai-search",
"Params": [
{ "query": "서울 맛집 추천" }
]
}
}'| Param | Required | Description |
|---|---|---|
query | yes | Search query |
disableretry | no | true to return the first response without retrying |
waze/alerts - Waze Alerts
Returns live Waze alerts (accidents, police, hazards, jams, …) inside a bounding box.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "waze/alerts",
"Params": [
{ "top": 40.80, "bottom": 40.70, "left": -74.02, "right": -73.93 },
{ "top": 51.55, "bottom": 51.45, "left": -0.20, "right": 0.00, "types": "ACCIDENT,ROAD_CLOSED" }
]
}
}'| Param | Required | Description |
|---|---|---|
top / bottom | yes | Northern / southern edge (latitude, -90 to 90) |
left / right | yes | Western / eastern edge (longitude, -180 to 180) |
types | no | Comma-separated categories, e.g. ACCIDENT,POLICE,HAZARD. Omit for all. |
Swapped edges are corrected automatically. A zero-area box returns 400.
Carrefour Plugins
carrefour/* covers two catalogues: standard delivery (carrefour/search, carrefour/product) and rapid "15 mins" delivery (carrefour/rapid/search, carrefour/rapid/product). Prices and availability differ between them.
country is required on every task (or set top-level GeoCode). Only ae (United Arab Emirates) is enabled; other codes return 400.
carrefour/search - Search Results
Returns search results with prices, stock, and offer and seller IDs.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "carrefour/search",
"Params": [
{ "q": "nutella", "country": "ae" },
{ "q": "nutella", "country": "ae", "page": 1, "page_size": 20, "filter": "deal:true" }
]
}
}'| Param | Required | Description |
|---|---|---|
q | yes | Search keyword |
country | yes | ae |
page | no | Zero-based page (default 0) |
page_size | no | 1–40 (default 40) |
sort_by | no | Storefront sort order (default relevance) |
filter | no | Storefront filter expression, e.g. deal:true |
carrefour/product - Product Detail
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "carrefour/product",
"Params": [
{ "product_id": "28561", "country": "ae" },
{ "product_id": "28561", "country": "ae", "offer_id": "offer_carrefour_", "seller_id": "0000" }
]
}
}'| Param | Required | Description |
|---|---|---|
product_id | yes | results[].product_id from search (up to 32 chars of A-Z a-z 0-9 _ -) |
country | yes | ae |
offer_id | no | results[].offer_id. Send with seller_id for marketplace items. |
seller_id | no | results[].seller_id (send as a string, e.g. "0000") |
Without offer_id / seller_id, the store's own offer is returned.
carrefour/rapid/search and carrefour/rapid/product
Same params and response as carrefour/search and carrefour/product, over the rapid ("15 mins") catalogue.
{
"Plugin": {
"Key": "carrefour/rapid/search",
"Params": [
{ "q": "milk", "country": "ae" }
]
}
}Shein Plugin
shein - Product Page
Fetches a Shein product URL and returns the rendered product HTML. A 404 from Shein is passed through. Top-level GeoCode returns 400 for this key.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "shein",
"Params": [
{ "url": "https://www.shein.com/Tropical-Print-Drawstring-Hooded-Jacket-p-12345678.html" }
]
}
}'| Param | Required | Description |
|---|---|---|
url | yes | Full shein.com URL |
timeout | no | Timeout in ms |
Trip.com Plugins
country selects the Trip.com edition (locale, language, pricing region) and is required on every task, either per-param or via top-level GeoCode. It must be one of th, vn, id, jp, au, sg, my, in. A missing or unsupported value returns 400 at job creation.
trip/search - Flight Search
Returns itineraries in Trip.com's ranked order, with segments, fares, and the productId / policyId / shortPolicyId needed for trip/detail.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "trip/search",
"Params": [
{ "departCity": "SIN", "arriveCity": "BKK", "departDate": "2026-12-15", "country": "sg" },
{ "departCity": "SYD", "arriveCity": "TYO", "departDate": "2026-12-20", "returnDate": "2027-01-05", "country": "au", "adults": 2, "cabinClass": "c", "currency": "AUD" }
]
}
}'| Param | Required | Description |
|---|---|---|
departCity / arriveCity | yes | Departure / arrival city IATA code (e.g., SIN, BKK) |
departDate | yes | Outbound date, YYYY-MM-DD |
country | yes | Trip.com edition (see above) |
returnDate | no | Inbound date, YYYY-MM-DD. Omit for one-way. |
departAirport / arriveAirport | no | Specific airport IATA (e.g., JFK vs LGA) |
adults / children / infants | no | Passenger counts (default 1 / 0 / 0). Invalid counts fall back to the default. |
cabinClass | no | y economy (default), s premium economy, c business, f first |
currency | no | ISO-4217 (default USD) |
sortBy | no | Score (default), Price, Duration |
trip/detail - Fare Detail
Returns the full fare breakdown for one policy from trip/search: baggage, refund and change rules, fees and amenities.
curl -X POST "https://q.scrape.do/api/v1/jobs" \
--header "X-Token: YOUR_TOKEN" \
--header "Content-Type: application/json" \
--data '{
"Plugin": {
"Key": "trip/detail",
"Params": [
{ "policyId": "abc123...", "shortPolicyId": "xyz789...", "country": "sg" }
]
}
}'| Param | Required | Description |
|---|---|---|
policyId | yes | policyId from a trip/search result |
shortPolicyId | yes | shortPolicyId from the same result |
country | yes | Trip.com edition. Use the same one as the search. |
productId | no | productId from the search result (default: policyId) |
adults / children / infants | no | Passenger counts (default 1 / 0 / 0) |
currency | no | ISO-4217 (default USD) |
A sold-out policy returns 200 with {"error":"cabin_sold_out"}. Re-run trip/search for fresh fares.
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, amazon/* | geocode | verbatim |
google/trends, google/trending | geo | uppercased |
All other google/* (search, shopping, maps, hotels, flights, news, youtube, lens, food, play-store, …) | gl | lowercased |
chatgpt/chat, chatgpt/v2/chat | geoCode | verbatim (case-insensitive) |
carrefour/* | country | lowercased |
trip/search, trip/detail | country | lowercased; must be a Trip.com edition |
These keys read no geo parameter, so a top-level GeoCode returns 400 instead of being silently ignored: walmart/*, samsclub/store, lowes/store, homedepot/*, google/shopping/product/stores, gemini/chat, naver/ai-search, waze/alerts, shein. google/search in url mode also rejects it — put gl inside the url instead.
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 paramsWebhooks
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 for the full payload shape and delivery semantics.
{
"Plugin": { "Key": "amazon/pdp", "Params": [...] },
"WebhookURL": "https://example.com/webhook",
"WebhookHeaders": { "Authorization": "Bearer your-token" }
}Error Codes
These errors are returned at job creation; no tasks are created.
| 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 | plugin params exceed limit of 1000 (got N) | Too many param entries |
400 | method <M> is not supported for plugin <key> | Non-GET method on a key that only accepts GET |
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[i]: "<k>" is reserved and set by async-api; remove it | token, async or proxy_key in params |
400 | plugin params[i]: "<a>" and "<b>" differ only in case; send one | Case-duplicate keys in one entry |
400 | plugin params[i].<k>: must be a string, number or boolean … | Array or object value |
400 | plugin params[i]: google/search url= cannot be combined with <params>; put every Google parameter inside url | Search params next to url |
400 | top-level GeoCode cannot be used with google/search url=; put gl inside url | Top-level GeoCode with google/search in url mode |
400 | GeoCode "<v>" is not supported by trip/<x>; use one of … | Top-level GeoCode is not a Trip.com edition |
400 | plugin params[i]: country "<v>" is not supported by trip/<x>; use one of … | Per-param country is not a Trip.com edition |
400 | plugin params[i]: country is required for trip/<x> (or set top-level GeoCode); use one of … | Trip entry with no country and no GeoCode |

