# Mercado Livre Brazil Scraper (`automation-lab/mercado-livre-brazil-scraper`) Actor

Search current Mercado Livre Brazil offers and export product, seller, price, availability, rating, image, listing ID, and source-query records.

- **URL**: https://apify.com/automation-lab/mercado-livre-brazil-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** E-commerce
- **Stats:** 1 total users, 1 monthly users, 90.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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

## Mercado Livre Brazil Scraper

Search the current **mercadolivre** offers catalog and export structured Brazilian marketplace product records. Mercado Livre Brazil Scraper collects public titles, sellers, prices, discounts, availability, ratings, sales labels, images, listing IDs, product URLs, and source-query context from `mercadolivre.com.br`.

Use it for scheduled catalog snapshots, competitor-price monitoring, seller-offer review, deal discovery, and data pipelines that need typed JSON instead of marketplace pages.

### What does Mercado Livre Brazil Scraper do?

The Actor reads Mercado Livre Brazil's public server-rendered offers pages.
It can:

- match one or more product keywords against current offer titles and seller names;
- collect a specific Mercado Livre `/ofertas` page;
- keep products inside a BRL price range;
- filter products by public seller or official-store name;
- deduplicate records by Mercado Livre listing ID;
- stop at a user-defined result limit;
- produce one clean default-dataset record per accepted listing.

The Actor is optimized for repeat snapshots. Schedule the same input and compare records by `listingId` to identify price, seller, discount, rating, or availability changes.

### Who is it for?

**E-commerce analysts** can build a current offer-price benchmark.

**Brands and manufacturers** can review public marketplace positioning and seller visibility.

**Retail and procurement teams** can find products inside a budget band.

**Marketplace agencies** can export offer cards for client reporting.

**Data engineers** can feed normalized Mercado Livre product rows into a warehouse, dashboard, spreadsheet, webhook, or monitoring job.

**Developers** can use the Actor as a hosted, schedulable alternative to maintaining HTML extraction and Apify integrations themselves.

### Why use this Actor?

- **Brazil-specific source:** the implementation targets `mercadolivre.com.br` and BRL prices.
- **Monitoring-ready IDs:** `listingId` provides a stable key for comparing snapshots.
- **Useful seller context:** public seller names are included when Mercado Livre displays them.
- **Input parity:** query, seller, and price filters apply to explicit offers-page URLs too.
- **Fail-closed behavior:** traffic-verification or unrecognized pages cause a failed run instead of misleading empty success.
- **No automatic residential proxy:** the current route uses efficient direct HTTP and does not expose an unmeasured costly fallback.
- **Integration-friendly output:** primary records go to the default Apify dataset.

### What Mercado Livre product data is extracted?

| Field | Type | Meaning |
| --- | --- | --- |
| `listingId` | string | Stable listing ID, normally an `MLB…` value |
| `productId` | string or null | Catalog product ID exposed by the URL |
| `title` | string | Public listing title |
| `seller` | string or null | Public seller or official-store name |
| `price` | number | Current price in BRL |
| `originalPrice` | number or null | Previous price when shown |
| `discountPercent` | number or null | Displayed discount percentage |
| `currency` | string | Always `BRL` for this Actor |
| `rating` | number or null | Displayed rating from zero to five |
| `soldQuantityText` | string or null | Source-formatted public sales label |
| `availability` | string | `available` when present in the current offers catalog |
| `imageUrl` | string or null | Public product thumbnail URL |
| `url` | string | Public product URL without tracking fragment |
| `sourceQuery` | string or null | First matching input keyword |
| `matchedQueries` | string\[] | Every matching input keyword |
| `sourceUrl` | string | Offers page that produced the record |
| `position` | integer | One-based card position on that source page |
| `scrapedAt` | string | ISO 8601 extraction timestamp |

Nullable values reflect what Mercado Livre displays on each card. A missing rating or previous price is returned as `null`, not fabricated.

### How to scrape Mercado Livre Brazil offers

1. Open the Actor input page.
2. Enter one or more product keywords, such as `notebook`.
3. Optionally add a supported Mercado Livre `/ofertas` URL.
4. Add a seller substring or BRL price range when needed.
5. Set the maximum-products limit to control dataset size and total budget.
6. Click **Start**.
7. Open the **Products** output or export the default dataset as JSON, CSV, Excel, XML, or RSS.
8. For monitoring, schedule the Task and compare snapshots by `listingId`.

Start with a small result limit while validating a new workflow.

### Input parameters

| Input | Required | Default | Description |
| --- | --- | --- | --- |
| `queries` | conditionally | `notebook` | Up to 20 case-insensitive keywords matched against titles and sellers |
| `startUrls` | conditionally | offers page in prefill | Mercado Livre Brazil URLs under `/ofertas` |
| `seller` | no | — | Seller-name substring filter |
| `minPrice` | no | — | Minimum accepted current price in BRL |
| `maxPrice` | no | — | Maximum accepted current price in BRL |
| `maxItems` | no | `100` | Maximum unique rows, from 1 to 5,000 |

Provide at least one non-empty query or one start URL. Unsupported hosts and paths fail validation before collection.

