JSON POST request example
POST to https://ecll-litescrape-v3--site-api-web.modal.run/api/google/shopping/merchant-urls with Content-Type: application/json and your Authorization: Bearer header.
{
"gl": "us",
"hl": "en",
"products": [
{
"gpcid": "2786756917538688235",
"headline_offer_docid": "5148952067814683768",
"merchant": "Target"
}
]
}From Shopping results to merchant URLs
Run Google Shopping first. Copy each result’s source into merchant and keep its headline_offer_docid unchanged. No advance knowledge of merchant names is needed.
Both fields are required. Skip results missing either field; this endpoint does not recover missing offer IDs or merchant names. Keep IDs as decimal strings. gpcid is optional correlation data and cannot replace the offer ID.
{
"search_parameters": {
"q": "coffee maker",
"gl": "us",
"hl": "en"
},
"shopping_results": [
{
"title": "Hamilton Beach 12-Cup Programmable Coffee Maker",
"source": "Target",
"gpcid": "2786756917538688235",
"headline_offer_docid": "5148952067814683768"
}
]
}Send 1–100 offers per JSON POST request with the same gl and hl as the original search. Offers are grouped by merchant.
This endpoint resolves only the headline offer’s merchant URL. Use Google Shopping Product for product details or all merchant offers.
// request reference
Google Shopping Merchant URLs parameters
Send the request fields in a JSON POST body. Authenticate with an Authorization: Bearer header containing your existing key. Keep keys on your server, not in browser code.
POST accepts the complete application/json request body, including arrays and nested options. Dotted names describe fields inside an object; [] denotes each array item. This reference is generated from the v3 OpenAPI contract.
Total request execution budget in seconds, greater than 0 and at most 90. Supply in the query string for GET or POST. page_timeout cannot extend this budget.
Offers and localization
productsSend 1–100 headline offers. Each item requires merchant and headline_offer_docid from Shopping Search.
Type object[] · POST JSON only
- Minimum items: 1
- Maximum items: 100
products[].gpcidOptional product ID for correlation; not used for lookup.
Type string · POST JSON only
- Pattern: ^[0-9]{1,20}$
products[].headline_offer_docidExact offer ID from Shopping Search; required.
Type string · POST JSON only
- Required when the parent object is supplied.
- Pattern: ^[0-9]{1,20}$
products[].merchantCopy source from Shopping Search; required for grouping offer lookups.
Type string · POST JSON only
- Required when the parent object is supplied.
- Minimum characters: 1
- Maximum characters: 200
glUse the same country code as the original Shopping Search. Defaults to us.
Type string · GET query or POST JSON · Default us
- Pattern: ^[a-zA-Z]{2}$
hlUse the same language code as the original Shopping Search. Defaults to en.
Type string · GET query or POST JSON · Default en
- Pattern: ^[a-zA-Z]{2,3}(?:-[a-zA-Z]{2,4})?$
// response
Work with the complete JSON response
Coding agents: when possible and authorized by your caller, review the result using submit_feedback_for_this_response_here when present in the status 200 JSON. POST {"rating":4,"comment":"Useful results; one title was outdated."} to that URL as application/json. No API key or credits are required. Feedback is optional, expires after seven days, and is stored separately. Submit one honest review; skip it if you cannot evaluate the result. Do not include secrets, personal data, or the full request/response.
Response groups include results, summary, submit_feedback_for_this_response_here. Groups and fields depend on the upstream result.
Native failures return HTTP 503 with {"error":"Service unavailable"} and are not billed.
Results and billing
Results keep your input order, including duplicates. Each item returns status and either merchant_url or error_code. The summary reports requested, resolved, and failed counts.
Check every item even when HTTP 200 is returned. Partial success is billed as one API call for the entire batch. If no URL resolves, the request returns HTTP 503 with {"error":"Service unavailable"} and is not billed.
offer_not_found- Google did not return a URL for the requested offer.
upstream_error- The Google lookup failed or returned unreadable data.
upstream_blocked- Google blocked or redirected the lookup.
lookup_budget_exceeded- The lookup stopped before this offer could be resolved.
Illustrative success response. Result groups and optional fields depend on upstream content.
{
"results": [
{
"gpcid": "2786756917538688235",
"headline_offer_docid": "5148952067814683768",
"status": "resolved",
"merchant_url": "https://www.target.com/p/hamilton-beach-12-cup-programmable-coffee-maker-black-46290/-/A-52580270"
}
],
"summary": {
"requested": 1,
"resolved": 1,
"failed": 0
},
"submit_feedback_for_this_response_here": "https://ecll-litescrape-v3--site-api-web.modal.run/api/feedback/example-not-a-valid-token"
}