Lidl API Capability

Search products

Search Lidl's online assortment by keyword across GB, DE, and FR storefronts. Returns products with title, brand, price, ratings, images, PDP URL, and EAN when available.

Capability ID lidl.products.search

Cost From $1.25 per 1,000 requests · 1–5 credits

Maximum runtime 30 seconds

View raw

# Search products

Search Lidl's online assortment by keyword across GB, DE, and FR storefronts. Returns products with title, brand, price, ratings, images, PDP URL, and EAN when available.

- Platform: [Lidl](https://docs.upscrape.com/docs/platforms/lidl)
- Capability ID: `lidl.products.search`
- Cost: 1–5 credits per request
- Maximum runtime: 30 seconds
- Execute endpoint: `POST https://data.upscrape.com/execute`

## Request

Use the exact public capability ID in the shared execute envelope.

```bash
curl --request POST \
  --url https://data.upscrape.com/execute \
  --header "Authorization: Bearer $UPSCRAPE_API_KEY" \
  --header "Content-Type: application/json" \
  --header "Prefer: wait=30" \
  --data '{
  "input": {
    "country": "GB",
    "fetchsize": 5,
    "offset": 0,
    "query": "chocolate"
  },
  "capability": "lidl.products.search"
}'
```

## Input


| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `country` | `string` | No | Country to search in or localize results to. Allowed values: `GB`, `DE`, `FR`. Default: `GB`. |
| `fetchsize` | `integer` | No | Number of results per page. From 1 to 100. Default: `24`. |
| `offset` | `integer` | No | Zero-based number of results to skip. At least 0. Default: `0`. |
| `query` | `string` | Yes | Search query. |

### Example input

```json
{
  "country": "GB",
  "fetchsize": 5,
  "offset": 0,
  "query": "chocolate"
}
```

## Response

Successful output is returned in `results[0].data`.

Raw platform output is intentionally open-ended and may evolve with the upstream source.

### Illustrative sample output

This example shows one response. Values and optional fields vary with the data available.

```json
{
  "country": "GB",
  "fetchsize": 5,
  "items": [
    {
      "brand": "HALLOWEEN",
      "code": "10055407",
      "currency": "GBP",
      "description": "<p><strong>Get 15% off the regular price with the Lidl Plus app 01.10 &ndash; 07.10</strong></p>",
      "gridbox": {
        "action": "UPDATE",
        "country": "GB",
        "data": {
          "productId": 10055407,
          "energyLabels": [],
          "isLidlGiftCard": false,
          "keyfacts": {
            "analyticsCategory": "Food",
            "description": "<p><strong>Get 15% off the regular price with the Lidl Plus app 01.10 &ndash; 07.10</strong></p>",
            "fullTitle": "HALLOWEEN Milk Chocolate Balls",
            "moreDetails": "More details",
            "supplementalDescription": "70g",
            "title": "Milk Chocolate Balls",
            "wonCategoryPrimary": "Worlds of need/Food and near food/Candy & Snacks/Chocolate products",
            "wonCategoryPrimaryPath": "0/17/1744/174410"
          },
          "category": "Food",
          "lidlPlus": [
            {
              "highlightText": "SAVE 15%",
              "lidlPlusText": "With Lidl Plus",
              "price": {
                "basePrice": {
                  "prefix": false,
                  "text": "£12.00/kg"
                },
                "discount": {
                  "discountHasStar": false,
                  "discountText": "SAVE 15%",
                  "fromNormalPriceForLidlPlus": false,
                  "fromRecommendedPrice": false,
                  "showDiscount": false,
                  "showFrom": false,
                  "showPercentage": false,
                  "showUpTo": false
                },
                "displayedCurrency": "£",
                "hasStar": false,
                "hasVat": false,
                "oldPrice": 0,
                "packaging": {
                  "text": "Regular price £0.99"
                },
                "price": 0.84,
                "priceTheme": "white_yellow",
                "specialTaxes": [],
                "superscript": ""
              }
            }
          ],
          "guaranteeLabels": [],
          "havingPrice": true,
          "ians": [
            "213279"
          ],
          "canonicalPath": "/p/halloween-milk-chocolate-balls/p10055407",
          "timezoneId": "Europe/London",
          "awards": [],
          "ribbons": [],
          "regionsPrices": {},
          "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg",
          "storeStartDate": 1790809200,
          "preventSelling": false,
          "renderedTs": 1790215745,
          "dealOfDay": {
            "active": false
          },
          "image_V1": {
            "accessibility": "A mesh bag of Halloween milk chocolates with spooky skull, pumpkin, and eyeball designs.",
            "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg"
          },
          "cutoutimageV2": [],
          "havingThreesixty": false,
          "gs1Attributes": [],
          "imageList_V1": [
            {
              "accessibility": "A mesh bag of Halloween milk chocolates with spooky skull, pumpkin, and eyeball designs.",
              "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg"
            }
          ],
          "erpNumber": "10055407",
          "designTheme": "default",
          "imageList": [
            "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg"
          ],
          "zones": {},
          "hasColors": false,
          "flashSales": false,
          "price": {
            "currencyCode": "GBP",
            "currencyCodeSecond": "",
            "currencySymbol": "£",
            "currencySymbolSecond": "",
            "displayedCurrency": "£",
            "hasStar": false,
            "hasVat": false,
            "specialTaxes": [],
            "variantsHaveDifferentPrices": false
          },
          "storeEndDate": 1791413999,
          "highlightedSeals": 0,
          "ageRestriction": false,
          "brand": {
            "name": "HALLOWEEN",
            "showBrand": true,
            "url": "/q/search?q=halloween"
          },
          "store": false,
          "quickAddToCart": false,
          "fullTitle": "HALLOWEEN Milk Chocolate Balls",
          "productOrigin": "progress_event",
          "seals": [],
          "isUsedProduct": false,
          "multipack": false,
          "stockAvailability": {
            "availabilityIndicator": 0,
            "backInStockNotification": false,
            "backInStockNotificationSoldOut": false,
            "badgeInfo": {
              "badges": [
                {
                  "text": "In store from 01.10",
                  "type": "IN_STORE_FROM_FUTURE_DATE_RANGE"
                }
              ]
            },
            "badgeInfoV2": [
              {
                "badges": [
                  {
                    "text": "In store from 01.10",
                    "type": "IN_STORE_FROM_FUTURE_DATE_RANGE"
                  }
                ],
                "validFrom": 1790809200,
                "validUntil": 1791413999
              }
            ],
            "minOrderableQuantity": 1,
            "onlineAvailable": false
          },
          "displayFreeDelivery": false,
          "productType": "RETAIL",
          "disclaimers": [
            {
              "id": "code_10055407_c83ed87a",
              "type": "CODE",
              "value": "Basic"
            }
          ],
          "title": "Milk Chocolate Balls",
          "itemId": 10055407,
          "canonicalUrl": "/p/halloween-milk-chocolate-balls/p10055407",
          "havingVideos": false,
          "online": false
        },
        "eventType": "GRIDBOX",
        "id": "10055407",
        "language": "en",
        "meta": {
          "campaignPaths": [
            [
              {
                "hiddenCategory": false,
                "id": "10030004",
                "name": "Halloween Party Food",
                "url": "/c/halloween-party-food-and-sweets/a10030004"
              }
            ],
            [
              {
                "hiddenCategory": false,
                "id": "10053070",
                "name": "Lidl Plus Offers - Upcoming Deals",
                "url": "/c/lidl-plus-offers-upcoming/a10053070"
              }
            ]
          ],
          "categoryPaths": [],
          "fullTitle": "HALLOWEEN Milk Chocolate Balls",
          "lists": [
            6063,
            6065
          ],
          "preview": false,
          "retailLists": [
            [
              {
                "id": 6063,
                "productSortIndex": 26
              },
              {
                "id": 6065,
                "productSortIndex": 9
              }
            ]
          ],
          "wonCategoryBreadcrumbs": [
            [
              {
                "hiddenCategory": false,
                "id": "10068374",
                "name": "Food & Drink",
                "url": "/c/food-drink/s10068374"
              },
              {
                "hiddenCategory": false,
                "id": "10096205",
                "name": "Confectionery & Snacks",
                "url": "/h/confectionery-snacks/h10096205"
              },
              {
                "hiddenCategory": false,
                "id": "10096206",
                "name": "Chocolate & Chocolate Bars",
                "url": "/h/chocolate-chocolate-bars/h10096206"
              }
            ]
          ],
          "worldOfNeeds": [
            {
              "code": "174410",
              "isMain": true,
              "name": "Chocolate products",
              "parent": "1744",
              "superCategories": [
                {
                  "code": "1744",
                  "name": "Candy & Snacks",
                  "parent": "17"
                },
                {
                  "code": "17",
                  "name": "Food and near food",
                  "parent": "0"
                },
                {
                  "code": "0",
                  "name": "Worlds of need",
                  "parent": ""
                }
              ]
            }
          ]
        },
        "productId": 10055407,
        "sequence": 1790215745917073
      },
      "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg",
      "product_type": "RETAIL",
      "title": "HALLOWEEN Milk Chocolate Balls",
      "url": "https://www.lidl.co.uk/p/halloween-milk-chocolate-balls/p10055407"
    },
    {
      "brand": "J.D. GROSS",
      "code": "10055053",
      "currency": "GBP",
      "description": "<p><strong>Get 20% off the regular price with the Lidl Plus app 24.09 &ndash; 07.10</strong></p>",
      "gridbox": {
        "action": "UPDATE",
        "country": "GB",
        "data": {
          "productId": 10055053,
          "energyLabels": [],
          "isLidlGiftCard": false,
          "keyfacts": {
            "analyticsCategory": "Food",
            "description": "<p><strong>Get 20% off the regular price with the Lidl Plus app 24.09 &ndash; 07.10</strong></p>",
            "fullTitle": "J.D. GROSS Dark Chocolate",
            "moreDetails": "More details",
            "supplementalDescription": "125g",
            "title": "Dark Chocolate",
            "wonCategoryPrimary": "Worlds of need/Food and near food/Candy & Snacks/Chocolate products",
            "wonCategoryPrimaryPath": "0/17/1744/174410"
          },
          "category": "Food",
          "lidlPlus": [
            {
              "highlightText": "SAVE 20%",
              "lidlPlusText": "With Lidl Plus",
              "price": {
                "basePrice": {
                  "prefix": false,
                  "text": "£15.92/kg"
                },
                "discount": {
                  "discountHasStar": false,
                  "discountText": "SAVE 20%",
                  "fromNormalPriceForLidlPlus": false,
                  "fromRecommendedPrice": false,
                  "showDiscount": false,
                  "showFrom": false,
                  "showPercentage": false,
                  "showUpTo": false
                },
                "displayedCurrency": "£",
                "hasStar": false,
                "hasVat": false,
                "oldPrice": 0,
                "packaging": {
                  "text": "Regular price £2.49"
                },
                "price": 1.99,
                "priceTheme": "white_yellow",
                "specialTaxes": [],
                "superscript": ""
              }
            }
          ],
          "guaranteeLabels": [],
          "havingPrice": true,
          "ians": [
            "28823"
          ],
          "canonicalPath": "/p/j-d-gross-dark-chocolate/p10055053",
          "timezoneId": "Europe/London",
          "awards": [],
          "ribbons": [],
          "regionsPrices": {},
          "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg",
          "storeStartDate": 1790204400,
          "preventSelling": false,
          "renderedTs": 1790204615,
          "dealOfDay": {
            "active": false
          },
          "image_V1": {
            "accessibility": "Three bars of dark chocolate with 90%, 70%, and 85% cocoa content.",
            "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg"
          },
          "cutoutimageV2": [],
          "havingThreesixty": false,
          "gs1Attributes": [],
          "imageList_V1": [
            {
              "accessibility": "Three bars of dark chocolate with 90%, 70%, and 85% cocoa content.",
              "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg"
            }
          ],
          "erpNumber": "10055053",
          "designTheme": "default",
          "imageList": [
            "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg"
          ],
          "zones": {},
          "hasColors": false,
          "flashSales": false,
          "price": {
            "currencyCode": "GBP",
            "currencyCodeSecond": "",
            "currencySymbol": "£",
            "currencySymbolSecond": "",
            "displayedCurrency": "£",
            "hasStar": false,
            "hasVat": false,
            "specialTaxes": [],
            "variantsHaveDifferentPrices": false
          },
          "storeEndDate": 1790809199,
          "highlightedSeals": 0,
          "ageRestriction": false,
          "brand": {
            "name": "J.D. GROSS",
            "showBrand": true,
            "url": "/q/search?q=j.d.+gross"
          },
          "store": true,
          "quickAddToCart": false,
          "fullTitle": "J.D. GROSS Dark Chocolate",
          "productOrigin": "progress_event",
          "seals": [],
          "isUsedProduct": false,
          "multipack": false,
          "stockAvailability": {
            "availabilityIndicator": 0,
            "backInStockNotification": false,
            "backInStockNotificationSoldOut": false,
            "badgeInfo": {
              "badges": [
                {
                  "text": "Available in store now",
                  "type": "IN_STORE_TODAY_DATE_RANGE"
                }
              ]
            },
            "badgeInfoV2": [
              {
                "badges": [
                  {
                    "text": "Available in store now",
                    "type": "IN_STORE_TODAY_DATE_RANGE"
                  }
                ],
                "validFrom": 1790204400,
                "validUntil": 1790809199
              }
            ],
            "minOrderableQuantity": 1,
            "onlineAvailable": false
          },
          "displayFreeDelivery": false,
          "productType": "RETAIL",
          "disclaimers": [
            {
              "id": "code_10055053_63191637",
              "type": "CODE",
              "value": "Basic"
            }
          ],
          "title": "Dark Chocolate",
          "itemId": 10055053,
          "canonicalUrl": "/p/j-d-gross-dark-chocolate/p10055053",
          "havingVideos": false,
          "online": false
        },
        "eventType": "GRIDBOX",
        "id": "10055053",
        "language": "en",
        "meta": {
          "campaignPaths": [
            [
              {
                "hiddenCategory": false,
                "id": "10053070",
                "name": "Lidl Plus Offers - Upcoming Deals",
                "url": "/c/lidl-plus-offers-upcoming/a10053070"
              }
            ]
          ],
          "categoryPaths": [],
          "fullTitle": "J.D. GROSS Dark Chocolate",
          "lists": [
            6054,
            6063
          ],
          "preview": false,
          "retailLists": [
            [
              {
                "id": 6054,
                "productSortIndex": 44
              },
              {
                "id": 6063,
                "productSortIndex": 49
              }
            ]
          ],
          "wonCategoryBreadcrumbs": [
            [
              {
                "hiddenCategory": false,
                "id": "10068374",
                "name": "Food & Drink",
                "url": "/c/food-drink/s10068374"
              },
              {
                "hiddenCategory": false,
                "id": "10096205",
                "name": "Confectionery & Snacks",
                "url": "/h/confectionery-snacks/h10096205"
              },
              {
                "hiddenCategory": false,
                "id": "10096206",
                "name": "Chocolate & Chocolate Bars",
                "url": "/h/chocolate-chocolate-bars/h10096206"
              }
            ]
          ],
          "worldOfNeeds": [
            {
              "code": "174410",
              "isMain": true,
              "name": "Chocolate products",
              "parent": "1744",
              "superCategories": [
                {
                  "code": "1744",
                  "name": "Candy & Snacks",
                  "parent": "17"
                },
                {
                  "code": "17",
                  "name": "Food and near food",
                  "parent": "0"
                },
                {
                  "code": "0",
                  "name": "Worlds of need",
                  "parent": ""
                }
              ]
            }
          ]
        },
        "productId": 10055053,
        "sequence": 1790204615760361
      },
      "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg",
      "product_type": "RETAIL",
      "title": "J.D. GROSS Dark Chocolate",
      "url": "https://www.lidl.co.uk/p/j-d-gross-dark-chocolate/p10055053"
    },
    {
      "code": "10052239",
      "currency": "GBP",
      "gridbox": {
        "action": "UPDATE",
        "country": "GB",
        "data": {
          "productId": 10052239,
          "energyLabels": [],
          "isLidlGiftCard": false,
          "keyfacts": {
            "analyticsCategory": "Food",
            "fullTitle": "Kinder Chocolate",
            "moreDetails": "More details",
            "supplementalDescription": "300g (24 x 12,5g)",
            "title": "Kinder Chocolate",
            "wonCategoryPrimary": "Worlds of need/Food and near food/Candy & Snacks/Chocolate products",
            "wonCategoryPrimaryPath": "0/17/1744/174410"
          },
          "category": "Food",
          "lidlPlus": [],
          "guaranteeLabels": [],
          "havingPrice": true,
          "ians": [
            "5209117"
          ],
          "canonicalPath": "/p/kinder-chocolate/p10052239",
          "timezoneId": "Europe/London",
          "awards": [],
          "ribbons": [],
          "regionsPrices": {},
          "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg",
          "storeStartDate": 1790809200,
          "preventSelling": false,
          "renderedTs": 1790215724,
          "dealOfDay": {
            "active": false
          },
          "image_V1": {
            "accessibility": "A packet of Kinder Chocolate on a white background ",
            "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg"
          },
          "cutoutimageV2": [],
          "havingThreesixty": false,
          "gs1Attributes": [],
          "imageList_V1": [
            {
              "accessibility": "A packet of Kinder Chocolate on a white background ",
              "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg"
            }
          ],
          "erpNumber": "10052239",
          "designTheme": "default",
          "imageList": [
            "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg"
          ],
          "zones": {},
          "hasColors": false,
          "flashSales": false,
          "price": {
            "basePrice": {
              "prefix": false,
              "text": "£11.63/kg"
            },
            "currencyCode": "GBP",
            "currencyCodeSecond": "",
            "currencySymbol": "£",
            "currencySymbolSecond": "",
            "displayedCurrency": "£",
            "hasStar": false,
            "hasVat": false,
            "oldPrice": 0,
            "price": 3.49,
            "priceTheme": "white_red",
            "specialTaxes": [],
            "variantsHaveDifferentPrices": false
          },
          "storeEndDate": 1793663999,
          "highlightedSeals": 0,
          "ageRestriction": false,
          "brand": {
            "showBrand": false
          },
          "store": false,
          "quickAddToCart": false,
          "fullTitle": "Kinder Chocolate",
          "productOrigin": "progress_event",
          "seals": [],
          "isUsedProduct": false,
          "multipack": false,
          "stockAvailability": {
            "availabilityIndicator": 0,
            "backInStockNotification": false,
            "backInStockNotificationSoldOut": false,
            "badgeInfo": {
              "badges": [
                {
                  "text": "In store from 01.10",
                  "type": "IN_STORE_FROM_FUTURE_DATE_RANGE"
                }
              ]
            },
            "badgeInfoV2": [
              {
                "badges": [
                  {
                    "text": "In store from 01.10",
                    "type": "IN_STORE_FROM_FUTURE_DATE_RANGE"
                  }
                ],
                "validFrom": 1790809200,
                "validUntil": 1793663999
              }
            ],
            "minOrderableQuantity": 1,
            "onlineAvailable": false
          },
          "displayFreeDelivery": false,
          "productType": "RETAIL",
          "disclaimers": [
            {
              "id": "code_10052239_eb9336d2",
              "type": "CODE",
              "value": "Basic"
            }
          ],
          "title": "Kinder Chocolate",
          "itemId": 10052239,
          "canonicalUrl": "/p/kinder-chocolate/p10052239",
          "havingVideos": false,
          "online": false
        },
        "eventType": "GRIDBOX",
        "id": "10052239",
        "language": "en",
        "meta": {
          "campaignPaths": [
            [
              {
                "hiddenCategory": false,
                "id": "10030004",
                "name": "Halloween Party Food",
                "url": "/c/halloween-party-food-and-sweets/a10030004"
              }
            ]
          ],
          "categoryPaths": [],
          "fullTitle": "Kinder Chocolate",
          "lists": [
            6065
          ],
          "preview": false,
          "retailLists": [
            [
              {
                "id": 6065,
                "productSortIndex": 16
              }
            ]
          ],
          "wonCategoryBreadcrumbs": [
            [
              {
                "hiddenCategory": false,
                "id": "10068374",
                "name": "Food & Drink",
                "url": "/c/food-drink/s10068374"
              },
              {
                "hiddenCategory": false,
                "id": "10096205",
                "name": "Confectionery & Snacks",
                "url": "/h/confectionery-snacks/h10096205"
              },
              {
                "hiddenCategory": false,
                "id": "10096206",
                "name": "Chocolate & Chocolate Bars",
                "url": "/h/chocolate-chocolate-bars/h10096206"
              }
            ]
          ],
          "worldOfNeeds": [
            {
              "code": "174410",
              "isMain": true,
              "name": "Chocolate products",
              "parent": "1744",
              "superCategories": [
                {
                  "code": "1744",
                  "name": "Candy & Snacks",
                  "parent": "17"
                },
                {
                  "code": "17",
                  "name": "Food and near food",
                  "parent": "0"
                },
                {
                  "code": "0",
                  "name": "Worlds of need",
                  "parent": ""
                }
              ]
            }
          ]
        },
        "productId": 10052239,
        "sequence": 1790215724220556
      },
      "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg",
      "price": 3.49,
      "product_type": "RETAIL",
      "title": "Kinder Chocolate",
      "url": "https://www.lidl.co.uk/p/kinder-chocolate/p10052239"
    }
  ],
  "numFound": 20,
  "offset": 0,
  "query": "chocolate"
}
```
### Illustrative output fields

Derived from the sample above for orientation only. These fields are not a fixed response schema.

| Path | Observed type | Example |
| --- | --- | --- |
| `country` | `string` | GB |
| `fetchsize` | `integer` | 5 |
| `items` | `array` | 3 items |
| `items` | `array` | 3 items |
| `numFound` | `integer` | 20 |
| `offset` | `integer` | 0 |
| `query` | `string` | chocolate |

## Execution behavior

A `200` response completed inline. A `202` response was queued; poll `GET /jobs/{id}` until the job reaches `completed` or `failed`. Use an `Idempotency-Key` when retrying must not create a duplicate logical job.

## Related documentation

- [Authentication](https://docs.upscrape.com/docs/api/authentication)
- [Jobs and results](https://docs.upscrape.com/docs/api/jobs)
- [Errors and retries](https://docs.upscrape.com/docs/api/errors)
- [Idempotency](https://docs.upscrape.com/docs/api/idempotency)

POST /execute Shared execution endpoint

Input parameters

country string optional

Country to search in or localize results to. Allowed values: `GB`, `DE`, `FR`. Default: `GB`.

Example GB

Available values GBDEFR

fetchsize integer optional

Number of results per page. From 1 to 100. Default: `24`.

Example 5

offset integer optional

Zero-based number of results to skip. At least 0. Default: `0`.

Example 0

query string required

Search query.

Example chocolate

Response

Successful output is returned in results[0].data.

Raw platform output is intentionally open-ended and may evolve with the upstream source.

Illustrative sample The example response is shown in the response panel.

Illustrative output fields

Values illustrate one response. Read the guidance above for missing values and limits; fields can vary with the requested operation and the data available.

Path	Observed type	Example
`country`	`string`	GB
`fetchsize`	`integer`	5
`items`	`array`	3 items
`items`	`array`	3 items
`numFound`	`integer`	20
`offset`	`integer`	0
`query`	`string`	chocolate

Execution behavior

A 200 response completed inline. A 202 response was queued; poll GET /jobs/:id until the job reaches completed or failed.

curl --request POST \ --url https://data.upscrape.com/execute \ --header "Authorization: Bearer $UPSCRAPE_API_KEY" \ --header "Content-Type: application/json" \ --header "Prefer: wait=30" \ --data '{ "input": { "country": "GB", "fetchsize": 5, "offset": 0, "query": "chocolate" }, "capability": "lidl.products.search" }'

import json import os import requests payload = json.loads(r'''{ "input": { "country": "GB", "fetchsize": 5, "offset": 0, "query": "chocolate" }, "capability": "lidl.products.search" }''') response = requests.post( "https://data.upscrape.com/execute", headers={ "Authorization": f"Bearer {os.environ['UPSCRAPE_API_KEY']}", "Content-Type": "application/json", "Prefer": "wait=30", }, json=payload, ) response.raise_for_status() print(json.dumps(response.json(), indent=2))

{ "country": "GB", "fetchsize": 5, "items": [ { "brand": "HALLOWEEN", "code": "10055407", "currency": "GBP", "description": "Get 15% off the regular price with the Lidl Plus app 01.10 – 07.10", "gridbox": { "action": "UPDATE", "country": "GB", "data": { "productId": 10055407, "energyLabels": [], "isLidlGiftCard": false, "keyfacts": { "analyticsCategory": "Food", "description": "Get 15% off the regular price with the Lidl Plus app 01.10 – 07.10", "fullTitle": "HALLOWEEN Milk Chocolate Balls", "moreDetails": "More details", "supplementalDescription": "70g", "title": "Milk Chocolate Balls", "wonCategoryPrimary": "Worlds of need/Food and near food/Candy & Snacks/Chocolate products", "wonCategoryPrimaryPath": "0/17/1744/174410" }, "category": "Food", "lidlPlus": [ { "highlightText": "SAVE 15%", "lidlPlusText": "With Lidl Plus", "price": { "basePrice": { "prefix": false, "text": "£12.00/kg" }, "discount": { "discountHasStar": false, "discountText": "SAVE 15%", "fromNormalPriceForLidlPlus": false, "fromRecommendedPrice": false, "showDiscount": false, "showFrom": false, "showPercentage": false, "showUpTo": false }, "displayedCurrency": "£", "hasStar": false, "hasVat": false, "oldPrice": 0, "packaging": { "text": "Regular price £0.99" }, "price": 0.84, "priceTheme": "white_yellow", "specialTaxes": [], "superscript": "" } } ], "guaranteeLabels": [], "havingPrice": true, "ians": [ "213279" ], "canonicalPath": "/p/halloween-milk-chocolate-balls/p10055407", "timezoneId": "Europe/London", "awards": [], "ribbons": [], "regionsPrices": {}, "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg", "storeStartDate": 1790809200, "preventSelling": false, "renderedTs": 1790215745, "dealOfDay": { "active": false }, "image_V1": { "accessibility": "A mesh bag of Halloween milk chocolates with spooky skull, pumpkin, and eyeball designs.", "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg" }, "cutoutimageV2": [], "havingThreesixty": false, "gs1Attributes": [], "imageList_V1": [ { "accessibility": "A mesh bag of Halloween milk chocolates with spooky skull, pumpkin, and eyeball designs.", "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg" } ], "erpNumber": "10055407", "designTheme": "default", "imageList": [ "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg" ], "zones": {}, "hasColors": false, "flashSales": false, "price": { "currencyCode": "GBP", "currencyCodeSecond": "", "currencySymbol": "£", "currencySymbolSecond": "", "displayedCurrency": "£", "hasStar": false, "hasVat": false, "specialTaxes": [], "variantsHaveDifferentPrices": false }, "storeEndDate": 1791413999, "highlightedSeals": 0, "ageRestriction": false, "brand": { "name": "HALLOWEEN", "showBrand": true, "url": "/q/search?q=halloween" }, "store": false, "quickAddToCart": false, "fullTitle": "HALLOWEEN Milk Chocolate Balls", "productOrigin": "progress_event", "seals": [], "isUsedProduct": false, "multipack": false, "stockAvailability": { "availabilityIndicator": 0, "backInStockNotification": false, "backInStockNotificationSoldOut": false, "badgeInfo": { "badges": [ { "text": "In store from 01.10", "type": "IN_STORE_FROM_FUTURE_DATE_RANGE" } ] }, "badgeInfoV2": [ { "badges": [ { "text": "In store from 01.10", "type": "IN_STORE_FROM_FUTURE_DATE_RANGE" } ], "validFrom": 1790809200, "validUntil": 1791413999 } ], "minOrderableQuantity": 1, "onlineAvailable": false }, "displayFreeDelivery": false, "productType": "RETAIL", "disclaimers": [ { "id": "code_10055407_c83ed87a", "type": "CODE", "value": "Basic" } ], "title": "Milk Chocolate Balls", "itemId": 10055407, "canonicalUrl": "/p/halloween-milk-chocolate-balls/p10055407", "havingVideos": false, "online": false }, "eventType": "GRIDBOX", "id": "10055407", "language": "en", "meta": { "campaignPaths": [ [ { "hiddenCategory": false, "id": "10030004", "name": "Halloween Party Food", "url": "/c/halloween-party-food-and-sweets/a10030004" } ], [ { "hiddenCategory": false, "id": "10053070", "name": "Lidl Plus Offers - Upcoming Deals", "url": "/c/lidl-plus-offers-upcoming/a10053070" } ] ], "categoryPaths": [], "fullTitle": "HALLOWEEN Milk Chocolate Balls", "lists": [ 6063, 6065 ], "preview": false, "retailLists": [ [ { "id": 6063, "productSortIndex": 26 }, { "id": 6065, "productSortIndex": 9 } ] ], "wonCategoryBreadcrumbs": [ [ { "hiddenCategory": false, "id": "10068374", "name": "Food & Drink", "url": "/c/food-drink/s10068374" }, { "hiddenCategory": false, "id": "10096205", "name": "Confectionery & Snacks", "url": "/h/confectionery-snacks/h10096205" }, { "hiddenCategory": false, "id": "10096206", "name": "Chocolate & Chocolate Bars", "url": "/h/chocolate-chocolate-bars/h10096206" } ] ], "worldOfNeeds": [ { "code": "174410", "isMain": true, "name": "Chocolate products", "parent": "1744", "superCategories": [ { "code": "1744", "name": "Candy & Snacks", "parent": "17" }, { "code": "17", "name": "Food and near food", "parent": "0" }, { "code": "0", "name": "Worlds of need", "parent": "" } ] } ] }, "productId": 10055407, "sequence": 1790215745917073 }, "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg", "product_type": "RETAIL", "title": "HALLOWEEN Milk Chocolate Balls", "url": "https://www.lidl.co.uk/p/halloween-milk-chocolate-balls/p10055407" }, { "brand": "J.D. GROSS", "code": "10055053", "currency": "GBP", "description": "Get 20% off the regular price with the Lidl Plus app 24.09 – 07.10", "gridbox": { "action": "UPDATE", "country": "GB", "data": { "productId": 10055053, "energyLabels": [], "isLidlGiftCard": false, "keyfacts": { "analyticsCategory": "Food", "description": "Get 20% off the regular price with the Lidl Plus app 24.09 – 07.10", "fullTitle": "J.D. GROSS Dark Chocolate", "moreDetails": "More details", "supplementalDescription": "125g", "title": "Dark Chocolate", "wonCategoryPrimary": "Worlds of need/Food and near food/Candy & Snacks/Chocolate products", "wonCategoryPrimaryPath": "0/17/1744/174410" }, "category": "Food", "lidlPlus": [ { "highlightText": "SAVE 20%", "lidlPlusText": "With Lidl Plus", "price": { "basePrice": { "prefix": false, "text": "£15.92/kg" }, "discount": { "discountHasStar": false, "discountText": "SAVE 20%", "fromNormalPriceForLidlPlus": false, "fromRecommendedPrice": false, "showDiscount": false, "showFrom": false, "showPercentage": false, "showUpTo": false }, "displayedCurrency": "£", "hasStar": false, "hasVat": false, "oldPrice": 0, "packaging": { "text": "Regular price £2.49" }, "price": 1.99, "priceTheme": "white_yellow", "specialTaxes": [], "superscript": "" } } ], "guaranteeLabels": [], "havingPrice": true, "ians": [ "28823" ], "canonicalPath": "/p/j-d-gross-dark-chocolate/p10055053", "timezoneId": "Europe/London", "awards": [], "ribbons": [], "regionsPrices": {}, "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg", "storeStartDate": 1790204400, "preventSelling": false, "renderedTs": 1790204615, "dealOfDay": { "active": false }, "image_V1": { "accessibility": "Three bars of dark chocolate with 90%, 70%, and 85% cocoa content.", "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg" }, "cutoutimageV2": [], "havingThreesixty": false, "gs1Attributes": [], "imageList_V1": [ { "accessibility": "Three bars of dark chocolate with 90%, 70%, and 85% cocoa content.", "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg" } ], "erpNumber": "10055053", "designTheme": "default", "imageList": [ "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg" ], "zones": {}, "hasColors": false, "flashSales": false, "price": { "currencyCode": "GBP", "currencyCodeSecond": "", "currencySymbol": "£", "currencySymbolSecond": "", "displayedCurrency": "£", "hasStar": false, "hasVat": false, "specialTaxes": [], "variantsHaveDifferentPrices": false }, "storeEndDate": 1790809199, "highlightedSeals": 0, "ageRestriction": false, "brand": { "name": "J.D. GROSS", "showBrand": true, "url": "/q/search?q=j.d.+gross" }, "store": true, "quickAddToCart": false, "fullTitle": "J.D. GROSS Dark Chocolate", "productOrigin": "progress_event", "seals": [], "isUsedProduct": false, "multipack": false, "stockAvailability": { "availabilityIndicator": 0, "backInStockNotification": false, "backInStockNotificationSoldOut": false, "badgeInfo": { "badges": [ { "text": "Available in store now", "type": "IN_STORE_TODAY_DATE_RANGE" } ] }, "badgeInfoV2": [ { "badges": [ { "text": "Available in store now", "type": "IN_STORE_TODAY_DATE_RANGE" } ], "validFrom": 1790204400, "validUntil": 1790809199 } ], "minOrderableQuantity": 1, "onlineAvailable": false }, "displayFreeDelivery": false, "productType": "RETAIL", "disclaimers": [ { "id": "code_10055053_63191637", "type": "CODE", "value": "Basic" } ], "title": "Dark Chocolate", "itemId": 10055053, "canonicalUrl": "/p/j-d-gross-dark-chocolate/p10055053", "havingVideos": false, "online": false }, "eventType": "GRIDBOX", "id": "10055053", "language": "en", "meta": { "campaignPaths": [ [ { "hiddenCategory": false, "id": "10053070", "name": "Lidl Plus Offers - Upcoming Deals", "url": "/c/lidl-plus-offers-upcoming/a10053070" } ] ], "categoryPaths": [], "fullTitle": "J.D. GROSS Dark Chocolate", "lists": [ 6054, 6063 ], "preview": false, "retailLists": [ [ { "id": 6054, "productSortIndex": 44 }, { "id": 6063, "productSortIndex": 49 } ] ], "wonCategoryBreadcrumbs": [ [ { "hiddenCategory": false, "id": "10068374", "name": "Food & Drink", "url": "/c/food-drink/s10068374" }, { "hiddenCategory": false, "id": "10096205", "name": "Confectionery & Snacks", "url": "/h/confectionery-snacks/h10096205" }, { "hiddenCategory": false, "id": "10096206", "name": "Chocolate & Chocolate Bars", "url": "/h/chocolate-chocolate-bars/h10096206" } ] ], "worldOfNeeds": [ { "code": "174410", "isMain": true, "name": "Chocolate products", "parent": "1744", "superCategories": [ { "code": "1744", "name": "Candy & Snacks", "parent": "17" }, { "code": "17", "name": "Food and near food", "parent": "0" }, { "code": "0", "name": "Worlds of need", "parent": "" } ] } ] }, "productId": 10055053, "sequence": 1790204615760361 }, "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg", "product_type": "RETAIL", "title": "J.D. GROSS Dark Chocolate", "url": "https://www.lidl.co.uk/p/j-d-gross-dark-chocolate/p10055053" }, { "code": "10052239", "currency": "GBP", "gridbox": { "action": "UPDATE", "country": "GB", "data": { "productId": 10052239, "energyLabels": [], "isLidlGiftCard": false, "keyfacts": { "analyticsCategory": "Food", "fullTitle": "Kinder Chocolate", "moreDetails": "More details", "supplementalDescription": "300g (24 x 12,5g)", "title": "Kinder Chocolate", "wonCategoryPrimary": "Worlds of need/Food and near food/Candy & Snacks/Chocolate products", "wonCategoryPrimaryPath": "0/17/1744/174410" }, "category": "Food", "lidlPlus": [], "guaranteeLabels": [], "havingPrice": true, "ians": [ "5209117" ], "canonicalPath": "/p/kinder-chocolate/p10052239", "timezoneId": "Europe/London", "awards": [], "ribbons": [], "regionsPrices": {}, "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg", "storeStartDate": 1790809200, "preventSelling": false, "renderedTs": 1790215724, "dealOfDay": { "active": false }, "image_V1": { "accessibility": "A packet of Kinder Chocolate on a white background ", "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg" }, "cutoutimageV2": [], "havingThreesixty": false, "gs1Attributes": [], "imageList_V1": [ { "accessibility": "A packet of Kinder Chocolate on a white background ", "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg" } ], "erpNumber": "10052239", "designTheme": "default", "imageList": [ "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg" ], "zones": {}, "hasColors": false, "flashSales": false, "price": { "basePrice": { "prefix": false, "text": "£11.63/kg" }, "currencyCode": "GBP", "currencyCodeSecond": "", "currencySymbol": "£", "currencySymbolSecond": "", "displayedCurrency": "£", "hasStar": false, "hasVat": false, "oldPrice": 0, "price": 3.49, "priceTheme": "white_red", "specialTaxes": [], "variantsHaveDifferentPrices": false }, "storeEndDate": 1793663999, "highlightedSeals": 0, "ageRestriction": false, "brand": { "showBrand": false }, "store": false, "quickAddToCart": false, "fullTitle": "Kinder Chocolate", "productOrigin": "progress_event", "seals": [], "isUsedProduct": false, "multipack": false, "stockAvailability": { "availabilityIndicator": 0, "backInStockNotification": false, "backInStockNotificationSoldOut": false, "badgeInfo": { "badges": [ { "text": "In store from 01.10", "type": "IN_STORE_FROM_FUTURE_DATE_RANGE" } ] }, "badgeInfoV2": [ { "badges": [ { "text": "In store from 01.10", "type": "IN_STORE_FROM_FUTURE_DATE_RANGE" } ], "validFrom": 1790809200, "validUntil": 1793663999 } ], "minOrderableQuantity": 1, "onlineAvailable": false }, "displayFreeDelivery": false, "productType": "RETAIL", "disclaimers": [ { "id": "code_10052239_eb9336d2", "type": "CODE", "value": "Basic" } ], "title": "Kinder Chocolate", "itemId": 10052239, "canonicalUrl": "/p/kinder-chocolate/p10052239", "havingVideos": false, "online": false }, "eventType": "GRIDBOX", "id": "10052239", "language": "en", "meta": { "campaignPaths": [ [ { "hiddenCategory": false, "id": "10030004", "name": "Halloween Party Food", "url": "/c/halloween-party-food-and-sweets/a10030004" } ] ], "categoryPaths": [], "fullTitle": "Kinder Chocolate", "lists": [ 6065 ], "preview": false, "retailLists": [ [ { "id": 6065, "productSortIndex": 16 } ] ], "wonCategoryBreadcrumbs": [ [ { "hiddenCategory": false, "id": "10068374", "name": "Food & Drink", "url": "/c/food-drink/s10068374" }, { "hiddenCategory": false, "id": "10096205", "name": "Confectionery & Snacks", "url": "/h/confectionery-snacks/h10096205" }, { "hiddenCategory": false, "id": "10096206", "name": "Chocolate & Chocolate Bars", "url": "/h/chocolate-chocolate-bars/h10096206" } ] ], "worldOfNeeds": [ { "code": "174410", "isMain": true, "name": "Chocolate products", "parent": "1744", "superCategories": [ { "code": "1744", "name": "Candy & Snacks", "parent": "17" }, { "code": "17", "name": "Food and near food", "parent": "0" }, { "code": "0", "name": "Worlds of need", "parent": "" } ] } ] }, "productId": 10052239, "sequence": 1790215724220556 }, "image": "https://imgproxy-retcat.assets.schwarz/[redacted:token]/sm:0/exar:1:ce/w:427/h:320/cz/M6Ly9wcm9kLWNhd/[redacted:token]/[redacted:token].jpg", "price": 3.49, "product_type": "RETAIL", "title": "Kinder Chocolate", "url": "https://www.lidl.co.uk/p/kinder-chocolate/p10052239" } ], "numFound": 20, "offset": 0, "query": "chocolate" }