🛒 Olímpica Supermarket & Retail Scraper (Colombia)

Powerful, fast, and resilient web scraper for Olímpica Colombia (olimpica.com). Extract complete product catalog data, pricing, discounts, technical specifications, brand filters, and price range filters with HTTP browser impersonation and zero anti-bot hassle.

---

🌟 Key Features

• 🔍 Universal Search & Direct URLs (startUrls): Search by keywords (e.g. "tv", "whisky", "leche") or supply direct Olímpica URLs (e.g. https://www.olimpica.com/tv?_q=tv&priceRange=2601560%20TO%2010499900).
• 💰 Price Range Filtering (price_range): Filter products by exact price intervals (e.g. 2601560 TO 10499900 or 1000000:5000000), or via min_price and max_price numeric bounds.
• 🏷️ Brand & Custom VTEX Filters: Apply brand filters (brand: "Samsung") and custom specification parameters (custom_filters).
• 🧭 Filter Discovery Mode (discovery_mode): Discover available categories, brands, price ranges, and technical specifications for any search query before launching full catalog extractions.
• ⚡ High Performance & Anti-Bot Bypass: Utilizes Chrome TLS fingerprint impersonation to bypass rate limits and anti-scraping protections efficiently.
• 📊 Dynamic Data Extraction: Captures product IDs, prices, discounts, PUM unit prices, alcohol degrees, net measure, HTML-cleaned descriptions, and dynamic specification dictionaries.

---

📊 Extracted Data Fields

The scraper outputs structured JSON objects containing all key details:

Field Name	Type	Description
ID	String	Unique VTEX Product ID
Nombre	String	Commercial product name
Marca	String	Brand name
Referencia	String	Product reference code
Categoria	String	Main category / department
Tipo_Producto	String	Dynamic product taxonomy (e.g., Alcohol, Tabaco, Ultraprocesados, Tecnología y Electrodomésticos, General)
Grados_Alcohol	String	Percentage / degrees of alcohol content (if applicable)
Medida	String	Net content / package size
Precio_Original	Number	Original list price before discount
Precio_Final	Number	Current selling price
Descuento_Porcentaje	String	Discount percentage (e.g., 50%)
Precio_Unidad	Number	Price per PUM unit (Unit Price Measurement)
URL_Producto	String	Direct canonical URL to the product page
Descripcion	String	Clean text description (HTML tags stripped)
Informacion_Adicional	Object	Key-value dictionary of dynamic technical specifications

---

💡 JSON Output Example

{
  "ID": "1002407174",
  "Nombre": "TV Stick 4K Android Wifi Con Control Voz Y Apps",
  "Marca": "Generico",
  "Referencia": "IZ20000102969",
  "Categoria": "Reproductores de video",
  "Tipo_Producto": "Tecnología y Electrodomésticos",
  "Grados_Alcohol": "N/A",
  "Medida": "N/A",
  "Precio_Original": 347800.0,
  "Precio_Final": 173900.0,
  "Descuento_Porcentaje": "50%",
  "Precio_Unidad": "N/A",
  "URL_Producto": "https://www.olimpica.com/tv-stick-4k-android-wifi-con-control-voz-y-apps-1002407174/p",
  "Descripcion": "Convierte cualquier televisor en un Smart TV de manera facil y rapida con este TV Stick Android 4K...",
  "Informacion_Adicional": {
    "Marca": "GENERICO",
    "Peso (Kg)": "1 Kg",
    "Garantía": "1 Mes",
    "Resolución de Imagen": "4K",
    "Portátil": "Si"
  }
}

---

⚙️ Input Parameters

Parameter	Type	Default	Description
search_term	String	"tv"	Keyword or search query for Olímpica
startUrls	Array	[]	List of direct Olímpica search or category URLs
max_items	Integer	100	Max products to extract (use 0 for unlimited catalog)
discovery_mode	Boolean	false	Set to true to extract available search filters & options only
category_1	String	""	Department / Category path (e.g., "/supermercado/licores", "tecnologia")
category_2	String	""	Subcategory slug (e.g., "televisores")
brand	String	""	Brand filter (e.g., "Samsung", "LG")
price_range	String	""	Price range interval (e.g., "2601560 TO 10499900")
min_price	Integer	null	Numeric minimum price
max_price	Integer	null	Numeric maximum price
custom_filters	String	""	Custom VTEX fq parameters or Key=Value pairs
sort	String	"score_desc"	Sort order (score_desc, OrderByPriceASC, OrderByPriceDESC, etc.)
proxyConfiguration	Object	{}	Apify Proxy configuration settings

---

🚀 Usage Examples

Example 1: Search TVs with Price Range Filter

{
  "search_term": "tv",
  "price_range": "2601560 TO 10499900",
  "max_items": 50,
  "sort": "OrderByPriceDESC"
}

Example 2: Scrape Direct Olímpica URL

{
  "startUrls": [
    {
      "url": "https://www.olimpica.com/tv?_q=tv&fuzzy=0&initialMap=ft&initialQuery=tv&map=ft&operator=and&priceRange=2601560%20TO%2010499900"
    }
  ],
  "max_items": 100
}

Example 3: Filter Discovery Mode

{
  "search_term": "tv",
  "discovery_mode": true
}

---

🛠️ Integration via Apify Client

Python SDK

from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run_input = {
    "search_term": "tv",
    "price_range": "2601560 TO 10499900",
    "max_items": 50
}

run = client.actor("your-username/olimpica-scraper").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item["Nombre"], item["Precio_Final"])

---

❓ FAQ

Q: How does Price Range Filtering work?
A: You can provide price ranges via price_range (e.g. "2601560 TO 10499900" or "1000000:5000000"), or directly via direct search URLs containing priceRange=.... The scraper seamlessly converts these into native VTEX query filters (fq=P:[min TO max]).

Q: What is Filter Discovery Mode?
A: Setting discovery_mode: true inspects the target query and returns all available brands, departments, price ranges, and technical specifications, allowing you to discover exact values to refine your scraping tasks.

---

📄 License

MIT License