# MercadoLibre Mexico Marketplace Price Scraper (`dataspryva/mercadolibre-mexico-marketplace-price-scraper`) Actor

Search MercadoLibre Mexico by keyword or category URL and get price, discount, condition, seller, brand and rating for each matching product, filterable by condition and price range.

- **URL**: https://apify.com/dataspryva/mercadolibre-mexico-marketplace-price-scraper.md
- **Developed by:** [Dataspryva](https://apify.com/dataspryva) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
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

## MercadoLibre Mexico Marketplace Price Scraper

MercadoLibre Mexico (`mercadolibre.com.mx`) is the country's largest online marketplace. This actor reads its public listing pages and product pages without cookies, login or an API key, so you can track prices, discounts, sellers and stock for any product line.

### What this actor does

- **Search listings** by keyword, by pasted MercadoLibre Mexico listing URL, or by category — with pagination until `maxItems` is reached.
- **Product details** by URL or item ID: title, price, original price, discount, condition, stock, sold count, seller, rating, specs, images and variations.
- Filters for condition, price range, sort order and free shipping.
- Optional `includeDetails` enrichment: open each search result's product page to add fields the listing card does not show.
- Omits fields the source does not provide — no nulls, empty strings or placeholder rows.

### Modes

| Mode | What it returns | Required input |
|---|---|---|
| `search` | One row per listing card (optionally enriched with product-page fields) | `searchQuery` or `startUrls` |
| `product` | One row per product page, with full detail fields | `productUrls` |

### Output per product

Core fields (kept from earlier versions):

- `id` — item ID (e.g. `MLM1018500855`)
- `title`, `url`
- `countryCode` — always `MX`
- `price` — current price in MXN
- `originalPrice` — pre-discount price, when shown
- `currency`, `currencySymbol`
- `discountPercentage` — percent off, when discounted
- `condition` — `new`, `used`, `refurbished` or `open_box`
- `thumbnail` — product image URL
- `sellerName`, `brand`
- `shippingLabel` — shipping badge text (e.g. `Envío gratis`)
- `rating` — average star rating
- `reviewsCount` — number of ratings
- `scrapedAt` — UTC scrape timestamp

Additional detail fields appear when the page provides them: `itemId`, `catalogProductId`, `userProductId`, `itemUrl`, `imageUrl`, `imageCount`, `availableQuantity`, `hasStock`, `soldQuantity`, `soldText`, `sellerId`, `isOfficialStore`, `freeShipping`, `fullShipping`, `shippingText`, `logisticType`, `installments`, `specs`, `variations`, `categoryId`, `categoryPath`, `ratingDistribution`, `promotions`, `position`, `searchQuery`, `totalResults`, `sponsored` and `recordType`.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | string | `search` | `search` or `product` |
| `country` | string | `MX` | Only Mexico is supported |
| `searchQuery` | string | – | Keyword for search mode |
| `startUrls` | array | – | MercadoLibre Mexico listing URLs; replaces the keyword, filters still apply |
| `productUrls` | array | – | Product URLs or item IDs for product mode |
| `condition` | string | `any` | `any`, `new`, `used`, `refurbished`, `open_box` |
| `sort` | string | `relevance` | `relevance`, `price_asc`, `price_desc` |
| `priceMin` | integer | – | Minimum price in MXN |
| `priceMax` | integer | – | Maximum price in MXN |
| `freeShippingOnly` | boolean | `false` | Only listings with free shipping |
| `includeDetails` | boolean | `false` | Enrich each search card from its product page |
| `maxItems` | integer | `50` | Maximum records (1–1000) |

#### Example: new iPhones under a price cap

```json
{
  "mode": "search",
  "country": "MX",
  "searchQuery": "iphone",
  "condition": "new",
  "priceMax": 20000,
  "maxItems": 30
}
```

#### Example: used items in a price band, free shipping only

```json
{
  "mode": "search",
  "country": "MX",
  "searchQuery": "laptop gamer",
  "condition": "used",
  "priceMin": 5000,
  "priceMax": 15000,
  "freeShippingOnly": true,
  "maxItems": 40
}
```

#### Example: product details

```json
{
  "mode": "product",
  "productUrls": ["https://articulo.mercadolibre.com.mx/MLM-1234567890-producto", "MLM1018500855"]
}
```

#### Example: a category listing URL

```json
{
  "mode": "search",
  "startUrls": ["https://listado.mercadolibre.com.mx/camaras-fotograficas"],
  "maxItems": 20
}
```

### Use cases

- **Price monitoring** — run daily to track how a product's listed price moves.
- **Competitive research** — compare sellers, shipping offers and ratings for the same keyword.
- **Secondary-market analysis** — filter `condition=used` to study the refurbished/used segment.
- **Discount tracking** — watch `discountPercentage` to catch newly discounted items.
- **Catalog enrichment** — pull product details, specs, images and stock into a database.

### FAQ

**Is this affiliated with MercadoLibre?**
No. This is an independent actor that reads publicly available MercadoLibre Mexico pages.

**Do I need cookies, a login or an API key?**
No. The actor uses MercadoLibre's public webview route and needs no credentials.

**Why is only Mexico supported?**
Other MercadoLibre country sites are aggressively anti-bot gated and were removed rather than ship options that fail. The Mexico marketplace is verified end to end.

**How does pagination work?**
The actor requests 50 listings per page and keeps paging until `maxItems` is reached, the source reports no more results, or MercadoLibre's 2,000-row per-query window is exhausted. Use narrower filters or several queries for larger result sets.

**Why do some products have no `rating`, `reviewsCount` or `condition`?**
Listing cards often omit fields that product pages show. Set `includeDetails=true` to open each product page and fill them in.

**What happens if MercadoLibre blocks a request?**
The actor retries with fresh sessions and alternating app user agents. If a page still cannot be read, it skips that page and reports the situation in the run status instead of fabricating rows.

**How fresh is the data?**
Each run reads live MercadoLibre Mexico pages, so prices and availability reflect what is listed at run time.

**Do old saved tasks keep working?**
Yes. Legacy mode names (`searchProducts`, `searchByCategory`, `getProductDetails`), old keys
(`query`, `urls`, `startUrl`, `itemId`, `productId`, `countryCode`, `maxResults`) and
`condition=all` are mapped in code. Old API search URLs are translated to the public listing route.

# Actor input Schema

## `mode` (type: `string`):

Search listings, or fetch details for specific products.

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

MercadoLibre country site. Only Mexico (MX) is supported.

## `searchQuery` (type: `string`):

Keyword to search for. Use this or Start URLs with the search mode.

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

MercadoLibre Mexico search or category listing URLs. When set, they replace the keyword; the filter and sort fields still apply.

## `productUrls` (type: `array`):

MercadoLibre Mexico product URLs or item IDs (for example MLM1234567890). Required for the product-details mode.

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

Filter listings by item condition.

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

Order of search results.

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

Minimum price in Mexican pesos.

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

Maximum price in Mexican pesos.

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

Return only listings that advertise free shipping.

## `includeDetails` (type: `boolean`):

Open each search result's product page to add description, stock, sold count and seller fields. Slower and uses more requests.

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

Maximum records to return. Search results paginate automatically.

## Actor input object example

```json
{
  "mode": "search",
  "country": "MX",
  "searchQuery": "iphone",
  "startUrls": [],
  "productUrls": [],
  "condition": "any",
  "sort": "relevance",
  "freeShippingOnly": false,
  "includeDetails": false,
  "maxItems": 5
}
```

# Actor output Schema

## `products` (type: `string`):

Dataset containing scraped MercadoLibre Mexico product 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 = {
    "mode": "search",
    "country": "MX",
    "searchQuery": "iphone",
    "startUrls": [],
    "productUrls": [],
    "includeDetails": false,
    "maxItems": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("dataspryva/mercadolibre-mexico-marketplace-price-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 = {
    "mode": "search",
    "country": "MX",
    "searchQuery": "iphone",
    "startUrls": [],
    "productUrls": [],
    "includeDetails": False,
    "maxItems": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("dataspryva/mercadolibre-mexico-marketplace-price-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 '{
  "mode": "search",
  "country": "MX",
  "searchQuery": "iphone",
  "startUrls": [],
  "productUrls": [],
  "includeDetails": false,
  "maxItems": 5
}' |
apify call dataspryva/mercadolibre-mexico-marketplace-price-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dataspryva/mercadolibre-mexico-marketplace-price-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/ivQSE0xqPyobEakbk/builds/k8GphfC79smaHdXz3/openapi.json