# MercadoLibre Product Scraper (`crawlerbros/mercadolibre-scraper`) Actor Scrape products from MercadoLibre across 11 Latin American countries. Returns product title, price, currency, condition, seller, thumbnail, and permalink. - **URL**: https://apify.com/crawlerbros/mercadolibre-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** E-commerce, Lead generation, SEO tools - **Stats:** 2 total users, 1 monthly users, 92.3% runs succeeded, 9 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $1.00 / 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/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 ## MercadoLibre Scraper Scrape products from **[MercadoLibre](https://www.mercadolibre.com)** — Latin America's largest e-commerce marketplace. Returns product ID, title, URL, price, currency, condition, seller, thumbnail, rating, and more. Supports Argentina, Brazil, and Mexico. ### What it does - Scrapes MercadoLibre search results across **3 LatAm country sites** (AR, BR, MX) - Extracts product ID, title, URL, price, currency, thumbnail, rating, reviews, seller, brand, and shipping info - Hardcoded residential proxy handles MercadoLibre's account-verification block wall - Automatic session rotation — up to 6 retries on flagged sessions - Clean, non-null output — empty fields are omitted from records ### Input | Field | Type | Default | Description | |---|---|---|---| | `country` | enum | `AR` | Which MercadoLibre site to scrape: `AR` (Argentina), `BR` (Brazil), `MX` (Mexico) | | `searchQuery` | string | `"iphone"` | Free-text keyword (required unless `startUrls` is set) | | `condition` | enum | `any` | `any` / `new` / `used` | | `priceMin` | integer | — | Minimum price in local currency | | `priceMax` | integer | — | Maximum price in local currency | | `startUrls` | array | — | Direct MercadoLibre search URLs (override structured filters) | | `maxItems` | integer | `50` | Maximum results to return (1–1000) | #### Example input ```json { "country": "BR", "searchQuery": "notebook", "priceMin": 2000, "priceMax": 10000, "maxItems": 20 } ```` ### Output Each product is a JSON record with the following fields (missing fields are omitted, never `null`): | Field | Type | Always present | Description | |---|---|---|---| | `id` | string | ✓ | MercadoLibre item ID (e.g. `MLA1018500855`) | | `title` | string | ✓ | Product title | | `url` | string | ✓ | Full product URL | | `countryCode` | string | ✓ | Country code (e.g. `AR`) | | `scrapedAt` | string | ✓ | UTC ISO 8601 scrape timestamp | | `price` | number | — | Current price in local currency | | `originalPrice` | number | — | Strikethrough / original price (before discount) | | `currency` | string | — | Currency code (e.g. `ARS`, `BRL`, `MXN`) | | `currencySymbol` | string | — | Currency symbol as displayed on the site | | `discountPercentage` | number | — | Percentage off (0–100) | | `thumbnail` | string | — | Product image URL | | `sellerName` | string | — | Seller / brand name | | `brand` | string | — | Brand attribute | | `shippingLabel` | string | — | Shipping badge text (e.g. `Envío gratis`, `Frete grátis`) | | `rating` | number | — | Seller or product star rating | | `reviewsCount` | number | — | Number of reviews | #### Sample output ```json { "id": "MLA1018500855", "title": "iPhone 13 128 GB 4 GB RAM Blanco estelar Apple - Distribuidor Autorizado", "url": "https://articulo.mercadolibre.com.ar/MLA-1018500855-iphone-13-128-gb-...", "countryCode": "AR", "price": 999999, "currency": "ARS", "currencySymbol": "$", "thumbnail": "https://http2.mlstatic.com/D_Q_NP_2X_787642-MLA95698363690_102025-E.webp", "sellerName": "DistribuidorOficial", "shippingLabel": "Envío gratis", "scrapedAt": "2026-04-14T06:38:23Z" } ``` ### FAQ **Do I need a proxy?** No configuration needed — an Apify **residential proxy** is applied automatically, matching the selected country. MercadoLibre blocks direct datacenter access and even many residential sessions, so the scraper rotates proxy session IDs up to 6 times per run on flagged sessions. The first half of attempts use the target country's residential pool; the second half falls back to any residential IP for resilience. **Why only 3 countries?** At the time of writing, MercadoLibre's smaller-market sites (Chile, Colombia, Peru, Uruguay, Venezuela, Ecuador, Dominican Republic, Costa Rica) return a hard-block response on every residential session in Apify's pool. Only AR, BR, and MX reliably serve scrapable HTML. The scraper's country enum has been trimmed accordingly. **How many results can I get per run?** Up to 1,000 items (theoretically). Each search page returns 40–50 cards; the scraper paginates via the MercadoLibre page index when `maxItems` exceeds a single page. Practical cap depends on how deep the search goes before MercadoLibre starts returning "no more results". **Does the scraper call MercadoLibre's public API?** No. `api.mercadolibre.com` now returns 403 for anonymous traffic. The scraper uses the HTML search listings page (`listado.mercadolibre.com.ar/`, etc.) and parses the `poly-card` server-rendered product tiles. **What happens if the target site is blocked?** The scraper retries with a fresh residential session. If all 6 retries fail, the run exits with a fail status and no records — the residential pool was exhausted for that country. Rerun in a few minutes. **How fresh is the data?** Every run hits the live search page. Prices and availability are always current. ### Use cases - **Price monitoring** — daily runs to track competitor prices in AR/BR/MX - **Trend research** — ingest product names and prices across major keywords - **Cross-border arbitrage** — compare pricing between AR, BR, and MX markets - **Inventory alerts** — monitor specific SKUs via the `startUrls` override ### Notes - Pricing is configured in the Apify UI (pay-per-result). - MercadoLibre's HTML can change; if the scraper starts returning 0 items, check the `poly-card` class markers in `src/main.py:parse_search_html`. - The daily Apify test run uses `country=AR`, `searchQuery=iphone`, `maxItems=5`. # Actor input Schema ## `country` (type: `string`): MercadoLibre country site to scrape. Currently supports AR (Argentina), BR (Brazil) and MX (Mexico). Smaller-market sites (CL, CO, PE, UY, VE, EC, DO, CR) are heavily anti-bot gated and are not reliably scrapable from Apify residential pools at this time. ## `searchQuery` (type: `string`): Free-text keyword. Required if startUrls is empty. ## `condition` (type: `string`): Filter by item condition. ## `priceMin` (type: `integer`): Minimum price in the country's local currency. ## `priceMax` (type: `integer`): Maximum price in the country's local currency. ## `startUrls` (type: `array`): Direct MercadoLibre API search URLs. If set, overrides structured filters. ## `maxItems` (type: `integer`): Maximum items to return. ## Actor input object example ```json { "country": "AR", "searchQuery": "iphone", "condition": "any", "maxItems": 5 } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "country": "AR", "searchQuery": "iphone", "maxItems": 5 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "country": "AR", "searchQuery": "iphone", "maxItems": 5, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/mercadolibre-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "country": "AR", "searchQuery": "iphone", "maxItems": 5 }' | apify call crawlerbros/mercadolibre-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/mercadolibre-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "MercadoLibre Product Scraper", "description": "Scrape products from MercadoLibre across 11 Latin American countries. Returns product title, price, currency, condition, seller, thumbnail, and permalink.", "version": "1.0", "x-build-id": "c0eKKXeDJrTfajUuW" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~mercadolibre-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-mercadolibre-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~mercadolibre-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-mercadolibre-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~mercadolibre-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-mercadolibre-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "country": { "title": "Country", "enum": [ "AR", "BR", "MX" ], "type": "string", "description": "MercadoLibre country site to scrape. Currently supports AR (Argentina), BR (Brazil) and MX (Mexico). Smaller-market sites (CL, CO, PE, UY, VE, EC, DO, CR) are heavily anti-bot gated and are not reliably scrapable from Apify residential pools at this time.", "default": "AR" }, "searchQuery": { "title": "Search Query", "type": "string", "description": "Free-text keyword. Required if startUrls is empty." }, "condition": { "title": "Condition", "enum": [ "any", "new", "used" ], "type": "string", "description": "Filter by item condition.", "default": "any" }, "priceMin": { "title": "Min Price", "minimum": 0, "type": "integer", "description": "Minimum price in the country's local currency." }, "priceMax": { "title": "Max Price", "minimum": 0, "type": "integer", "description": "Maximum price in the country's local currency." }, "startUrls": { "title": "Start URLs (optional)", "type": "array", "description": "Direct MercadoLibre API search URLs. If set, overrides structured filters.", "items": { "type": "string" } }, "maxItems": { "title": "Max Items", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum items to return.", "default": 50 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```