# Google Shopping Light Search

> Use when the user wants Google Shopping Light product search results through Frevana, including lightweight Google Shopping product lists, titles, prices, ratings, source merchants, localized country/language results, pagination offsets, or device-specific results. Use this instead of google-shopping-search when the user says "Google Shopping Light", "shopping light", or asks for the lightweight Google Shopping endpoint.

- Skill: `finpeakinc/google-shopping-light-search` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add finpeakinc/google-shopping-light-search`
- Raw SKILL.md: https://api.skillmd.com/api/skills/finpeakinc/google-shopping-light-search/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: finpeakinc (https://skillmd.com/u/finpeakinc)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/finpeakinc/google-shopping-light-search

---


# Google Shopping Light Search

Search Google Shopping Light product listings through Frevana.

## Purpose

This skill is for **finding lightweight Google Shopping product results**.

Inputs:

- `q`
- optional `google_domain`
- optional `gl`
- optional `hl`
- optional `start`
- optional `device`

Output:

- validated response JSON with Google Shopping Light product results
- the same validated JSON saved to a local file on every successful run

This skill validates that the response is JSON, saves it to disk, and returns it unchanged on stdout. Do **not** rewrite or reshape the returned data unless the user explicitly asks for a transformation.

## What This Skill Needs

- user-provided `q`
- optional `google_domain`
- optional `gl`
- optional `hl`
- optional `start`
- optional `device`
- `FREVANA_TOKEN` in the environment variables, or an explicit `--token` override for the current run
- `curl`
- `bash`
- `python3`

## Execution Order

Use this flow so the request stays simple and reliable:

1. Confirm the user has provided `q` or an equivalent product search query.
2. Prefer the script over ad hoc `curl` commands.
3. Let the script read `FREVANA_TOKEN` first.
4. In interactive shell usage, if `FREVANA_TOKEN` is missing, the script may prompt for it.
5. In non-interactive or agent workflows, fail fast if the token is missing and tell the user to set `FREVANA_TOKEN` or pass `--token` explicitly.
6. Run the script once. It prints the validated JSON to stdout and saves the same JSON to a file.
7. Use the saved JSON file for any follow-up parsing or summarization instead of calling the search API again.
8. Return the validated response JSON, or summarize the most relevant products if the user does not need the full payload.

## Commands

### Basic shopping light search

```bash
bash <skill-path>/scripts/search_google_shopping_light.sh \
  --q "wireless earbuds"
```

`--query` is accepted as an alias for `--q`.

### Search with country, language, and Google domain

```bash
bash <skill-path>/scripts/search_google_shopping_light.sh \
  --q "wireless earbuds" \
  --google-domain google.com \
  --gl US \
  --hl en
```

### Search with pagination and device

```bash
bash <skill-path>/scripts/search_google_shopping_light.sh \
  --q "wireless earbuds" \
  --start 20 \
  --device mobile
```

### Save response JSON to a specific file

```bash
bash <skill-path>/scripts/search_google_shopping_light.sh \
  --q "wireless earbuds" \
  --gl US \
  --hl en \
  --output ./out/google-shopping-light-search-result.json
```

### Token override for the current run

```bash
bash <skill-path>/scripts/search_google_shopping_light.sh \
  --q "wireless earbuds" \
  --token "your bearer token"
```

## Fixed Request Shape

The script sends this payload shape, omitting optional fields that were not provided:

```json
{
  "q": "wireless earbuds",
  "google_domain": "google.com",
  "gl": "US",
  "hl": "en",
  "start": 20,
  "device": "mobile"
}
```

Only `q` is required. Do not invent `google_domain`, `gl`, `hl`, `start`, or `device` values when the user did not provide them.

## Response Shape

The API returns Frevana JSON. This skill validates the response as JSON and returns it unchanged.

## Output

- Success: the script validates that the response body is JSON, writes it to a file, prints the saved path to stderr, and prints the JSON to stdout
- Default file path: `./out/google-shopping-light-search-<UTC timestamp>-<pid>.json`
- With `--output`: the same JSON is written to the specified file path instead of the default path
- Failure: the script prints the response body or parsing error and exits non-zero

## Notes

- Require `--q` or `--query`
- Do not call the script twice just to save and summarize results. It always saves the same JSON that it prints.
- Use `--google-domain` only when the user specifies a Google domain such as `google.com`
- Use `--gl` when the user requests a specific country or region
- Use `--hl` when the user requests a specific language
- Use `--start` when the user requests pagination by result offset
- Use `--device` only for `desktop`, `mobile`, or `tablet`
- This Light endpoint does not accept `sort_by`; use `google-shopping-search` if the user explicitly needs Google Shopping price sorting.
- If `curl` is missing, stop and tell the user to install `curl`
- If `python3` is missing, stop and tell the user to install `python3`
- Do not echo the Bearer token back to the user
- Summarize the product results the user actually cares about instead of dumping raw JSON unless they ask for the full payload

## Example Prompts

### 中文

- "搜索 Google Shopping Light 上的 wireless earbuds"
- "查一下 Google Shopping Light 里 q=running shoes，gl=US，hl=en"
- "Google Shopping Light 搜索 wireless earbuds，device=mobile，并保存原始 JSON"

### English

- "Search Google Shopping Light for wireless earbuds"
- "Look up Google Shopping Light results for running shoes with gl=US and hl=en"
- "Search Google Shopping Light for wireless earbuds on mobile and save the raw JSON"