# MercadoLibre Scraper (`axlymxp/mercadolibre-scraper`) Actor

Scrape MercadoLibre & MercadoLivre products across 18 Latin-American countries by keyword or today's deals — title, price, discount, rating, units sold, seller, shipping and images as structured JSON. Multi-country, resumable. Pay only for the results you get.

- **URL**: https://apify.com/axlymxp/mercadolibre-scraper.md
- **Developed by:** [axly](https://apify.com/axlymxp) (community)
- **Categories:** E-commerce, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $3.00 / 1,000 dataset items

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 Scraper

Extract product data from **MercadoLibre** and **MercadoLivre** across **18
Latin-American country marketplaces** — by keyword search or from the daily
**Ofertas** (deals) feed. Every product comes back as a clean, structured JSON row
with price, discount, rating, units sold, seller, shipping and images.

Built on MercadoLibre's own structured "polycard" data (not fragile HTML scraping),
so the output stays consistent and complete.

### Who it's for

- **Resellers & price monitors** — watch competitor prices, discounts and stock
  velocity (units sold) across countries and categories.
- **E-commerce & market analysts** — build pricing and catalog datasets per
  country for benchmarking and trend analysis.
- **Deal aggregators & affiliates** — the Ofertas feed is a high-volume, low-cost
  source of live discounts.
- **Developers** — a stable JSON schema you can wire straight into a database,
  Google Sheets, or an AI agent.

### Output fields

| Field | Type | Description |
| ----- | ---- | ----------- |
| `item_id` | string | MercadoLibre item id (e.g. `MLA1673586949`) |
| `product_id` | string | Catalog product id (e.g. `MLA57692573`), when catalogued |
| `title` | string | Product title |
| `url` / `permalink` | string | Product page URL |
| `price` | number | Current price in the site's local currency |
| `original_price` | number | Pre-discount price, when on sale |
| `currency` | string | Currency id (ARS, BRL, MXN, …) |
| `discount` | string | Discount label (e.g. `65% OFF`) |
| `installments` | string | Installment offer text |
| `rating` | number | Average review score (0–5) |
| `sold_label` | string | Raw sold label (e.g. `+5mil vendidos`) |
| `sold_count` | number | Units sold, parsed to an integer floor |
| `seller` | string | Seller / store name |
| `official_store` | boolean | Whether it's an official brand store |
| `shipping` | string | Shipping label (e.g. `Llega gratis mañana`) |
| `free_shipping` | boolean | Free-shipping flag |
| `fulfillment` | boolean | Fulfilled by MercadoLibre (FULL) |
| `variations` | string | Variation summary, when present |
| `promotions` | string | Promotion label, when present |
| `images` | array | Product image URLs |
| `position` | number | Position in the result list |
| `listing_type` | string | e.g. `ORGANIC_ITEM` |
| `site` | string | Country site id (MLA, MLB, MLM, …) |
| `source` | string | `search:<query>` or `deals` |
| `scraped_at` | string | ISO-8601 timestamp |

### Use cases

- **Cross-border price benchmarking** — run the same keyword on MLA, MLB and MLM
  and compare prices, discounts and sold counts side by side.
- **Discount monitoring** — schedule the Ofertas feed hourly per category and alert
  on new lightning deals.
- **Best-seller research** — sort by `best_sellers` and read `sold_count` to find
  what's actually moving in a category.
- **Catalog building** — page through a category to seed a product database with
  images, sellers and prices.

### Input parameters

| Field | Type | Default | Description |
| ----- | ---- | ------- | ----------- |
| `searchQueries` | array | `["notebook"]` | Keywords or full `listado.*` search URLs |
| `site` | enum | `MLA` | Country marketplace (18 options) |
| `maxItems` | integer | `200` | Total product rows to return |
| `sortBy` | enum | `relevance` | `relevance`, `price_asc`, `price_desc`, `best_sellers`, `newest` |
| `condition` | enum | `all` | `all`, `new`, `used` |
| `freeShippingOnly` | boolean | `false` | Only free-shipping products |
| `priceMin` / `priceMax` | integer | — | Local-currency price band |
| `scrapeDeals` | boolean | `false` | Also scrape today's Ofertas feed |
| `dealsCategory` | string | — | Category id to scope deals (e.g. `MLA1652`) |
| `proxyConfiguration` | proxy | Residential (site country) | Search needs a residential IP |

#### Example input

```json
{
  "searchQueries": ["notebook", "zapatillas nike"],
  "site": "MLA",
  "sortBy": "best_sellers",
  "condition": "new",
  "maxItems": 500,
  "scrapeDeals": true,
  "dealsCategory": "MLA1652"
}
```

#### Example output row

```json
{
  "item_id": "MLA57692573",
  "product_id": "MLA57692573",
  "title": "Combo Hidrolavadora Aspiradora Electrica Trent HLT307 + VC19K",
  "permalink": "https://www.mercadolibre.com.ar/.../p/MLA57692573",
  "price": 158239,
  "original_price": 458789,
  "currency": "ARS",
  "discount": "65% OFF",
  "rating": 4.8,
  "sold_label": "+5mil vendidos",
  "sold_count": 5000,
  "seller": "TRENT",
  "official_store": true,
  "free_shipping": true,
  "fulfillment": true,
  "images": ["https://http2.mlstatic.com/D_Q_NP_2X_639539-....webp"],
  "site": "MLA",
  "source": "deals",
  "scraped_at": "2026-09-25T12:00:00Z"
}
```

### Scheduling & integrations

Run it on a **schedule** (hourly/daily) from the Apify Console, or trigger it via
the **API**. Pipe results to **Google Sheets, Make, Zapier, Airbyte or S3**, or
pull the dataset directly:

```
https://api.apify.com/v2/datasets/<datasetId>/items?format=json
```

### Use it from an AI assistant (MCP)

The actor is callable from AI agents through the **Apify MCP server** — an
assistant can run "scrape MercadoLibre for `iphone 15` in Mexico, best sellers,
top 100" and read back structured rows, no code required.

### Notes on coverage & anti-bot

- **Keyword search** is protected by MercadoLibre's IP-reputation gate, so the
  actor routes it through an **Apify Residential** proxy in the site's country
  (enabled by default). It rotates the exit IP automatically if a request is
  challenged.
- **The Ofertas (deals) feed is open** and works without a proxy — a reliable,
  low-cost source even if search is throttled.
- MercadoLibre caps any single search at ~1000 results; narrow by category, price
  band or condition to go deeper.

### FAQ

**Which countries are supported?** All 18 MercadoLibre sites: Argentina, Brazil,
Mexico, Chile, Colombia, Peru, Uruguay, Venezuela, Ecuador, Bolivia, Paraguay,
Costa Rica, Guatemala, Panama, Dominican Republic, Honduras, Nicaragua and El
Salvador.

**Do I need my own proxies?** No. A residential proxy is built in for search. The
deals feed needs no proxy at all.

**How fresh is the data?** Every row is fetched live at run time and stamped with
`scraped_at`.

**Can I get more than 1000 results for one keyword?** MercadoLibre itself caps a
search at ~1000 organic results. Split by category, price range or condition to
cover more of the catalog.

**Is it reliable?** The actor reads MercadoLibre's own structured product data and
checkpoints its progress, so runs resume cleanly after interruptions.

**Is scraping this legal?** The actor collects only public product data. You are
responsible for using the output in line with MercadoLibre's terms and applicable
law.

# Actor input Schema

## `searchQueries` (type: `array`):

Keywords to search (e.g. "notebook", "iphone 15"), or full MercadoLibre search URLs. NOTE: keyword search is gated by MercadoLibre and needs a residential proxy (see Proxy) — on accounts without one, use "Scrape deals" instead, which is open.

## `site` (type: `string`):

Which MercadoLibre country marketplace to scrape.

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

Stop after this many product rows in total (across all queries). MercadoLibre caps any single search at ~1000 results.

## `sortBy` (type: `string`):

Result ordering for keyword searches.

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

Filter search results by item condition.

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

Only return products with free shipping.

## `priceMin` (type: `integer`):

Only return products at or above this price (in the site's local currency).

## `priceMax` (type: `integer`):

Only return products at or below this price (in the site's local currency).

## `scrapeDeals` (type: `boolean`):

Scrape the site's "Ofertas" deals feed — open, works without a proxy. On by default; the actor scrapes deals when no search queries are given.

## `dealsCategory` (type: `string`):

Optional category id to scope the deals feed (e.g. MLA1652 for Notebooks). Leave empty for site-wide deals.

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

Required for keyword search: MercadoLibre gates search behind an IP check, so a residential proxy in the site's country is used (the country is auto-selected). The deals feed does NOT need a proxy. If your plan has no residential proxy, leave search empty and use deals.

## Actor input object example

```json
{
  "searchQueries": [
    "notebook",
    "zapatillas nike"
  ],
  "site": "MLA",
  "maxItems": 200,
  "sortBy": "relevance",
  "condition": "all",
  "freeShippingOnly": false,
  "scrapeDeals": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `dataset` (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 = {
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("axlymxp/mercadolibre-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 = { "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    } }

# Run the Actor and wait for it to finish
run = client.actor("axlymxp/mercadolibre-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 '{
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call axlymxp/mercadolibre-scraper --silent --output-dataset

```

## MCP server setup

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