🛒 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"
  }
}

---

🧾 Campos estándar para comparar cadenas (nuevo)

Además de los campos de siempre, cada producto trae columnas iguales en los scrapers de Éxito, Carulla, Jumbo y Olímpica, para cruzarlos sin limpiar datos:

Campo	Qué es
Cadena	Olímpica
EAN	Código de barras (EAN/GTIN) con dígito de control verificado. Es la llave para comparar el mismo producto entre cadenas.
SKU, Referencia_Cadena	Identificadores internos de la tienda.
Precio_Lista, Precio_Venta, Descuento_Pct, En_Promocion	Precios numéricos y descuento calculado.
Promociones	Nombres de las promociones activas (cuando la tienda las publica).
Contenido_Total, Unidad_Base, Unidades_Empaque	Contenido total del empaque en g, ml o unidades (ej. bolsa x6 de 1.100 ml = 6.600 ml).
Precio_Kg_L	Precio por kilo, por litro o por unidad: compara presentaciones distintas.
Disponible, Stock_Disponible	Disponibilidad online (el stock solo es informativo por debajo de 10.000).
Vendedor, Vendido_Por_Cadena	Quién vende: la cadena o un vendedor del marketplace.
Departamento, Categoria_Nivel_2, Categoria_Nivel_3, Ruta_Categoria	Árbol de categorías de la tienda.
Imagen_URL, Fecha_Extraccion, Moneda	Imagen, fecha UTC de la lectura y moneda (COP).

🧺 Modo canasta: los mismos productos en todas las cadenas (nuevo)

Ideal para monitorear precios todos los días con la misma canasta:

{
  "eans": ["7702001029716", "7702511000045"],
  "terms": ["leche deslactosada", "café molido"],
  "max_items_per_term": 50
}

• eans: busca cada código de barras y devuelve ese producto exacto. Los que la cadena no vende quedan en el registro OUTPUT como no_encontrados.
• terms: toma los primeros max_items_per_term productos de cada búsqueda, sin repetir, con el mismo orden en todas las cadenas.
• Si usas cualquiera de los dos, el actor no hace la búsqueda normal. Corre la misma entrada en los cuatro scrapers y une los resultados por EAN.

⚙️ 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