# Mercado Libre Full Product Scraper (`ultramarine_freezer/meli`) Actor

Extrae datos completos de productos de Mercado Libre en 18 países de Latinoamérica. Obtén precios, reseñas, stock, imágenes y más de 30 campos con traducción automática de idioma (ES/PT).

- **URL**: https://apify.com/ultramarine\_freezer/meli.md
- **Developed by:** [JIGSAW](https://apify.com/ultramarine_freezer) (community)
- **Categories:** E-commerce, Automation
- **Stats:** 128 total users, 1 monthly users, 99.4% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$20.00/month + usage

To use this Actor, you pay a monthly rental fee to the developer. The rent is subtracted from your prepaid usage every month after the free trial period. You also pay for the Apify platform usage, which gets cheaper the higher Apify subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#rental-actors

## 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

## Mercado Libre Scraper — El más completo 🚀

Scraper **profesional y multipropósito** de Mercado Libre / Mercado Livre para los **18 países** de Latinoamérica, con traducción automática ES/PT y **45+ campos** por producto. Busca por keyword, o pega URLs de producto, categoría o **tienda**. Extrae vendedor completo (reputación, MercadoLíder, tienda oficial, seguidores), cantidad vendida, envío FULL, specs y reseñas **estructuradas**, cuotas, y precio en **USD**.

### ✨ Qué lo hace el mejor

- 🌎 **18 países** (vs 7–9 de la competencia) con traducción automática ES/PT opcional.
- 🎯 **4 formas de entrada** en un mismo run: keyword, URL de producto, URL de categoría/listado, y URL de **tienda/vendedor** — auto-clasificadas.
- 🏪 **Modo tienda**: perfil de la tienda (nombre, seguidores, tipo, oficial) + su catálogo completo.
- 👤 **Datos de vendedor**: reputación (`5_green`), **MercadoLíder** (silver/gold/platinum), tienda oficial.
- 📈 **Cantidad vendida** y **posición** en resultados.
- 🚚 **Envío FULL** (MercadoEnvíos Full) además de envío gratis.
- 🧾 **Specs, variantes y reseñas estructuradas** (con fecha, país, likes y fotos).
- 💵 **Precio en USD** automático (tasas del día) para comparar entre países.
- ⚡ **Modo listado rápido** para monitoreo de precios masivo y barato.
- 🛡️ **Anti-bloqueo**: huella de navegador realista, geo por país y **rotación de IP** ante el gate anti-bot de ML.

### 🚀 Inicio rápido

#### Búsqueda por keyword

```json
{ "busqueda": "iphone 15", "paises": ["MX", "BR", "AR"], "maxItems": 50 }
```

#### URLs directas (producto / categoría / tienda)

```json
{
  "startUrls": [
    "https://www.mercadolibre.com.mx/apple-iphone-15-256-gb-negro/p/MLM27172669",
    "https://listado.mercadolibre.com.ar/celulares",
    "https://www.mercadolibre.com.mx/tienda/apple"
  ]
}
```

#### Monitoreo rápido de precios (solo listado)

```json
{ "busqueda": "laptop gaming", "paises": ["MX"], "soloListado": true, "maxItems": 500 }
```

#### Con precio en USD

```json
{ "busqueda": "notebook", "paises": ["MX", "BR"], "convertirUSD": true, "maxItems": 30 }
```

### ⚙️ Parámetros de entrada

| Campo | Tipo | Descripción |
|-------|------|-------------|
| `busqueda` | string | Término a buscar por keyword. Vacío si solo usas `startUrls`. |
| `startUrls` | array | URLs de producto / categoría / tienda (auto-clasificadas; el país se detecta del dominio). |
| `paises` | array | Países para la búsqueda por keyword (18 disponibles). |
| `soloListado` | boolean | Modo rápido: solo tarjetas del listado, sin entrar a cada producto. |
| `traducirColumnas` | boolean | Columnas/valores en portugués para Brasil. Off = dataset consistente en español. |
| `maxReviews` | integer | Reseñas detalladas por producto (0 desactiva). |
| `convertirUSD` | boolean | Agrega `precio_usd` con tasas del día. |
| `tasasUSD` | object | Tasas manuales opcionales, ej. `{"MXN": 0.058}`. |
| `maxItems` | integer | Máx. productos por país (0 = ilimitado). |
| `maxConcurrency` | integer | Requests en paralelo (2–5 recomendado). |
| `separarDatasetsPorPais` | boolean | Genera un JSON por país además del unificado. |
| `proxyConfiguration` | object | Proxies de Apify (residenciales recomendados). |
| `externalProxies` | array | Proxies externos propios (opcional). |

### 📋 Campos de salida (45+)

**Fila**: `tipo_fila` (`producto` o `perfil_tienda`), `pais_origen`, `fecha_scrape`, `posicion`, `categoria`
**Identidad**: `titulo`, `url`, `product_id`, `sku`, `marca`, `modelo`, `condicion`
**Precios**: `precio_actual`, `precio_original`, `descuento_porcentaje`, `moneda`, `precio_usd`, `cuotas`, `cuotas_detalle`
**Stock/ventas**: `stock`, `cantidad_disponible`, `cantidad_vendida`
**Vendedor**: `vendedor`, `tienda_oficial`, `tienda_oficial_nombre`, `reputacion_vendedor`, `mercadolider`
**Tienda (perfil)**: `nombre_tienda`, `seguidores`, `tipo_tienda`
**Envío**: `envio`, `envio_gratis`, `envio_full`, `envio_tipo`
**Ficha**: `descripcion`, `caracteristicas`, `especificaciones` `[{nombre, valor}]`, `variantes` `[{tipo, seleccion, opciones}]`, `variaciones`, `imagenes`
**Reseñas / Q\&A**: `estrellas`, `reviews_count`, `reviews_texto`, `reviews_detalle` `[{estrellas, texto, fecha, pais, likes, media}]`, `preguntas`

En Brasil, con `traducirColumnas: true`, las columnas y valores salen en portugués (`preco_atual`, `condicao`, `Novo`, `frete_full`, etc.).

### 🏪 Modo tienda

Pega una URL de tienda (`/tienda/...`, `/perfil/...`) en `startUrls` y el actor devuelve:

1. Una **fila de perfil** (`tipo_fila: perfil_tienda`) con `nombre_tienda`, `seguidores`, `tipo_tienda`, `tienda_oficial`.
2. El **catálogo** de esa tienda, hasta `maxItems`, con la ficha completa de cada producto (`tipo_fila: producto`).

```json
{ "startUrls": ["https://www.mercadolibre.com.mx/tienda/apple"], "maxItems": 50 }
```

### 🌎 Países soportados

Argentina, Bolivia, Brasil, Chile, Colombia, Costa Rica, Rep. Dominicana, Ecuador, Guatemala, Honduras, México, Nicaragua, Panamá, Paraguay, Perú, El Salvador, Uruguay y Venezuela.

### 💡 Rendimiento y anti-bloqueo

Motor Playwright con **concurrencia real**, **huella de navegador realista** (fingerprint Chrome), **locale y zona horaria alineados al país del proxy**, **bloqueo de recursos pesados** (imágenes/fuentes/trackers) y extracción de cada ficha en **una sola pasada** al navegador. Mercado Libre bloquea IPs de datacenter y sirve un reto anti-bot en los listados: el actor **rota de IP automáticamente** cuando lo detecta. **Usa siempre proxies residenciales.**

### 📊 Output

Datasets en JSON, CSV, Excel o XML, con vistas predefinidas: **Vista General**, **Vista Detallada** y **Vendedores y Tiendas**.

### ⚠️ Notas

- La reputación del vendedor, MercadoLíder, cantidad vendida y tienda oficial se leen del payload interno de ML con fallback al DOM; su disponibilidad depende de cada publicación.
- El campo `envio` (texto) es una **promesa de entrega dinámica** (depende de la hora, la ubicación del proxy y la sesión); para señales estables usa `envio_gratis` y `envio_full`.
- El Q\&A (`preguntas`) es best-effort: ML lo sirve tras un modal, así que puede venir vacío.
- El modo `soloListado` no incluye ficha profunda (specs, reseñas, vendedor detallado).

***

**Uso comercial permitido.** Este actor no está afiliado a Mercado Libre; extrae solo datos de páginas públicas. El usuario es responsable de cumplir los términos de servicio de Mercado Libre y la normativa de datos aplicable.

# Actor input Schema

## `busqueda` (type: `string`):

Producto a buscar por keyword (ej: iphone 15, laptop gaming). Déjalo vacío si solo usas 'URLs directas'.

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

Pega URLs de Mercado Libre: de producto (/p/MLM...), de categoría/listado (listado.mercadolibre...), o de tienda/vendedor (/tienda/...). Se auto-clasifican y el país se detecta del dominio. Puedes mezclarlas con la búsqueda por keyword.

## `paises` (type: `array`):

Países donde buscar el término. (Para 'URLs directas' el país se detecta solo del dominio.)

## `soloListado` (type: `boolean`):

Si está activo, extrae únicamente los datos de las tarjetas del listado (título, precio, descuento, envío, rating, posición) SIN entrar a cada producto. Mucho más rápido y barato — ideal para monitoreo de precios masivo.

## `traducirColumnas` (type: `boolean`):

Si está activo, las filas de Brasil usan nombres de columna y valores en portugués (preco\_atual, condicao, Novo...). Déjalo DESACTIVADO para un dataset multi-país limpio con columnas consistentes en español.

## `maxReviews` (type: `integer`):

Cuántas reseñas extraer con detalle (estrellas, texto, fecha, país, likes, fotos). Usa 0 para desactivar. Solo aplica en modo detalle.

## `convertirUSD` (type: `boolean`):

Agrega el campo precio\_usd convirtiendo desde la moneda local. Usa tasas en vivo (o las que proveas en 'Tasas USD'). Útil para comparar precios entre países.

## `tasasUSD` (type: `object`):

Opcional: factores manuales moneda→USD, ej: {"MXN": 0.058, "BRL": 0.18, "ARS": 0.001}. Si se deja vacío y 'precio USD' está activo, se obtienen tasas en vivo automáticamente.

## `maxItems` (type: `integer`):

Productos a scrapear por país. Usa 0 para TODO lo disponible (⚠️ modo ilimitado, puede ser costoso).

## `maxConcurrency` (type: `integer`):

Requests en paralelo. 3 (balanceado), 5 (rápido), 2 (ultra estable).

## `separarDatasetsPorPais` (type: `boolean`):

Genera un JSON por país además del dataset unificado.

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

⚠️ Muy recomendado: proxies residenciales para evitar bloqueos. Mercado Libre bloquea IPs de datacenter.

## `externalProxies` (type: `array`):

URLs de proxies premium externos. Formato: http://user:pass@host:port

## Actor input object example

```json
{
  "busqueda": "iphone 15",
  "startUrls": [],
  "paises": [
    "MX"
  ],
  "soloListado": false,
  "traducirColumnas": false,
  "maxReviews": 5,
  "convertirUSD": false,
  "tasasUSD": {},
  "maxItems": 5,
  "maxConcurrency": 3,
  "separarDatasetsPorPais": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  },
  "externalProxies": []
}
```

# 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 = {
    "busqueda": "iphone 15",
    "startUrls": [],
    "paises": [
        "MX"
    ],
    "maxReviews": 5,
    "maxItems": 5,
    "maxConcurrency": 3,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("ultramarine_freezer/meli").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 = {
    "busqueda": "iphone 15",
    "startUrls": [],
    "paises": ["MX"],
    "maxReviews": 5,
    "maxItems": 5,
    "maxConcurrency": 3,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("ultramarine_freezer/meli").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "busqueda": "iphone 15",
  "startUrls": [],
  "paises": [
    "MX"
  ],
  "maxReviews": 5,
  "maxItems": 5,
  "maxConcurrency": 3,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call ultramarine_freezer/meli --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ultramarine_freezer/meli"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/xTr91sBE3Cjj56g2A/builds/pu5OgNzhkI3elmtpd/openapi.json