# Mercado Libre Scraper LATAM (18 Países) (`doorma_10/mercadolibre-latam-scraper`) Actor

Scraper rápido, confiable y estructurado para Mercado Libre en 18 países de LATAM. Extrae precios oficiales, cuotas, descuentos, vendedores y stock sin proxies obligatorios.

- **URL**: https://apify.com/doorma_10/mercadolibre-latam-scraper.md
- **Developed by:** [Doorman Data Labs](https://apify.com/doorma_10) (community)
- **Features:** Limited permissions
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.70 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## 🛒 Mercado Libre LATAM Scraper (18 Países)

> **Scraper rápido, confiable y estructurado para Mercado Libre en toda América Latina.**\
> Extrae productos, precios oficiales, cuotas detalladas, descuentos, vendedores, reputación y stock de **18 países** sin costos ocultos ni proxies obligatorios.

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-orange?style=flat-square\&logo=apify)](https://apify.com/doorma_10/mercadolibre-latam-scraper)
[![18 Países](https://img.shields.io/badge/MercadoLibre-18%20Pa%C3%ADses-yellow?style=flat-square)](https://www.mercadolibre.com)
[![Motor](https://img.shields.io/badge/Motor-Cheerio%20%7C%20Node%2020-blue?style=flat-square)](https://nodejs.org)
[![Eficiencia](https://img.shields.io/badge/Consumo-Optimizado%20\(256--512MB\)-green?style=flat-square)](https://apify.com)
[![Pricing](https://img.shields.io/badge/Pricing-Pay--Per--Result-success?style=flat-square)](https://apify.com/doorma_10/mercadolibre-latam-scraper)

***

### ⚡ ¿Por qué elegir este Scraper?

- 💰 **Arquitectura liviana y económica:** Basado en extracción HTTP optimizada con Cheerio. No requiere renderizado de navegadores pesados tipo Puppeteer ni consume gigabytes de RAM. Corre eficientemente desde **256 MB de memoria**, ideal para grandes volúmenes de datos con consumo mínimo de plataforma.
- ⚡ **Alta velocidad y latencia mínima (< 5 segundos):** Obtiene entre 20 y 50 resultados por búsqueda en cuestión de segundos mediante la extracción directa de los metadatos y modelos de datos hidratados de Mercado Libre.
- 🎯 **Precios 100% auténticos y transparentes:** Captura fielmente el precio publicado, precio de lista anterior, porcentaje de descuento y el desglose de cuotas (`installments`) con o sin interés, tal como lo ve el comprador en la web.
- 🌎 **Cobertura total en 18 países:** Soporte nativo para todos los portales de Mercado Libre en América Latina con un selector simple de 2 letras (`AR`, `MX`, `BR`, `CL`, `CO`, etc.).
- 📦 **Modo Dual (Búsqueda Rápida o Detalle Profundo):** Extrae catálogos completos a máxima velocidad o activa `extractProductDetails: true` para obtener fotos en alta resolución, descripción completa, atributos técnicos y reputación del vendedor.
- 🛡️ **Detección y reporte estructurado de incidencias:** Si una consulta es restringida o sufre un timeout, el Actor no falla en silencio: registra una fila estructurada con `tipoRegistro: "bloqueo"` o `"error"` para que tus procesos automatizados tomen acción de inmediato.

***

### 📋 ¿Qué datos extrae exactamente?

Por cada producto, el scraper extrae un objeto JSON normalizado con los siguientes campos clave:

- 🏷️ **Identificadores oficiales:** `itemId` (ID de publicación), `catalogProductId` (ID de catálogo), `userProductId` (ID de vendedor), `url` canónica y `itemUrl`.
- 💵 **Precios y Financiación:** `price` (precio actual), `originalPrice` (precio tachado), `discountPercentage` (% de descuento), `currency` (moneda ISO), y `installments` (cantidad de cuotas, monto por cuota, costo total y bandera `noInterest`).
- 📈 **Métricas de Demanda:** `soldQuantity` (unidades vendidas aproximadas), `rating` (puntuación media 1 a 5), `reviewCount` (total de opiniones) y `availableQuantity` (stock disponible cuando es público).
- 🚚 **Logística y Entrega:** `freeShipping` (envío gratis sí/no), `isFull` (Mercado Envíos Full), `shippingText` (plazo o condición de entrega) y `isInternational` (compra internacional CBT).
- 🏪 **Vendedor y Reputación:** `sellerName`, `sellerId`, `isOfficialStore` (tienda oficial verificada) y `sellerReputation` (termómetro y nivel MercadoLíder Platinum/Gold/Silver).
- 🔍 **Auditoría y Búsqueda:** `searchQuery`, `position` (posición en el listado), `isSponsored` (publicación orgánica vs. promocionada), `highlight` (etiquetas como "MÁS VENDIDO"), `categoryId`, `domainId`, `country`, `siteId` y `scrapedAt` (timestamp ISO).

> Al activar `extractProductDetails: true`, añade además: galería completa de fotos HD (`images`), ficha técnica (`attributes`), descripción textual completa (`description`) y políticas de devolución.

***

### 🌎 Países y Marketplaces Soportados

| Código | País | Dominio | Site ID |
| :---: | :--- | :--- | :---: |
| `AR` | 🇦🇷 Argentina | `mercadolibre.com.ar` | `MLA` |
| `MX` | 🇲🇽 México | `mercadolibre.com.mx` | `MLM` |
| `BR` | 🇧🇷 Brasil | `mercadolivre.com.br` | `MLB` |
| `CL` | 🇨🇱 Chile | `mercadolibre.cl` | `MLC` |
| `CO` | 🇨🇴 Colombia | `mercadolibre.com.co` | `MCO` |
| `UY` | 🇺🇾 Uruguay | `mercadolibre.com.uy` | `MLU` |
| `PE` | 🇵🇪 Perú | `mercadolibre.com.pe` | `MPE` |
| `EC` | 🇪🇨 Ecuador | `mercadolibre.com.ec` | `MEC` |
| `BO` | 🇧🇴 Bolivia | `mercadolibre.com.bo` | `MBO` |
| `CR` | 🇨🇷 Costa Rica | `mercadolibre.co.cr` | `MCR` |
| `DO` | 🇩🇴 República Dominicana | `mercadolibre.com.do` | `MRD` |
| `GT` | 🇬🇹 Guatemala | `mercadolibre.com.gt` | `MGT` |
| `HN` | 🇭🇳 Honduras | `mercadolibre.com.hn` | `MHN` |
| `NI` | 🇳🇮 Nicaragua | `mercadolibre.com.ni` | `MNI` |
| `PA` | 🇵🇦 Panamá | `mercadolibre.com.pa` | `MPA` |
| `PY` | 🇵🇾 Paraguay | `mercadolibre.com.py` | `MPY` |
| `SV` | 🇸🇻 El Salvador | `mercadolibre.com.sv` | `MSV` |
| `VE` | 🇻🇪 Venezuela | `mercadolibre.com.ve` | `MLV` |

***

### 💳 Modelo de Precios (Pricing)

Este Actor utiliza el modelo **Pay-Per-Result** (pago por resultado extraído):

- **Sin costo de inicio:** `$0.00` por iniciar la corrida (`Actor start`).
- **Solo pagás por lo que extraés:** Tarifa transparente por cada 1.000 resultados en el dataset.
- **Sin proxies obligatorios:** Funciona con conexión directa optimizada, evitando cargos extra por tráfico de proxy en búsquedas habituales.

***

### 📥 Parámetros de Entrada (`input_schema.json`)

El Actor acepta tanto términos de búsqueda por palabras clave (`searchTerms`) como URLs directas de Mercado Libre (`startUrls`):

| Parámetro | Tipo | Por defecto | Descripción |
| :--- | :---: | :---: | :--- |
| `searchTerms` | `array[string]` | `["celular"]` | Lista de palabras clave o productos a buscar (ej: `["notebook", "auriculares bluetooth"]`). |
| `country` | `string` | `"AR"` | Código ISO de 2 letras del país destino (`AR`, `MX`, `BR`, etc.). |
| `startUrls` | `array[object]` | `[]` | Lista de URLs directas (búsquedas personalizadas, categorías, tiendas oficiales o links directos). |
| `maxResults` | `integer` | `50` | Cantidad máxima de productos a recolectar por cada término o URL. |
| `extractProductDetails` | `boolean` | `false` | Si está en `true`, abre cada producto para extraer ficha técnica, fotos HD y descripción. |
| `sort` | `string` | `"Más relevantes"` | Criterio de ordenación: `"Más relevantes"`, `"Menor precio"` o `"Mayor precio"`. |
| `condition` | `string` | `"all"` | Filtro por condición: `"all"` (todos), `"new"` (nuevos) o `"used"` (usados). |
| `freeShippingOnly` | `boolean` | `false` | Si está activo, filtra únicamente publicaciones con envío gratuito. |
| `officialStoresOnly` | `boolean` | `false` | Filtra únicamente tiendas oficiales verificadas. |
| `promoted` | `boolean` | `false` | Si está activo, incluye también publicaciones patrocinadas / publicidad. |
| `maxPages` | `integer` | `1` | Límite de páginas de resultados a recorrer por cada término. |
| `includeReviews` | `boolean` | `false` | Incluye reseñas y comentarios de compradores en los productos enriquecidos. |
| `proxyConfiguration` | `object` | `{ "useApifyProxy": false }` | Permite usar proxies de Apify para scraping masivo de alto volumen. |

#### Ejemplo de Entrada (`JSON`)

```json
{
  "searchTerms": [
    "samsung galaxy",
    "notebook lenovo"
  ],
  "country": "AR",
  "maxResults": 30,
  "sort": "Más relevantes",
  "condition": "all",
  "freeShippingOnly": false,
  "extractProductDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

***

### 📤 Formato de Salida (`Dataset`)

Ejemplo de registro generado en el Dataset de Apify:

```json
{
  "itemId": "MLA2258462987",
  "catalogProductId": "MLA68212479",
  "userProductId": "MLAU5795809912",
  "title": "Samsung Galaxy A57 5G Awesome Gray",
  "url": "https://www.mercadolibre.com.ar/samsung-galaxy-a57-5g-awesome-gray/p/MLA68212479",
  "itemUrl": "https://articulo.mercadolibre.com.ar/MLA-2258462987",
  "thumbnail": "https://http2.mlstatic.com/D_NQ_NP_773139-MLA111298497274_052026-O.webp",
  "brand": "Samsung",
  "model": "A57 5G",
  "price": 939000,
  "currency": "ARS",
  "originalPrice": 1050000,
  "discountPercentage": 10,
  "installments": {
    "quantity": 6,
    "amount": 181696,
    "total": 1090176,
    "noInterest": true,
    "text": "Cuota promocionada en 6 cuotas de ARS 181.696"
  },
  "noTaxesPrice": null,
  "unitPrice": null,
  "rating": 4.9,
  "reviewCount": 128,
  "soldQuantity": 1000,
  "availableQuantity": 50,
  "condition": "new",
  "freeShipping": true,
  "isFull": true,
  "shippingText": "Llega gratis mañana con Full",
  "isInternational": false,
  "sellerName": "Samsung Oficial",
  "sellerId": "123456789",
  "sellerReputation": "MercadoLíder Platinum (Verde)",
  "isOfficialStore": true,
  "highlight": "MÁS VENDIDO",
  "promotions": null,
  "variationsText": "6 colores disponibles",
  "categoryId": "MLA1055",
  "domainId": "MLA-CELLPHONES",
  "position": 1,
  "isSponsored": false,
  "searchQuery": "samsung galaxy",
  "searchUrl": "https://listado.mercadolibre.com.ar/samsung-galaxy",
  "totalResults": 2450,
  "country": "AR",
  "siteId": "MLA",
  "scrapedAt": "2026-11-13T12:13:13.434Z"
}
```

***

### 💻 Ejemplos de Integración

#### 1. Node.js / TypeScript (`apify-client`)

```bash
npm install apify-client
```

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

const client = new ApifyClient({
    token: 'TU_API_TOKEN',
});

const input = {
    searchTerms: ["auriculares inalámbricos"],
    country: "MX",
    maxResults: 20,
    extractProductDetails: false,
};

(async () => {
    // Iniciar el Actor y esperar el resultado
    const run = await client.actor("doorma_10/mercadolibre-latam-scraper").call(input);

    // Obtener los productos del dataset
    const { items } = await client.dataset(run.defaultDatasetId).listItems();
    console.log(`Se extrajeron ${items.length} productos:`);
    console.log(items);
})();
```

#### 2. Python (`apify-client`)

```bash
pip install apify-client
```

```python
from apify_client import ApifyClient

client = ApifyClient("TU_API_TOKEN")

run_input = {
    "searchTerms": ["cafetera espresso"],
    "country": "CO",
    "maxResults": 25,
    "freeShippingOnly": True,
}

## Ejecutar el Actor sincrónicamente y obtener el dataset
run = client.actor("doorma_10/mercadolibre-latam-scraper").call(run_input=run_input)

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"{item['title']} - {item['currency']} {item['price']}")
```

#### 3. API REST Directa (cURL)

**Ejecución síncrona en una sola petición (espera la finalización y retorna el dataset):**

```bash
curl -X POST "https://api.apify.com/v2/acts/doorma_10~mercadolibre-latam-scraper/run-sync-get-dataset-items?token=TU_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchTerms": ["monitor 27 pulgadas"],
    "country": "CL",
    "maxResults": 10
  }'
```

***

### 🛠️ Casos de Uso

- 📊 **Comparadores de Precios:** Rastreo continuo de precios para detectar ofertas, promociones bancarias y variaciones de stock en tiempo real.
- 🤖 **Agentes de Inteligencia Artificial & RAG:** Alimenta modelos de lenguaje o asistentes de compras con catálogos actualizados en tiempo real.
- 🏷️ **Monitoreo de Competencia:** Analiza la participación de mercado de marcas y vendedores líderes en cada país.
- 📦 **Arbitraje & E-commerce:** Descubre productos más vendidos con insignia Full y evalúa márgenes de reventa transfronterizos.

***

### 📄 Licencia

Desarrollado bajo licencia MIT. Libre para uso comercial, automatizaciones e integraciones en producción.

# Actor input Schema

## `searchTerms` (type: `array`):

Lista de palabras clave a buscar en Mercado Libre. Puedes agregar múltiples términos o editarlos en lote.

## `country` (type: `string`):

Selecciona el país o marketplace regional de Mercado Libre.

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

URLs de búsquedas, categorías, tiendas oficiales o productos directos en Mercado Libre.

## `maxResults` (type: `integer`):

Cantidad máxima de productos a extraer por cada término o enlace.

## `extractProductDetails` (type: `boolean`):

Si está activo, visita la publicación de cada producto para extraer descripción detallada, galería completa de fotos en alta resolución, ficha técnica y reputación del vendedor.

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

Criterio de ordenación para los resultados de búsqueda.

## `condition` (type: `string`):

Filtrar productos por estado o condición.

## `freeShippingOnly` (type: `boolean`):

Si está activo, solo incluye productos que ofrecen envío gratuito.

## `fullShippingOnly` (type: `boolean`):

Si está activo, solo incluye productos despachados mediante fulfillment Mercado Libre Full.

## `officialStoresOnly` (type: `boolean`):

Si está activo, filtra solo publicaciones de tiendas oficiales verificadas.

## `promoted` (type: `boolean`):

Si está activo, incluye también los anuncios y publicaciones promocionadas.

## `maxPages` (type: `integer`):

Cantidad máxima de páginas de búsqueda a paginar automáticamente.

## `includeReviews` (type: `boolean`):

Extrae reseñas y comentarios de compradores en los productos enriquecidos.

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

Configura proxies de Apify o proxies residenciales/datacenter si se requiere distribuir tráfico en alta concurrencia. Por defecto utiliza conexión directa optimizada.

## Actor input object example

```json
{
  "searchTerms": [
    "celular"
  ],
  "country": "AR",
  "maxResults": 50,
  "extractProductDetails": false,
  "sort": "Más relevantes",
  "condition": "all",
  "freeShippingOnly": false,
  "fullShippingOnly": false,
  "officialStoresOnly": false,
  "promoted": false,
  "maxPages": 1,
  "includeReviews": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `defaultDataset` (type: `string`):

Dataset containing the scraped Mercado Libre products and details.

# 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 = {
    "searchTerms": [
        "celular"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("doorma_10/mercadolibre-latam-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 = { "searchTerms": ["celular"] }

# Run the Actor and wait for it to finish
run = client.actor("doorma_10/mercadolibre-latam-scraper").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 '{
  "searchTerms": [
    "celular"
  ]
}' |
apify call doorma_10/mercadolibre-latam-scraper --silent --output-dataset

```

## MCP server setup

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

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/6ofzwDZhF6MOH2qsD/builds/FaWnver2xxojiOW9r/openapi.json
