Parameters

`parameters` ¶

Parameter Models for Scrape.do's Google Plugin Endpoints

Defines the pydantic models containing the parameters accepted by the various endpoints of the Scrape.do Google Scraper API

Model Definitions

Model structure comes from the Official Documentation Page

Sections¶

Search Results

GoogleSearchParameters
GoogleSearchAiModeParameters
GoogleSearchAiOverviewParameters

Maps

GoogleMapsSearchParameters
GoogleMapsPlaceParameters
GoogleMapsReviewsParameters

Verticals

GoogleShoppingParameters
GoogleShoppingProductParameters
GoogleShoppingProductStoresParameters
GoogleFlightsParameters
GoogleHotelsParameters
GoogleHotelsDetailParameters

YouTube / Play Store

GoogleYouTubeParameters
GooglePlayStoreParameters
GooglePlayStoreProductParameters
GooglePlayStoreReviewsParameters

Others

GoogleNewsParameters
GoogleTrendsParameters
GoogleTrendingParameters

Additional Information¶

Localization

All Google plugins accept hl (language) and gl (country) for localization

super=True

All google plugins use premium residential proxies by default

Parameter Types

Some of the models' parameters are Literal Mappings
See the Enums module for a more detailed explanation of what they represent

`GoogleSearchParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/search endpoint

Localization

hl / gl

hl (language) and gl (country) are CONTEXT hints
Results are ranked from that locale's perspective but may still include cross-locale results

cr / lr

cr and lr are STRICT filters
They restrict to a country of origin / language and accept tokens like countryUS and lang_en respectively
See the Localization Reference for the full allowlists
You can also import the public GOOGLE_LANGUAGE_RESTRICT_VALUES frozenset for opt-in client-side validation of lr

location / uule

location is a human-readable string (e.g. "New York,New York, United States")
The server auto-encodes it to a UULE token and echoes both back in search_parameters
uule is a pre-encoded location token
When both location and uule are set, uule wins

Attributes:

Name	Type	Description
`q`	`str`	Search query.
`gl`	`Optional[str]`	Country-perspective code (default `us`)
`hl`	`Optional[str]`	Interface-language code (default `en`)
`google_domain`	`Optional[str]`	Google domain override (default `google.com`)
`device`	`Optional[GoogleDeviceType]`	Device class to emulate
`start`	`Optional[int]`	Non-negative result offset for pagination
`include_html`	`Optional[bool]`	Include raw HTML alongside parsed JSON
`cr`	`Optional[str]`	Strict country-of-origin filter in `country<UPPER_ISO>` form (combine with `.` for multiple)
`lr`	`Optional[str]`	Strict language-of-origin filter in `lang_<iso>` form
`uule`	`Optional[str]`	Pre-encoded UULE location token
`location`	`Optional[str]`	Human-readable location string. (auto-encoded to UULE server-side)
`safe`	`Optional[GoogleSafeSearchType]`	SafeSearch toggle
`time_period`	`Optional[GoogleTimePeriodType]`	Filter results to a rolling time window
`filter`	`Optional[str]`	Server-side de-duplication / similar content filter (opaque on the gateway)
`nfpr`	`Optional[GoogleNFPRType]`	Spell-correction toggle.

`GoogleSearchAiModeParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/search/ai-mode endpoint

Strict Subset of google/search

AI Mode is documented as a standalone endpoint whose accepted parameter set is a strict subset of the SERP plugin
SERP-only fields are rejected with 400 by the engine
Returns Google's udm=50 AI Mode response rather than the standard SERP envelope

Attributes:

Name	Type	Description
`q`	`str`	Search query.
`gl`	`Optional[str]`	Country-perspective code (default `us`)
`hl`	`Optional[str]`	Interface-language code (default `en`)
`google_domain`	`Optional[str]`	Google domain override (default `google.com`)
`device`	`Optional[GoogleDeviceType]`	Device class to emulate
`include_html`	`Optional[bool]`	Include raw HTML alongside parsed JSON
`uule`	`Optional[str]`	Pre-encoded UULE location token
`location`	`Optional[str]`	Human-readable location string (auto-encoded to UULE server-side)
`safe`	`Optional[GoogleSafeSearchType]`	SafeSearch toggle

`GoogleMapsSearchParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/maps/search endpoint

Attributes:

Name	Type	Description
`q`	`str`	Search query
`ll`	`Optional[str]`	Lat / lng / zoom pin in `@<lat>,<lng>,<zoom>z` form
`start`	`Optional[int]`	Page offset (multiples of 20)
`hl`	`Optional[str]`	Language code
`gl`	`Optional[str]`	Country code
`google_domain`	`Optional[str]`	Google domain override

`GoogleMapsPlaceParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/maps/place endpoint

Place ID + Data CID

Exactly one of place_id or data_cid MUST be set
Setting both or neither raises ValueError

Attributes:

Name	Type	Description
`place_id`	`Optional[str]`	Google Place ID in `ChIJ...` form
`data_cid`	`Optional[str]`	Numeric CID
`hl`	`Optional[str]`	Language code
`gl`	`Optional[str]`	Country code
`google_domain`	`Optional[str]`	Google domain override

`GoogleMapsReviewsParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/maps/reviews endpoint

Data ID + Place ID

Exactly one of data_id or place_id MUST be set

Topic ID + Query

topic_id and query are mutually exclusive

Attributes:

Name	Type	Description
`data_id`	`Optional[str]`	Place ID in `0xHEX:0xHEX` form
`place_id`	`Optional[str]`	Place ID in `ChIJ...` form
`num`	`Optional[int]`	Reviews per page (`1`-`20`, default `10` server-side)
`sort_by`	`Optional[GoogleReviewsSortByType]`	Sort order for the returned reviews
`topic_id`	`Optional[str]`	Filter reviews by topic ID
`query`	`Optional[str]`	Filter reviews by free-text keyword
`next_page_token`	`Optional[str]`	Cursor returned from a previous response's `pagination.next_page_token`
`hl`	`Optional[str]`	Language code
`gl`	`Optional[str]`	Country code

`GoogleShoppingParameters` ¶

Bases: BaseModel

Input Parameters accepted by the google/shopping endpoint

Attributes:

Name	Type	Description
`q`	`str`	Search query
`min_price`	`Optional[int]`	Minimum price filter
`max_price`	`Optional[int]`	Maximum price filter
`sort_by`	`Optional[GoogleShoppingSortByType]`	Sort order
`free_shipping`	`Optional[bool]`	Filter to free-shipping listings
`on_sale`	`Optional[bool]`	Filter to on-sale listings
`shoprs`	`Optional[str]`	Opaque filter token from a previous response
`device`	`Optional[GoogleDeviceType]`	Device class to emulate
`start`	`Optional[int]`	Pagination offset
`hl`	`Optional[str]`	Language code
`gl`	`Optional[str]`	Country code
`google_domain`	`Optional[str]`	Google domain override
`location`	`Optional[str]`	Location string for localization
`uule`	`Optional[str]`	Encoded UULE location parameter

`GoogleFlightsParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/flights endpoint

Include / Exclude Airlines

include_airlines and exclude_airlines are mutually exclusive
Setting both raises ValueError

Unsupported Parameters

The following parameters are NOT supported by Scrape.do's plugin engine and trigger a 400 response if sent, so they're intentionally absent from the model

type=3 (Multi-City)
max_price
max_duration
bags

The plugin engine enforces these limits regardless of whether the request is routed through the synchronous gateway or the Async API

Attributes:

Name	Type	Description
`departure_id`	`str`	IATA code for departure airport(s) Comma-separated for multi-airport
`arrival_id`	`str`	IATA code for arrival airport(s). Comma-separated for multi-airport
`outbound_date`	`str`	YYYY-MM-DD outbound date
`return_date`	`Optional[str]`	YYYY-MM-DD return date for round trips
`type`	`Optional[GoogleFlightsTripType]`	Trip type. Auto-inferred when omitted
`adults`	`Optional[int]`	Number of adult passengers (`1`-`9`)
`children`	`Optional[int]`	Number of child passengers (`0`-`9`)
`infants_in_seat`	`Optional[int]`	Infants requiring a seat (`0`-`4`)
`infants_on_lap`	`Optional[int]`	Infants on lap (`0`-`4`)
`travel_class`	`Optional[GoogleFlightsTravelClassType]`	Cabin class
`stops`	`Optional[GoogleFlightsStopsType]`	Stop filter
`sort_by`	`Optional[GoogleFlightsSortByType]`	Sort order
`include_airlines`	`Optional[str]`	Comma-separated IATA codes of airlines to include
`exclude_airlines`	`Optional[str]`	Comma-separated IATA codes of airlines to exclude
`hl`	`Optional[str]`	Language code
`gl`	`Optional[str]`	Country code
`currency`	`Optional[str]`	ISO-4217 currency code (e.g. `USD`, `EUR`)

`GoogleHotelsParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/hotels endpoint

Unsupported Parameters

Occupancy Parameters (adults, children, children ages) are NOT supported by Scrape.do's plugin engine
Results always reflect 2 adults / 0 children
These fields are intentionally absent from the model
The plugin engine enforces this regardless of whether the request is routed through the synchronous gateway or the Async API

Date Order

check_out_date MUST be strictly after check_in_date
Same-day or reversed ranges raise a ValueError at model construction time

Price Range

When both min_price and max_price are set, max_price MUST be >= min_price
Reversed ranges raise a ValueError at construction

Attributes:

Name	Type	Description
`q`	`str`	Hotel search query (use the simple `"<City> hotels"` form)
`check_in_date`	`date`	ISO-8601 check-in date (accepts a `datetime.date` or `"YYYY-MM-DD"` string)
`check_out_date`	`date`	ISO-8601 check-out date (must be after `check_in_date`)
`sort_by`	`Optional[GoogleHotelsSortByType]`	Sort order
`min_price`	`Optional[int]`	Minimum nightly price (in requested currency)
`max_price`	`Optional[int]`	Maximum nightly price (>= `min_price` when both set)
`rating`	`Optional[GoogleHotelsRatingType]`	Rating threshold
`hotel_class`	`Optional[str]`	Comma-separated star ratings (`2`-`5`)
`brands`	`Optional[str]`	Comma-separated brand codes
`amenities`	`Optional[str]`	Comma-separated amenity codes
`property_types`	`Optional[str]`	Comma-separated property-type codes
`free_cancellation`	`Optional[bool]`	Filter to free-cancellation listings
`eco_certified`	`Optional[bool]`	Filter to eco-certified listings
`special_offers`	`Optional[bool]`	Filter to listings with special offers
`next_page_token`	`Optional[str]`	Pagination cursor from a previous response
`limit`	`Optional[int]`	Maximum properties to return per request (`1`-`20`, default `20` server-side)
`hl`	`Optional[str]`	Language code
`gl`	`Optional[str]`	Country code
`currency`	`Optional[str]`	ISO-4217 currency code

`GoogleNewsParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/news endpoint

Driver

Exactly ONE of the following parameters MUST be provided

They are considered the driver of the request and setting zero or more than one raises ValueError

q
topic_token
section_token
story_token
publication_token

so

The so parameter is only valid when provided along with the q or kgmid drivers
Pairing it with any other driver raises ValueError

Driver Semantics

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)

Attributes:

Name	Type	Description
`q`	`Optional[str]`	Keyword search driver
`topic_token`	`Optional[str]`	Topic-stream driver
`section_token`	`Optional[str]`	Section-within-topic driver
`story_token`	`Optional[str]`	Full-coverage story-page driver
`publication_token`	`Optional[str]`	Publisher-feed driver
`kgmid`	`Optional[str]`	Knowledge Graph entity driver
`so`	`Optional[GoogleNewsSortOrderType]`	Sort order
`hl`	`Optional[str]`	Language code
`gl`	`Optional[str]`	Country code

`GoogleTrendsParameters` ¶

Bases: BaseModel

Input Parameters accepted by the google/trends endpoint

data_type Defaults

When data_type is omitted, the gateway returns the combined TIMESERIES + GEO_MAP payload
GEO_MAP is the multi-query regional-interest breakdown
GEO_MAP_0 is the single-query map

region

Sets the geographic resolution for the regional-interest widgets
Only meaningful when data_type selects GEO_MAP or GEO_MAP_0

Attributes:

Name	Type	Description
`q`	`str`	Search keyword
`geo`	`Optional[str]`	Location code (e.g. `US`, `GB`, `US-CA`)
`hl`	`Optional[str]`	Language code (default `en`)
`date`	`Optional[str]`	Time-range string (default `today 12-m`)
`tz`	`Optional[int]`	Timezone offset in minutes from UTC (default `420` server-side)
`data_type`	`Optional[GoogleTrendsDataType]`	Trends widget to fetch
`cat`	`Optional[str]`	Category ID
`gprop`	`Optional[GoogleTrendsGPropType]`	Google property scope
`region`	`Optional[GoogleTrendsRegionType]`	Geographic resolution for regional-interest widgets

`GoogleTrendingParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/trending endpoint

Real-Time Feed

Returns the current real-time trending searches from Google Trends
geo is required at the parameter level OR via the top-level GeoCode field on the async request

Attributes:

Name	Type	Description
`geo`	`str`	Country code (e.g. `US`, `GB`, `DE`, `TR`)
`hl`	`Optional[str]`	Language code (default `en`)
`hours`	`Optional[GoogleTrendingHoursType]`	Time window for the trends feed (default `24`)
`cat`	`Optional[int]`	Category ID to filter trends (default `0` = all)
`sort`	`Optional[GoogleTrendingSortType]`	Sort order for results (default `relevance`)
`status`	`Optional[GoogleTrendingStatusType]`	Trend-status filter (default `all`)

`GoogleSearchAiOverviewParameters` ¶

Bases: BaseModel

One request for the sync google/search/ai-overview follow-up form

SERP Deferred-State Follow-Up

The sync endpoint is the follow-up call made when a google/ search response includes ai_overview.state == "deferred"
The session_key is returned in the SERP response and must be passed unchanged
The session_key has a 60-second TTL on the server side and is one-time use
An expired or invalid key returns 404 session not found

Async API Surface

The Async API exposes a different shape for this plugin which takes the q driver (search query) instead of a session key in order to handles both fetch hops internally
For async-side usage see GoogleSearchAiOverviewAsyncParameters

Attributes:

Name	Type	Description
`session_key`	`str`	Session token captured from the SERP response's `ai_overview.session_key` when `ai_overview.state == "deferred"`
`hl`	`Optional[str]`	Interface-language code
`gl`	`Optional[str]`	Country-perspective code

`GoogleHotelsDetailParameters` ¶

Bases: BaseModel

One request for the google/hotels/detail endpoint

Two-Step Hotel Workflow

detail_token is acquired from a prior GoogleHotelsParameters listing response (properties[].detail_token) and must be passed unchanged
The same check_in_date, check_out_date, and currency values used on the listing call should be reused here so vendor pricing matches the original results

Date Order

check_out_date MUST be strictly after check_in_date
Same-day or reversed ranges raise a ValueError at model construction time

Attributes:

Name	Type	Description
`detail_token`	`str`	Opaque token returned by the listing response
`check_in_date`	`date`	ISO-8601 check-in date (accepts a `datetime.date` or `"YYYY-MM-DD"` string)
`check_out_date`	`date`	ISO-8601 check-out date (must be after `check_in_date`)
`currency`	`Optional[str]`	ISO-4217 currency code (default `USD`)
`gl`	`Optional[str]`	Country-perspective code (default `us`)
`hl`	`Optional[str]`	Interface-language code (default `en`)

`GoogleYouTubeParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/youtube endpoint

q

q and search_query are accepted as aliases for the same driver field
The model serializes the field as search_query to match the documented wire format

Attributes:

Name	Type	Description
`q`	`str`	YouTube search query (alias `search_query` accepted for construction)
`hl`	`Optional[str]`	Interface-language code (e.g. `en`, `de`, `fr`)
`gl`	`Optional[str]`	Country code (e.g. `us`, `gb`, `de`)
`device`	`Optional[GoogleDeviceType]`	Device class to emulate
`sp`	`Optional[str]`	YouTube's opaque token. Short values control sort / result type / duration / features / upload date; long values are continuation cursors

`GooglePlayStoreParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/play-store endpoint

Driver

At least one of q / apps_category / chart MUST be set
Setting none raises ValueError

age Field

age is only valid when apps_category == "FAMILY"
Pairing it with any other category raises ValueError

Attributes:

Name	Type	Description
`q`	`Optional[str]`	Keyword search query
`apps_category`	`Optional[str]`	App category filter (e.g. `FAMILY`, `GAME`, `BUSINESS`)
`chart`	`Optional[GooglePlayStoreChartType]`	Top-charts driver
`num`	`Optional[int]`	Result count (`1`-`50`, default `20`)
`next_page_token`	`Optional[str]`	Pagination cursor
`store_device`	`Optional[GooglePlayStoreDeviceType]`	Device form-factor filter
`age`	`Optional[GooglePlayStoreAgeType]`	Age-range filter (FAMILY category only)
`hl`	`Optional[str]`	Language code (default `en`)
`gl`	`Optional[str]`	Country code (default `us`)

`GooglePlayStoreProductParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/play-store/product endpoint

Attributes:

Name	Type	Description
`product_id`	`str`	Play Store product ID (e.g. `com.discord`)
`hl`	`Optional[str]`	Language code (default `en`)
`gl`	`Optional[str]`	Country code (default `us`)

`GooglePlayStoreReviewsParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/play-store/reviews endpoint

Attributes:

Name	Type	Description
`product_id`	`str`	Play Store product ID (e.g. `com.discord`)
`sort_by`	`Optional[int]`	Review sort order (default `1`; only `1` is currently supported per docs)
`next_page_token`	`Optional[str]`	Pagination cursor
`hl`	`Optional[str]`	Language code (default `en`)
`gl`	`Optional[str]`	Country code (default `us`)

`GoogleShoppingProductParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/shopping/product endpoint

Input Mode

At least one of the following input groups MUST be set

catalog_id + q (both required together)
immersive_product_page_token (alias page_token)
product_id

warning: Input Mode Constraints

- Setting `catalog_id` without `q` raises `ValueError`

- When multiple inputs are set, the gateway resolves them in
  priority order. `catalog_id` > `immersive_product_page_token` >
  `product_id`

Mode-Specific Optionals

load_all_stores is only valid in catalog_id mode
more_stores is only valid in token (legacy) mode

Attributes:

Name	Type	Description
`catalog_id`	`Optional[str]`	Durable catalog identifier (digit-only). Requires `q` when set
`q`	`Optional[str]`	Search query (required only with `catalog_id`)
`immersive_product_page_token`	`Optional[str]`	Short-lived opaque base64 token from search results (alias `page_token`)
`product_id`	`Optional[str]`	Google product catalog ID (digit-only)
`device`	`Optional[GoogleShoppingProductDeviceType]`	Device class to emulate
`google_domain`	`Optional[str]`	Google domain override (default `google.com`)
`sort_by`	`Optional[GoogleShoppingProductSortByType]`	Sort order (forces HTML-fallback path)
`load_all_stores`	`Optional[bool]`	Catalog mode only
`more_stores`	`Optional[bool]`	Token mode only (legacy)
`hl`	`Optional[str]`	Language code (default `en`)
`gl`	`Optional[str]`	Country code (default `us`)
`location`	`Optional[str]`	Human-readable location string
`uule`	`Optional[str]`	Pre-encoded UULE location token

`GoogleShoppingProductStoresParameters` ¶

Bases: BaseModel

Input parameters accepted by the google/shopping/product/stores endpoint

Continuation Endpoint

This endpoint returns additional store offers for a product discovered via google/shopping/product
catalog_id must match the catalog identifier embedded in next_page_token
The locale (q, gl, hl) is carried inside the token and reused server-side

Attributes:

Name	Type	Description
`catalog_id`	`str`	Durable catalog identifier (must match `next_page_token`)
`next_page_token`	`str`	`stores_next_page_token` value from a prior `google/shopping/product` response

Parameters

parameters ¶

Sections¶

Additional Information¶

GoogleSearchParameters ¶

GoogleSearchAiModeParameters ¶

GoogleMapsSearchParameters ¶

GoogleMapsPlaceParameters ¶

GoogleMapsReviewsParameters ¶

GoogleShoppingParameters ¶

GoogleFlightsParameters ¶

GoogleHotelsParameters ¶

GoogleNewsParameters ¶

GoogleTrendsParameters ¶

GoogleTrendingParameters ¶

GoogleSearchAiOverviewParameters ¶

GoogleHotelsDetailParameters ¶

GoogleYouTubeParameters ¶

GooglePlayStoreParameters ¶

GooglePlayStoreProductParameters ¶

GooglePlayStoreReviewsParameters ¶

GoogleShoppingProductParameters ¶

GoogleShoppingProductStoresParameters ¶

`parameters` ¶

`GoogleSearchParameters` ¶

`GoogleSearchAiModeParameters` ¶

`GoogleMapsSearchParameters` ¶

`GoogleMapsPlaceParameters` ¶

`GoogleMapsReviewsParameters` ¶

`GoogleShoppingParameters` ¶

`GoogleFlightsParameters` ¶

`GoogleHotelsParameters` ¶

`GoogleNewsParameters` ¶

`GoogleTrendsParameters` ¶

`GoogleTrendingParameters` ¶

`GoogleSearchAiOverviewParameters` ¶

`GoogleHotelsDetailParameters` ¶

`GoogleYouTubeParameters` ¶

`GooglePlayStoreParameters` ¶

`GooglePlayStoreProductParameters` ¶

`GooglePlayStoreReviewsParameters` ¶

`GoogleShoppingProductParameters` ¶

`GoogleShoppingProductStoresParameters` ¶