# Olimpica Scraper (`knowten/olimpica-scraper`) Actor

Scraper ultrarrápido y avanzado para olimpica.com (Colombia). Extrae catálogo completo, productos, precios, descuentos, marcas y especificaciones técnicas.

- **URL**: https://apify.com/knowten/olimpica-scraper.md
- **Developed by:** [Knowten](https://apify.com/knowten) (community)
- **Categories:** E-commerce, Automation
- **Stats:** 1 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $1.00 / 1,000 resultados

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## 🛒 Olímpica Supermarket & Retail Scraper (Colombia)

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-orange.svg)](https://apify.com)
[![Python 3.11](https://img.shields.io/badge/Python-3.11-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```json
{
  "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

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

#### Example 2: Scrape Direct Olímpica URL

```json
{
  "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

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

***

### 🛠️ Integration via Apify Client

#### Python SDK

```python
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

# Actor input Schema

## `search_term` (type: `string`):

Palabra clave o término de búsqueda en Olímpica (ej. 'tv', 'whisky', 'leche', 'cerveza').

## `startUrls` (type: `array`):

Lista de URLs directas de Olímpica (ej. 'https://www.olimpica.com/tv?\_q=tv\&map=ft', 'https://www.olimpica.com/supermercado/licores', etc.).

## `max_items` (type: `integer`):

Cantidad máxima de productos a extraer por búsqueda. Usa 0 para extraer todo el catálogo disponible.

## `discovery_mode` (type: `boolean`):

Si se activa (true), extrae únicamente la lista de filtros, marcas y facetas disponibles para la búsqueda (sin extraer los detalles de productos).

## `category_1` (type: `string`):

Ruta o slug de la categoría principal (ej. '/supermercado/licores', '/tecnologia/televisores', 'tecnologia').

## `category_2` (type: `string`):

Slug de la categoría secundaria (ej. 'televisores', 'licores').

## `brand` (type: `string`):

Nombre de la marca para filtrar (ej. 'Samsung', 'LG', 'Pilsen').

## `price_range` (type: `string`):

Rango de precios en formato 'Min TO Max' o 'Min:Max' (ej. '2601560 TO 10499900' o '1000000:5000000').

## `min_price` (type: `integer`):

Precio mínimo numérico (ej. 50000).

## `max_price` (type: `integer`):

Precio máximo numérico (ej. 2000000).

## `custom_filters` (type: `string`):

Filtros VTEX adicionales en formato 'fq' o 'Clave=Valor' separados por coma.

## `sort` (type: `string`):

Criterio de ordenamiento de los productos.

## `proxyConfiguration` (type: `object`):

Configura el proxy de Apify para prevenir bloqueos de IP en extracciones continuas.

## Actor input object example

```json
{
  "max_items": 100,
  "discovery_mode": false,
  "sort": "score_desc",
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

Resultados de la extracción formateados en JSON, CSV o Excel

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("knowten/olimpica-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("knowten/olimpica-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{}' |
apify call knowten/olimpica-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=knowten/olimpica-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/v98E732JeEKtcXPbV/builds/8Jigttnd9LvjhfrxI/openapi.json