Example keyword search:

```json
{
  "queries": ["notebook"],
  "maxItems": 10
}
```

Example monitoring input:

```json
{
  "queries": ["smartphone", "camera"],
  "minPrice": 100,
  "maxPrice": 1500,
  "maxItems": 20
}
```

Example source-page export:

```json
{
  "queries": [],
  "startUrls": [
    { "url": "https://www.mercadolivre.com.br/ofertas" }
  ],
  "maxItems": 20
}
```

### Output example

A current run returns records shaped like this:

```json
{
  "listingId": "MLB49089309",
  "productId": "MLB49089309",
  "title": "Notebook ASUS Vivobook 15 M1502, AMD Ryzen 7, 8 GB RAM, 512 GB SSD",
  "seller": "Asus",
  "price": 2927,
  "originalPrice": 3999,
  "discountPercent": 26,
  "currency": "BRL",
  "rating": 4.8,
  "soldQuantityText": "+100 vendidos",
  "availability": "available",
  "imageUrl": "https://http2.mlstatic.com/D_NQ_NP_...webp",
  "url": "https://www.mercadolivre.com.br/notebook-asus-vivobook-15/p/MLB49089309",
  "sourceQuery": "notebook",
  "matchedQueries": ["notebook"],
  "sourceUrl": "https://www.mercadolivre.com.br/ofertas",
  "position": 23,
  "scrapedAt": "2026-08-06T20:52:30.000Z"
}
```

Values change with the live catalog. The schema, field names, and types remain stable.

### How much does it cost to monitor Mercado Livre offers?

The Actor uses pay-per-event pricing:

- one `start` event per run;
- one `item` event for each validated product saved to the default dataset;
- no item charge for duplicate, filtered-out, invalid, or failed records.

At the BRONZE rate, a run starts at **$0.005** and each accepted item is **$0.0015**. Examples before platform-usage charges:

| Accepted products | BRONZE calculation | Approximate total |
| ---: | --- | ---: |
| 1 | 0.005 + (1 × 0.0015) | 0.0065 USD |
| 10 | 0.005 + (10 × 0.0015) | 0.0200 USD |
| 25 | 0.005 + (25 × 0.0015) | 0.0425 USD |
| 100 | 0.005 + (100 × 0.0015) | 0.1550 USD |

Apify subscription tiers can use different item rates. The Console estimate shown before a run is the authoritative rate for your account tier. Compute and storage usage may also apply according to your Apify plan.

### Catalog monitoring workflow

Create an Apify Task with a stable input and schedule it daily or weekly.
Export every run to a warehouse table keyed by `listingId` and `scrapedAt`.
Then compare the latest two snapshots.

Common change rules include:

- `price` decreased or increased;
- `discountPercent` appeared or disappeared;
- `seller` changed;
- a listing did not appear in the latest current-offers snapshot;
- a new listing ID matched a tracked query;
- rating or public sales-volume text changed.

Absence from one offers-page snapshot means the listing was not present on that sampled source page; it does not prove that the product is unavailable across the entire marketplace.

### Export and integration patterns

Use Apify dataset exports for one-time analysis:

- JSON for applications and event pipelines;
- CSV or Excel for analysts and agencies;
- XML or RSS for legacy workflows;
- Google Sheets through an Apify integration;
- webhooks to trigger downstream processing after a successful run.

For repeat monitoring, store `listingId`, `price`, `seller`, `sourceUrl`, and `scrapedAt`. Those fields provide the most useful snapshot identity and provenance.

### Run through the Apify API with cURL

Replace `APIFY_TOKEN` with your token:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~mercado-livre-brazil-scraper/runs?token=APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["notebook"],"maxItems":10}'
```

To wait for completion and return dataset rows:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~mercado-livre-brazil-scraper/run-sync-get-dataset-items?token=APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"queries":["notebook"],"maxItems":10}'
```

### Run from JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/mercado-livre-brazil-scraper').call({
    queries: ['notebook'],
    maxItems: 10,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

### Run from Python

```python
import os
from apify_client import ApifyClient

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("automation-lab/mercado-livre-brazil-scraper").call(
    run_input={"queries": ["notebook"], "maxItems": 10}
)
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

### Use with MCP and AI agents

Add the Actor to Claude Code through Apify MCP:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/mercado-livre-brazil-scraper"
```

#### Claude Desktop, Cursor, and VS Code

