Google Shopping Results API

# Integrate HasData Google Shopping API

## Task

Add the requested product search, shopping visibility or listing comparison workflow using HasData Google Shopping API.
Inspect project instructions, the server-side runtime, existing HTTP client, and tests first.
Follow the project's conventions and preserve unrelated code. No new SDK is required.
Implement only the requested workflow. If it is unclear, ask which query, market and product research workflow the application needs.
Keep the integration as REST API calls; do not replace it with an MCP connection or a custom Google scraper.

## References

Read the endpoint documentation before implementing:

- Product search, localization and filters: https://docs.hasdata.com/apis/google-serp/shopping.md
- Optional detailed product lookup: https://docs.hasdata.com/apis/google-serp/immersive-product.md
- Error handling: https://docs.hasdata.com/api-codes.md
- Documentation index: https://docs.hasdata.com/llms.txt
- Full documentation (fallback): https://docs.hasdata.com/llms-full.txt

Start with the endpoint reference. Use `llms.txt` to find additional pages.
Use `llms-full.txt` only when needed; extract relevant sections instead of loading everything into context.
If a `.md` reference is unavailable, try its HTML URL without `.md`.
If it is still unavailable, ask for the missing documentation rather than guessing.

## Optional agent skill

If the official `hasdata` skill is already available, use its relevant guidance.
Otherwise, if this agent supports skills, ask before installing it in this project:

```sh
npx skills add hasdata/agent-skills --skill hasdata
```

Run from the project directory and select the coding agent in use.
The `hasdata-cli` skill is not required. If installation is declined or unsupported, continue with the docs.
Flag conflicts between skill guidance and current API docs rather than guessing.


## Implementation

- Use `GET https://api.hasdata.com/scrape/google/shopping` with required `q`. Use the project’s HTTP client to encode query parameters.
- Expose only requested documented options such as `location`, `gl`, `hl` and `deviceType`. Preserve query, market, language and device context with saved observations. Do not invent a currency-conversion parameter.
- Read `shoppingResults` separately from optional `inlineShoppingResults`, `filters` and `refineSearchFilters`. Missing blocks, ratings, delivery text or product tokens are valid; do not promise a fixed result count.
- Preserve `productId` as a string. Product IDs, matching titles and shared Google groupings do not prove identical pack sizes, models, condition or seller offers.
- Keep display prices and numeric `extractedPrice` together. Validate currency, variants and quantities before comparisons; listed prices are not final checkout totals. Price histories, alerts and currency normalization belong to the application.
- For filters, use the returned camelCase `hasdataLink` and its query context. The prose docs call it `hasdata_link`; inspect the actual response and do not silently assume snake_case. Do not combine opaque `shoprs` values using invented rules.
- Before following any returned API link, require the exact `https://api.hasdata.com` origin and the intended endpoint path. Do not forward credentials to Google, merchants or arbitrary redirects.
- For requested pagination, use only documented parameters and inspect `pagination.next`. This is a Google URL, not an authenticated API endpoint. Prevent repeated-page loops and stop if no new results are returned; never promise an exhaustive inventory.
- Only identify sponsored listings from explicit returned labels. Do not infer ad status from position, product category or the presence of a shopping filter.
- Only if detailed product information is requested, send a returned `immersiveProductPageToken` as `pageToken` to `GET https://api.hasdata.com/scrape/google/immersive-product`. This is a separate API request, not included seller detail. Never manufacture or truncate tokens.
- Handle timeouts and documented errors before reading data. Keep requests server-side. If no suitable runtime exists, discuss options before changing the architecture.

## Credentials

- Implement the integration and mocked tests without requiring a live API key.
- Read `HASDATA_API_KEY` from the project's existing environment or secret store and send it as `x-api-key`.
- If the key is missing before live verification, ask the user to configure it from https://app.hasdata.com/api-keys.
- Never ask the user to paste the key into chat. Check only that it is configured, without printing its value.
- Never put the key in browser code, logs, or version control. Add only a placeholder to the project's example configuration.
- If using a local `.env` file, make sure it is gitignored.
- Send the key only to `https://api.hasdata.com`. Never forward it to documentation, Google, retailer links, media links, or redirects to another origin.


## Verification

- Add mocked tests for query encoding, market context, optional fields, large string IDs, duplicate listings, currency and pack-size mismatches, safe link handling, missing product tokens, repeated pagination, empty results and errors. Include a usage example and run local checks.
- With a configured key and explicit user approval, including approval already given for this task, make one live verification request with agreed inputs. A successful Google Shopping API request consumes 10 credits.
- Verify the requested Shopping search only. Do not automatically expand product tokens or follow filters and pagination.
- Validate the HTTP status, documented API status, and response structure. An empty result set can be valid.
- Do not automatically repeat paid requests to obtain a nonempty response.
- Report changed files, setup commands, and test results. State separately whether live verification passed, failed, or was skipped.
- Ask before deploying.