API reference · Google Shopping

google-shopping/search

Integrate this model through SandBase's unified API, with production-ready schemas and examples.

APIAsyncOpen model

Production endpoint

Send your first request

OpenAI-compatible endpoint with unified authentication and usage tracking.

POSThttps://api.sandbase.ai/v1/api/google-shopping/search

Model IDgoogle-shopping/search

Input Schema

16 parameters · 1 required · 15 optional

Parameter	Type	Required	Description
`q`	stringnumberboolean	Required	The query you want to search. You can use anything that you would use in a regular Google Shopping search. This parameter is optional if using `shoprs` parameter.
`gl`	stringnumberboolean	Optional	The country to use for the Google search. It's a two-letter country code. (e.g., `us` for the United States, `uk` for United Kingdom, or `fr` for France) Head to the Google Shopping countries for a full list of supported Google Shopping countries.
`hl`	stringnumberboolean	Optional	The language to use for the Google Shopping search. It's a two or three-letter language code. (e.g., `en` for English, `es` for Spanish, or `fr` for French), optionally followed by a two-letter or three-digit region code (e.g., `en-gb` for British English, or `es-419` for Latin American Spanish).
`safe`	stringnumberboolean	Optional	The level of filtering for adult content. It can be set to `active` or `off`, by default Google will omit explicit content.
`uule`	stringnumberboolean	Optional	The Google encoded location you want to use for the search. `uule` and `location` parameters can't be used together. For consistent results with coordinates-based `uule` parameter, a matching `gl` parameter is required. Head to UULE Generator if you need to convert a location or GPS coordinates to `uule` parameter, and vice versa.
`start`	stringnumberboolean	Optional	Intended to define the result offset for pagination. Google Shopping's current layout does not support offset pagination: the `start` parameter is ignored and every request returns the first page of results (around 40 items). The `num` parameter is still accepted and forwarded to Google, but the current layout returns a fixed page size, so it does not change the number of results returned.
`device`	stringnumberboolean	Optional	The device to use to get the results. It can be set to `desktop` (default) to use a regular browser, `tablet` to use a tablet browser (currently using iPads), or `mobile` to use a mobile browser.
`shoprs`	stringnumberboolean	Optional	The parameter defines the token that includes metadata about query and search filter(s). Providing `q` parameter alongside the `shoprs` is not required. To apply multiple filters join them with `\|\|` separator, e.g. `shoprs_1\|\|shoprs_2\|\|shoprs_3`.
`on_sale`	stringnumberboolean	Optional	Show only products that are on sale. This parameter overrides corresponding filter embedded into `shoprs` parameter.
`sort_by`	union	Optional	The sorting order of the results. Available options: `1` - Price: low to high `2` - Price: high to low This parameter overrides corresponding filter embedded into `shoprs` parameter.
`max_price`	stringnumberboolean	Optional	Upper bound of price range query. This parameter overrides corresponding filter embedded into `shoprs` parameter.
`min_price`	stringnumberboolean	Optional	Lower bound of price range query. This parameter overrides corresponding filter embedded into `shoprs` parameter.
`free_shipping`	stringnumberboolean	Optional	Show only products with free shipping. This parameter overrides corresponding filter embedded into `shoprs` parameter.
`google_domain`	stringnumberboolean	Optional	The Google domain to use. It defaults to `google.com`. Head to the Google domains for a full list of supported Google domains.
`small_business`	stringnumberboolean	Optional	Show only products from small business. This parameter overrides corresponding filter embedded into `shoprs` parameter.
`json_restrictor`	stringnumberboolean	Optional	The fields you want to include in the output, reducing payload size for faster response. See the JSON Restrictor documentation for more details.

Output Schema

Field	Type	Description
`id`	string	Unique identifier for the generation task
`status`	string	Task status: pending, running, completed, failed, timeout
`model`	string	Model used for the generation
`outputs`	array	Array of output items
`outputs[].url`	string	URL of the generated artifact
`outputs[].content_type`	string	MIME type (e.g. image/png, video/mp4)
`error`	object \| null	Error details if failed, null on success
`error.type`	string	Machine-readable error type code
`error.message`	string	Human-readable error description

Async Workflow

This model uses asynchronous execution. Submit a request and poll for the result.

Submit — POST to /v1/run, receive an id
Poll — GET /v1/run/{id} until status is completed, failed, or timeout
Retrieve — Read outputs from the completed response

Code Examples

Ready-to-run snippets

const apiKey = process.env.SANDBASE_API_KEY;
const response = await fetch("https://api.sandbase.ai/v1/api/google-shopping/search", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({}),
});

if (!response.ok) throw new Error(await response.text());
console.log(await response.json());

← Back to Google Shopping Search