# Mercado Libre Listings Scraper (`piotrv1001/mercado-libre-listings-scraper`) Actor The Mercado Libre Listings Scraper extracts product listings across all 18 LATAM Mercado Libre sites, capturing titles, prices, discounts, sellers, shipping, ratings, attributes, and full detail pages — ideal for price monitoring, market research, and catalog enrichment. - **URL**: https://apify.com/piotrv1001/mercado-libre-listings-scraper.md - **Developed by:** [FalconScrape](https://apify.com/piotrv1001) (community) - **Categories:** E-commerce, Automation - **Stats:** 6 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $1.00 / 1,000 product listings 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/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 ### 🚀 Mercado Libre Listings Scraper Easily extract product listings from Mercado Libre across all 18 LATAM country sites. The **Mercado Libre Listings Scraper** gathers structured product data from Latin America's largest e-commerce marketplace for price monitoring, market research, and catalog enrichment. ### ✨ Features - 🌎 **All 18 LATAM Sites**: Argentina (`MLA`), Brazil (`MLB`), Mexico (`MLM`), Colombia, Chile, Peru, Uruguay, Venezuela, Ecuador, Bolivia, Panama, Paraguay, Dominican Republic, Costa Rica, Nicaragua, Guatemala, Honduras, and El Salvador. - 🏷️ **Comprehensive Product Data**: Title, price, original price, discount, installments, condition, seller, location, shipping, ratings, reviews, attributes, images, and variations. - 🔍 **Flexible Inputs**: Drive the scraper by **search keywords**, **category URLs**, or **direct listing/detail URLs**. - 🛡️ **Anti-Bot Built-In**: Drives a real Chromium browser via Playwright + Apify residential proxies — sails through Mercado Libre's regional traffic gating and JavaScript proof-of-work challenges automatically. - 🧩 **Optional Detail Enrichment**: Toggle `includeProductDetail` to fetch each item's full detail page for description, full specs, gallery images, variations, and stock. - ⚙️ **Filters & Sorting**: Price range, condition (new/used), official stores only, and sort by relevance / price ascending / descending. ### 🛠️ How It Works 1. **Pick a Country / Site ID** – e.g. `MLA` for Argentina, `MLB` for Brazil, `MLM` for Mexico. 2. **Enter Search Keywords, Category URLs, or Start URLs** – mix and match as needed. 3. **(Optional) Apply Filters** – set price range, condition, official-stores-only, sort order, and toggle `includeProductDetail`. 4. **Run the Scraper** – results stream into the dataset and can be downloaded as JSON, CSV, Excel, or HTML. ### 📥 Input | Field | Type | Required | Description | | ----------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | | `siteId` | string | yes | Country code: `MLA`, `MLB`, `MLM`, `MCO`, `MLC`, `MPE`, `MLU`, `MLV`, `MEC`, `MBO`, `MPA`, `MPY`, `MRD`, `MCR`, `MNI`, `MGT`, `MHN`, `MSV`. | | `searchQueries` | array | no | Free-text keywords. Each becomes a paginated listing crawl. | | `categoryUrls` | array | no | Mercado Libre category listing URLs. | | `startUrls` | array | no | Mix of listing, category, or detail URLs to crawl directly. | | `priceMin` | integer | no | Lower bound of the price filter (in site's local currency). | | `priceMax` | integer | no | Upper bound of the price filter (in site's local currency). | | `condition` | string | no | `any`, `new`, or `used`. Defaults to `any`. | | `officialStoresOnly` | boolean | no | Restrict to Mercado Libre official-store sellers. | | `sort` | string | no | `relevance`, `price_asc`, or `price_desc`. Defaults to `relevance`. | | `includeProductDetail` | boolean | no | Fetch each item's detail page for description, full specs, variations, gallery images, and stock. | | `maxItems` | integer | no | Stop after N items (0 = unlimited). | | `maxPagesPerQuery` | integer | no | Pagination cap per query. Default `42` (Mercado Libre limits HTML browsing to ~2,000 items per query). | | `proxyConfiguration` | object | yes | RESIDENTIAL group + LATAM country code. Required to bypass the suspicious-traffic interstitial. | ### 📊 Sample Output Data The scraper provides structured JSON output with full product details. Example: ```json [ { "id": "MLA1424728826", "siteId": "MLA", "title": "Apple iPhone 15 Pro 256 Gb Titanio Natural - Distribuidor Autorizado", "permalink": "https://articulo.mercadolibre.com.ar/MLA-1424728826-apple-iphone-15-pro-256-gb-_JM", "price": 2499999, "currency": "ARS", "originalPrice": 2799999, "discountPercent": 11, "installments": { "quantity": 12, "amount": 208333.25, "rate": 0 }, "condition": "new", "availableQuantity": 5, "soldQuantity": 250, "thumbnailUrl": "https://http2.mlstatic.com/D_NQ_NP_2X_...-F.webp", "images": ["https://http2.mlstatic.com/..."], "location": { "city": "Capital Federal", "state": "Buenos Aires", "country": "Argentina" }, "seller": { "nickname": "VENDEDORX", "isOfficialStore": true, "storeName": "VENDEDORX", "reputation": null, "powerSellerStatus": null }, "freeShipping": true, "fullShipping": true, "ratingAverage": 4.8, "reviewCount": 742, "attributes": { "brand": "Apple", "Modelo": "iPhone 15 Pro", "Capacidad": "256 GB" }, "variations": [], "scrapedAt": "2026-05-10T12:00:00.000Z" } ] ```` ### 💸 Pricing This Actor uses Apify **pay-per-event** pricing — you only pay for results you actually get. | Event | When charged | Price per result | Per 1,000 results | | ----------------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------- | ----------------- | | `product-listing` | Each product card scraped from a listing page (`includeProductDetail: false`) | $0.001 | **$1.00** | | `item-detail` | Each full product detail page (`includeProductDetail: true`) — adds description, full specs, variations, gallery, stock | $0.010 | **$10.00** | Compute units and proxy bandwidth are included in the per-event price. Set `maxItems` to cap your spend. Optimize your LATAM market research with **Mercado Libre Listings Scraper** today! 🚀 # Actor input Schema ## `siteId` (type: `string`): Mercado Libre site to scrape. Determines the domain (mercadolibre.com.ar, mercadolivre.com.br, etc.), language, currency, and default proxy country. ## `searchQueries` (type: `array`): Free-text search queries. Each will be slugified and submitted to listado.mercadolibre.com./. ## `categoryUrls` (type: `array`): Mercado Libre category listing URLs (e.g. https://listado.mercadolibre.com.ar/celulares-telefonos/celulares-smartphones/). ## `startUrls` (type: `array`): Mix of listing, category, or detail URLs to crawl directly. Detail URLs (articulo./produto.) are scraped in detail mode automatically. ## `priceMin` (type: `integer`): Lower bound for the price filter (in the site's local currency). ## `priceMax` (type: `integer`): Upper bound for the price filter (in the site's local currency). ## `condition` (type: `string`): Filter by new / used / any. ## `officialStoresOnly` (type: `boolean`): Restrict results to Mercado Libre official-store sellers. ## `sort` (type: `string`): Sort listing pages by relevance, ascending price, or descending price. ## `includeProductDetail` (type: `boolean`): If enabled, each listing's detail page is fetched to enrich the output with description, full specs, images, variations, and stock. Roughly doubles request volume and proxy cost. ## `maxItems` (type: `integer`): Stop the run after this many items have been pushed to the dataset. Set to 0 for unlimited (Mercado Libre caps each query at ~2,000 items). ## `maxPagesPerQuery` (type: `integer`): Pagination cap per query. Mercado Libre limits HTML browsing to ~2,000 items (~42 pages of 48). ## `proxyConfiguration` (type: `object`): RESIDENTIAL Apify proxies in the target country are mandatory. Datacenter and non-LATAM IPs are blocked by Mercado Libre's suspicious-traffic interstitial. The country code defaults to the site's country if you don't set one. ## Actor input object example ```json { "siteId": "MLA", "searchQueries": [ "iphone 15" ], "condition": "any", "officialStoresOnly": false, "sort": "relevance", "includeProductDetail": false, "maxItems": 50, "maxPagesPerQuery": 42, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } ``` # Actor output Schema ## `results` (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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "searchQueries": [ "iphone 15" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }; // Run the Actor and wait for it to finish const run = await client.actor("piotrv1001/mercado-libre-listings-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 = { "searchQueries": ["iphone 15"], "proxyConfiguration": { "useApifyProxy": True, "apifyProxyGroups": ["RESIDENTIAL"], }, } # Run the Actor and wait for it to finish run = client.actor("piotrv1001/mercado-libre-listings-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 '{ "searchQueries": [ "iphone 15" ], "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } }' | apify call piotrv1001/mercado-libre-listings-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=piotrv1001/mercado-libre-listings-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Mercado Libre Listings Scraper", "description": "The Mercado Libre Listings Scraper extracts product listings across all 18 LATAM Mercado Libre sites, capturing titles, prices, discounts, sellers, shipping, ratings, attributes, and full detail pages — ideal for price monitoring, market research, and catalog enrichment.", "version": "0.0", "x-build-id": "BK5em2NsaHpZd889T" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/piotrv1001~mercado-libre-listings-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-piotrv1001-mercado-libre-listings-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/piotrv1001~mercado-libre-listings-scraper/runs": { "post": { "operationId": "runs-sync-piotrv1001-mercado-libre-listings-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/piotrv1001~mercado-libre-listings-scraper/run-sync": { "post": { "operationId": "run-sync-piotrv1001-mercado-libre-listings-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", "required": [ "siteId" ], "properties": { "siteId": { "title": "Country / Site ID", "enum": [ "MLA", "MLB", "MLM", "MCO", "MLC", "MPE", "MLU", "MLV", "MEC", "MBO", "MPA", "MPY", "MRD", "MCR", "MNI", "MGT", "MHN", "MSV" ], "type": "string", "description": "Mercado Libre site to scrape. Determines the domain (mercadolibre.com.ar, mercadolivre.com.br, etc.), language, currency, and default proxy country.", "default": "MLA" }, "searchQueries": { "title": "Search keywords", "type": "array", "description": "Free-text search queries. Each will be slugified and submitted to listado.mercadolibre.com./.", "default": [ "iphone 15" ], "items": { "type": "string" } }, "categoryUrls": { "title": "Category URLs", "type": "array", "description": "Mercado Libre category listing URLs (e.g. https://listado.mercadolibre.com.ar/celulares-telefonos/celulares-smartphones/).", "items": { "type": "string" } }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Mix of listing, category, or detail URLs to crawl directly. Detail URLs (articulo./produto.) are scraped in detail mode automatically.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "priceMin": { "title": "Minimum price", "minimum": 0, "type": "integer", "description": "Lower bound for the price filter (in the site's local currency)." }, "priceMax": { "title": "Maximum price", "minimum": 0, "type": "integer", "description": "Upper bound for the price filter (in the site's local currency)." }, "condition": { "title": "Item condition", "enum": [ "any", "new", "used" ], "type": "string", "description": "Filter by new / used / any.", "default": "any" }, "officialStoresOnly": { "title": "Official stores only", "type": "boolean", "description": "Restrict results to Mercado Libre official-store sellers.", "default": false }, "sort": { "title": "Sort order", "enum": [ "relevance", "price_asc", "price_desc" ], "type": "string", "description": "Sort listing pages by relevance, ascending price, or descending price.", "default": "relevance" }, "includeProductDetail": { "title": "Include full product detail", "type": "boolean", "description": "If enabled, each listing's detail page is fetched to enrich the output with description, full specs, images, variations, and stock. Roughly doubles request volume and proxy cost.", "default": false }, "maxItems": { "title": "Max items", "minimum": 0, "type": "integer", "description": "Stop the run after this many items have been pushed to the dataset. Set to 0 for unlimited (Mercado Libre caps each query at ~2,000 items).", "default": 50 }, "maxPagesPerQuery": { "title": "Max listing pages per query", "minimum": 1, "type": "integer", "description": "Pagination cap per query. Mercado Libre limits HTML browsing to ~2,000 items (~42 pages of 48).", "default": 42 }, "proxyConfiguration": { "title": "Proxy configuration", "type": "object", "description": "RESIDENTIAL Apify proxies in the target country are mandatory. Datacenter and non-LATAM IPs are blocked by Mercado Libre's suspicious-traffic interstitial. The country code defaults to the site's country if you don't set one.", "default": { "useApifyProxy": true, "apifyProxyGroups": [ "RESIDENTIAL" ] } } } }, "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 } } } } } } } } } } ```