Claude Desktop, Cursor, and VS Code can use this HTTP MCP configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/mercado-livre-brazil-scraper"
    }
  }
}
```

Example prompts showing MCP usage:

- “Run Mercado Livre Brazil Scraper for notebook offers and return the 10 cheapest current records.”
- “Collect current smartphone and camera offers between R$100 and R$1,500.”
- “Compare these Mercado Livre listing IDs with yesterday's dataset and summarize price changes.”

The AI client still needs an Apify token and permission to run the Actor.

### Limits and responsible interpretation

This Actor covers the **current public offers catalog and supported `/ofertas` pages**. It does not claim marketplace-wide inventory, authenticated account data, private seller information, complete product details, reviews, coupons, historical prices, or stock counts.

Keyword matching is performed against the current page's product titles and public seller names. A query can legitimately produce zero rows when no current offer card matches it.

Mercado Livre can change HTML, offer composition, or traffic controls. The Actor recognizes the expected page shape and fails on verification shells instead of silently producing an empty dataset.

A successful record means the product card was displayed as an available current offer when scraped. It is not a guarantee that checkout or delivery remains available later.

### Reliability and troubleshooting

**The run failed with an unrecognized or verification page.**

Retry later once. If the source still returns a verification shell, inspect the run log and do not interpret the failed run as an empty catalog.

**My query returned zero products.**

Open the source offers page and check whether a current card contains the exact keyword in its title or seller. Try a broader term, remove the seller filter, or use the source-page export example.

**A URL was rejected.**

Only `mercadolivre.com.br` hosts and paths beginning with `/ofertas` are accepted. Product-detail, account, and generic search URLs are intentionally outside this Actor's supported source route.

**The same item appeared on two source pages.**

The Actor deduplicates within a run by `listingId`, so the first accepted occurrence is retained.

**I received fewer rows than `maxItems`.**

`maxItems` is a ceiling, not a promised count. Filters, deduplication, and current source-page inventory can all reduce output.

### Legal and responsible use

The Actor extracts public marketplace offer-card data. Use it only for lawful purposes and in accordance with Mercado Livre's terms, applicable database and copyright rules, privacy laws, and your contractual obligations.

Do not use the output to profile private individuals, circumvent access controls, automate purchases, impersonate sellers, or send unsolicited messages. Avoid collecting more data or running more frequently than your legitimate business purpose requires.

You are responsible for your input, retention period, downstream processing, and compliance decisions. This documentation is operational guidance, not legal advice.

### Related Automation Lab actors

- [Amazon Product Search Results Scraper](https://apify.com/automation-lab/amazon-product-search-results-scraper) for comparable Amazon marketplace search snapshots.
- [Amazon Bestsellers Scraper](https://apify.com/automation-lab/amazon-bestsellers-scraper) for category bestseller monitoring.
- [Amazon Sellers Scraper](https://apify.com/automation-lab/amazon-sellers-scraper) for Amazon seller-focused workflows.

These Actors target different sources. They are useful for multi-market analysis but do not extend Mercado Livre coverage inside this Actor.

### FAQ

#### Does it use the official Mercado Livre API?

No. The anonymous official search endpoint is not available to this runtime. The Actor parses public server-rendered offer cards and records the source URL for provenance.

#### Does it scrape all Mercado Livre products?

No. It samples the current public offers catalog or the explicit supported offers pages you provide. It does not claim complete marketplace inventory.

#### Can I monitor prices over time?

Yes. Schedule a stable input and compare runs by `listingId`. Keep `scrapedAt` and `sourceUrl` so every observed value retains time and source context.

#### Are filtered-out records charged?

No. The `item` event is emitted only after a record passes validation, query matching, deduplication, seller filtering, price filtering, and the result limit.

#### Can I provide product-detail or generic search URLs?

No. The Actor rejects unsupported paths rather than pretending they are covered. Use `/ofertas` sources or keywords matched against the current default offers catalog.

#### Does it need a proxy configuration?

No user proxy input is exposed. The working implementation uses direct HTTP. This keeps the runtime lightweight and prevents hidden residential-proxy cost.

# Actor input Schema

## `queries` (type: `array`):

Keywords matched against product titles and seller names in the current Mercado Livre offers catalog. Up to 20 queries.

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

Optional Mercado Livre Brazil /ofertas page URLs, including category-filtered offer pages. All price and seller filters also apply to these URLs.

## `seller` (type: `string`):

Keep only listings whose public seller or official-store name contains this text.

## `minPrice` (type: `number`):

Keep only products at or above this current price in Brazilian reais.

## `maxPrice` (type: `number`):

Keep only products at or below this current price in Brazilian reais.

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

Maximum number of unique product listing records saved to the dataset.

## Actor input object example

```json
{
  "queries": [
    "notebook"
  ],
  "startUrls": [
    {
      "url": "https://www.mercadolivre.com.br/ofertas"
    }
  ],
  "maxItems": 20
}
```

# Actor output Schema

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

Product listing, seller, price, availability, rating, image, query, and source-page records.

# 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 = {
    "queries": [
        "notebook"
    ],
    "startUrls": [
        {
            "url": "https://www.mercadolivre.com.br/ofertas"
        }
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/mercado-livre-brazil-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 = {
    "queries": ["notebook"],
    "startUrls": [{ "url": "https://www.mercadolivre.com.br/ofertas" }],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/mercado-livre-brazil-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 '{
  "queries": [
    "notebook"
  ],
  "startUrls": [
    {
      "url": "https://www.mercadolivre.com.br/ofertas"
    }
  ],
  "maxItems": 20
}' |
apify call automation-lab/mercado-livre-brazil-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,automation-lab/mercado-livre-brazil-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/cnAPfhFsNmiwGJA5t/builds/fSQ9BysRdo2GETkYj/openapi.json