# MercadoLibre Best Sellers Scraper (`stilled_stalagmite/mercadolibre-best-sellers-scraper`) Actor

Scrape MercadoLibre best-seller rankings and product data: titles, prices, sold counts, and ratings.

- **URL**: https://apify.com/stilled\_stalagmite/mercadolibre-best-sellers-scraper.md
- **Developed by:** [Danilo Frias](https://apify.com/stilled_stalagmite) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 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.

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

## MercadoLibre Best Sellers Scraper

Scrapes public best-seller ("mas vendidos") listings from MercadoLibre Mexico. No login, no session cookies, no CAPTCHA solving, no proxy services: plain HTTPS with a normal browser User-Agent and roughly one request per second between pages.

### What it scrapes and who would use it

The actor collects the ranked best-seller products shown on the public
`mas-vendidos` listing surfaces: rank within the category carousel, category,
title, current price in MXN, product URL, and image URL. Useful for competitive
research, price benchmarking, demand spotting, and catalog gap analysis on the
MercadoLibre Mexico marketplace.

### Inputs

| Field | Type | Default | Description |
|---|---|---|---|
| `categories` | array of strings | `[]` (built-in starter list) | Best-seller category pages to scrape. Each entry may be a full URL (e.g. `https://www.mercadolibre.com.mx/mas-vendidos/MLM1051`) or a MercadoLibre category code (e.g. `MLM1051`). The built-in starter list covers six Mexican categories discovered on the mas-vendidos hub: Celulares y Telefonia, Ropa Bolsas y Calzado, Salud y Equipamiento Medico, Computacion, Accesorios para Vehiculos, Consolas y Videojuegos. |
| `max_items` | integer | `500` | Maximum product records to push across all categories; the run stops when reached. |
| `country` | string | `"mx"` | MercadoLibre country site. Tested: `mx`. Other sites (`ar`, `br`, `cl`, `co`, `pe`, `ve`, `uy`) are accepted on a best-effort basis and only their `mas-vendidos` listing surfaces are used. |

### Sample output record

```json
{
  "rank": 1,
  "category": "Celulares y Telefonía",
  "title": "Audífonos In-ear Bluetooth Para Celulares, Tablets y Laptops, Conexión Automática, Resistente al Agua y Polvo IP55, Cómodo de Llevar, Estuche de Carga Gran Capacidad, Marca MVPSMART R30 Blanco",
  "price_mxn": 124.64,
  "sold_quantity": null,
  "product_url": "https://www.mercadolibre.com.mx/audifonos-in-ear-bluetooth-para-celulares-tablets-y-laptops-conexion-automatica-resistente-al-agua-y-polvo-ip55-comodo-de-llevar-estuche-de-carga-gran-capacidad-marca-mvpsmart-r30-blanco/p/MLM44007277",
  "image_url": "https://http2.mlstatic.com/D_Q_NP_2X_851731-MLA100096823243_122025-AB.webp"
}
```

### Coverage and limits

- The mas-vendidos **hub page** (`/mas-vendidos`) is the reliable source: it exposes six
  category carousels with roughly 20 ranked items each (about 115-120 records total per run).
- **Category subpages deliberately attempted, then skipped:** per-category best-seller pages
  (`/mas-vendidos/MLMxxxx`) currently redirect anonymous requests to MercadoLibre's
  account-verification wall (`/gz/account-verification`, served from the
  suspicious-traffic frontend). The actor detects this, records the URL/status/redirect
  target in the run summary, and moves on without retrying or solving anything.
- **Pages deliberately avoided:** search-result pages and product-detail pages are never
  fetched, because MercadoLibre redirects them to account verification for anonymous
  requests. Product URLs are recorded as plain strings only.
- `sold_quantity` is always `null`: the mas-vendidos surfaces do not publish a per-item
  sold count.
- Rate limiting: ~1 request/second between fetches; one bad page (timeout, block, parse
  error) never kills the run; records are deduplicated by product URL.

### Data rules

- Public, logged-out listing pages only. No login flows, no stored session cookies, no
  CAPTCHA solving, no proxy services.
- No personal data is collected: no names, emails, or phone numbers of private
  individuals. Only public listing data (product titles, prices, images, URLs; seller or
  brand names appear only when printed on the public listing itself).

# Actor input Schema

## `categories` (type: `array`):

Best-seller category pages to scrape. Each entry can be a full URL (e.g. https://www.mercadolibre.com.mx/mas-vendidos/MLM1051) or a MercadoLibre category code (e.g. MLM1051). Defaults to six top-level Mexican categories discovered on the mas-vendidos hub page: Celulares y Telefonia, Ropa Bolsas y Calzado, Salud y Equipamiento Medico, Computacion, Accesorios para Vehiculos, and Consolas y Videojuegos.

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

MercadoLibre country site to scrape. Tested and supported: "mx" (Mexico). Other sites (ar, br, cl, co, pe, ve, uy) are accepted on a best-effort basis; only their mas-vendidos listing surfaces are used.

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

Maximum number of product records to scrape across all categories. The run stops as soon as this many records have been pushed. The hub page currently exposes about 120 ranked items (roughly 20 per category carousel); category subpages are attempted but are skipped if MercadoLibre redirects them to account verification.

## Actor input object example

```json
{
  "categories": [],
  "country": "mx",
  "max_items": 500
}
```

# Actor output Schema

## `overview` (type: `string`):

No description

# 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("stilled_stalagmite/mercadolibre-best-sellers-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("stilled_stalagmite/mercadolibre-best-sellers-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 '{}' |
apify call stilled_stalagmite/mercadolibre-best-sellers-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,stilled_stalagmite/mercadolibre-best-sellers-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/mZ88Cje1vOyCw7PIl/builds/e3kb5kQsUpKpHdot4/openapi.json