# MercadoLibre Search Scraper (`automation-lab/mercadolibre-search-scraper`) Actor Extract ranked MercadoLibre search results with prices, sellers, shipping badges, locations, thumbnails, and rank metadata for LATAM commerce monitoring. - **URL**: https://apify.com/automation-lab/mercadolibre-search-scraper.md - **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community) - **Categories:** E-commerce - **Stats:** 2 total users, 1 monthly users, 85.7% 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 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 Search Scraper Extract ranked product listings from MercadoLibre search pages across LATAM marketplaces. ### What does MercadoLibre Search Scraper do? MercadoLibre Search Scraper collects one dataset row per listing from MercadoLibre search and category pages. It is designed for marketplace monitoring, price tracking, search-rank checks, and seller discovery workflows. ### Who is it for? - πŸ›’ Ecommerce sellers tracking their own product visibility. - 🏷️ Brands monitoring unauthorized sellers and price changes. - πŸ“ˆ Market researchers comparing supply across countries. - πŸ€– Automation teams feeding pricing dashboards and alerts. - 🧾 Dropshippers checking stock, shipping, and seller signals. ### Why use this scraper? MercadoLibre search pages contain ranking, pricing, shipping, location, and seller signals that are useful for day-to-day marketplace decisions. This actor packages those signals into clean Apify dataset rows that can be exported or consumed through the API. ### Supported MercadoLibre sites - Mexico (`MLM`) - Brazil (`MLB`) - Argentina (`MLA`) - Colombia (`MCO`) - Chile (`MLC`) - Peru (`MPE`) - Uruguay (`MLU`) - Ecuador (`MEC`) ### Data you can extract | Field | Description | | --- | --- | | `title` | Listing title | | `url` | Product/listing URL | | `price` | Current visible price | | `currency` | Currency code when available | | `originalPrice` | Previous price when MercadoLibre shows one | | `discount` | Discount badge text | | `sellerName` | Seller or official-store label when visible | | `location` | Listing or seller location | | `shipping` | Shipping badge text | | `isFreeShipping` | Boolean free-shipping indicator | | `isFull` | MercadoLibre FULL indicator | | `thumbnail` | Listing image URL | | `rating` | Rating when shown | | `reviewCount` | Review count when shown | | `rank` | Overall result rank in the run | | `page` | Search page number | | `query` | Input query | | `site` | MercadoLibre country site | | `scrapedAt` | Extraction timestamp | ### How much does it cost to scrape MercadoLibre search results? The actor uses pay-per-event pricing: a $0.07 start event plus a tiered per-listing result event. The formula-derived baseline BRONZE price is $0.0019215 per listing, with lower per-listing rates on higher Apify usage tiers. ### Quick start 1. Open the actor on Apify. 2. Enter one or more search queries such as `laptop gamer`. 3. Select the MercadoLibre site, for example Mexico (`MLM`). 4. Keep proxy enabled for best reliability. 5. Set `Maximum listings` to the number of rows you need. 6. Run the actor and export the dataset. ### Input example ```json { "queries": ["laptop gamer", "iphone 15"], "site": "MLM", "maxItems": 100, "maxPagesPerSearch": 3, "useProxy": true, "proxyGroups": ["RESIDENTIAL"], "proxyCountryCode": "MX" } ```` ### Start URL example ```json { "startUrls": [ { "url": "https://listado.mercadolibre.com.mx/consola-nintendo-switch" } ], "site": "MLM", "maxItems": 50, "useProxy": true, "proxyCountryCode": "MX" } ``` ### Output example ```json { "title": "Laptop Gamer Ryzen 7 16GB RAM 512GB SSD", "url": "https://articulo.mercadolibre.com.mx/...", "price": 12999, "currency": "MXN", "shipping": "EnvΓ­o gratis", "isFreeShipping": true, "rank": 1, "page": 1, "query": "laptop gamer", "site": "MLM", "scrapedAt": "2026-06-29T00:00:00.000Z" } ``` ### Ranking and page metadata The `rank` field is the overall position saved by the actor, while `positionOnPage` is the position on a specific MercadoLibre page. Use both fields to monitor search-rank changes over time. ### Proxy recommendations MercadoLibre commonly shows account-verification pages to datacenter and workspace IPs. Keep Apify Proxy enabled. Residential proxy with a matching country code is recommended for production runs. ### Anti-blocking behavior The actor warms up on the MercadoLibre country homepage before opening search pages. This improves reliability and reduces direct verification redirects. It also blocks heavy media resources to reduce proxy bandwidth. ### Tips for reliable runs - Use a proxy country matching the selected site. - Keep `maxPagesPerSearch` conservative for scheduled monitoring. - Prefer keyword queries for broad monitoring. - Use `startUrls` for categories or complex filtered pages. - Run smaller jobs more frequently for rank tracking. ### Common workflows #### Price monitoring Run the same query daily and compare `price`, `discount`, and `sellerName` values. #### Search-rank monitoring Track the `rank` and `positionOnPage` fields for important keywords. #### Seller discovery Export listings and group by `sellerName`, `location`, or official-store signals. #### Shipping analysis Use `shipping`, `isFreeShipping`, and `isFull` to compare fulfillment promises across products. ### Integrations - Send datasets to Google Sheets through Apify integrations. - Trigger runs on a schedule for rank monitoring. - Connect to Make or Zapier for alert workflows. - Export JSON/CSV into pricing intelligence dashboards. - Use webhooks to notify your team when a run finishes. ### API usage with Node.js ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: process.env.APIFY_TOKEN }); const run = await client.actor('automation-lab/mercadolibre-search-scraper').call({ queries: ['laptop gamer'], site: 'MLM', maxItems: 100, useProxy: true, proxyCountryCode: 'MX' }); console.log(run.defaultDatasetId); ``` ### API usage with Python ```python from apify_client import ApifyClient client = ApifyClient('YOUR_APIFY_TOKEN') run = client.actor('automation-lab/mercadolibre-search-scraper').call(run_input={ 'queries': ['laptop gamer'], 'site': 'MLM', 'maxItems': 100, 'useProxy': True, 'proxyCountryCode': 'MX', }) print(run['defaultDatasetId']) ``` ### API usage with cURL ```bash curl -X POST 'https://api.apify.com/v2/acts/automation-lab~mercadolibre-search-scraper/runs?token=YOUR_APIFY_TOKEN' \ -H 'Content-Type: application/json' \ -d '{"queries":["laptop gamer"],"site":"MLM","maxItems":100,"useProxy":true,"proxyCountryCode":"MX"}' ``` ### MCP integration Use the Apify MCP server with this actor in Claude Code or Claude Desktop: ```bash claude mcp add apify https://mcp.apify.com/?tools=automation-lab/mercadolibre-search-scraper ``` Claude Desktop JSON configuration: ```json { "mcpServers": { "apify": { "url": "https://mcp.apify.com/?tools=automation-lab/mercadolibre-search-scraper" } } } ``` Example prompts: - "Run the MercadoLibre Search Scraper for laptop gamer in Mexico and summarize the top sellers." - "Compare the top 50 iPhone listings on MercadoLibre Argentina by price and shipping." - "Create a CSV of MercadoLibre search ranks for my target keywords." ### Scheduling Schedule the actor daily or hourly to build a history of ranking and price changes. Use smaller result limits for frequent monitoring and larger limits for periodic market snapshots. ### Troubleshooting: no listings returned MercadoLibre may return an account-verification page. Enable Apify Proxy, choose `RESIDENTIAL`, and set a matching `proxyCountryCode` such as `MX` for Mexico. ### Troubleshooting: prices or sellers missing MercadoLibre varies the fields shown by country, category, and viewport. Some fields are optional and appear only when the marketplace displays them in search results. ### Legality and ethical use This actor extracts publicly visible marketplace search data. Use it responsibly, respect applicable laws, and avoid collecting personal data beyond what is necessary for legitimate business workflows. ### Related scrapers - https://apify.com/automation-lab/amazon-search-scraper - https://apify.com/automation-lab/ebay-search-scraper - https://apify.com/automation-lab/walmart-search-scraper - https://apify.com/automation-lab/shopify-product-scraper ### Limitations The actor focuses on search/listing result pages. It does not open every product detail page in the MVP, which keeps runs cheaper and avoids unnecessary anti-bot exposure. ### Changelog Initial private build extracts MercadoLibre search listings with rank, price, shipping, seller, and metadata fields. ### Support If a run fails, include the input, target country, run URL, and whether proxy was enabled when contacting support. ### FAQ #### Can I scrape multiple countries in one run? Use separate runs per country for the clearest ranking metadata and matching proxy-country settings. #### Can I scrape category URLs? Yes. Add MercadoLibre category or search URLs in `startUrls`. #### Does it support product details? The MVP focuses on search result cards. Product-detail crawling can be added later if demand justifies the extra cost. #### Why is proxy enabled by default? MercadoLibre often blocks direct cloud or datacenter traffic with verification pages, so proxy defaults are conservative. # Actor input Schema ## `queries` (type: `array`): Keywords to search on the selected MercadoLibre country site. ## `startUrls` (type: `array`): Optional MercadoLibre search/category URLs. Use this for category pages or filtered search URLs. ## `site` (type: `string`): Country marketplace to search when using queries. ## `maxItems` (type: `integer`): Total number of listing rows to save across all searches. ## `maxPagesPerSearch` (type: `integer`): Safety cap for pagination on each query or start URL. ## `sort` (type: `string`): Sort search results. Relevance uses MercadoLibre's default ranking. ## `condition` (type: `string`): Filter by item condition when supported by the selected site. ## `useProxy` (type: `boolean`): Recommended. MercadoLibre often shows verification pages to datacenter or workspace IPs. ## `proxyGroups` (type: `array`): Proxy groups to use. RESIDENTIAL is recommended for MercadoLibre search pages. ## `proxyCountryCode` (type: `string`): Optional two-letter country code matching the target marketplace, e.g. MX, BR, AR, CO, CL, PE, UY, EC. ## Actor input object example ```json { "queries": [ "laptop gamer", "iphone 15" ], "startUrls": [ { "url": "https://listado.mercadolibre.com.mx/laptop-gamer" } ], "site": "MLM", "maxItems": 20, "maxPagesPerSearch": 2, "sort": "relevance", "condition": "all", "useProxy": true, "proxyGroups": [ "RESIDENTIAL" ], "proxyCountryCode": "MX" } ``` # Actor output Schema ## `overview` (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 = { "queries": [ "laptop gamer", "iphone 15" ], "startUrls": [ { "url": "https://listado.mercadolibre.com.mx/laptop-gamer" } ], "site": "MLM", "maxItems": 20, "maxPagesPerSearch": 2, "sort": "relevance", "condition": "all", "useProxy": true, "proxyGroups": [ "RESIDENTIAL" ], "proxyCountryCode": "MX" }; // Run the Actor and wait for it to finish const run = await client.actor("automation-lab/mercadolibre-search-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 = { "queries": [ "laptop gamer", "iphone 15", ], "startUrls": [{ "url": "https://listado.mercadolibre.com.mx/laptop-gamer" }], "site": "MLM", "maxItems": 20, "maxPagesPerSearch": 2, "sort": "relevance", "condition": "all", "useProxy": True, "proxyGroups": ["RESIDENTIAL"], "proxyCountryCode": "MX", } # Run the Actor and wait for it to finish run = client.actor("automation-lab/mercadolibre-search-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 '{ "queries": [ "laptop gamer", "iphone 15" ], "startUrls": [ { "url": "https://listado.mercadolibre.com.mx/laptop-gamer" } ], "site": "MLM", "maxItems": 20, "maxPagesPerSearch": 2, "sort": "relevance", "condition": "all", "useProxy": true, "proxyGroups": [ "RESIDENTIAL" ], "proxyCountryCode": "MX" }' | apify call automation-lab/mercadolibre-search-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=automation-lab/mercadolibre-search-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "MercadoLibre Search Scraper", "description": "Extract ranked MercadoLibre search results with prices, sellers, shipping badges, locations, thumbnails, and rank metadata for LATAM commerce monitoring.", "version": "0.1", "x-build-id": "DBmrA1NZwiFgz31wk" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/automation-lab~mercadolibre-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-automation-lab-mercadolibre-search-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/automation-lab~mercadolibre-search-scraper/runs": { "post": { "operationId": "runs-sync-automation-lab-mercadolibre-search-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/automation-lab~mercadolibre-search-scraper/run-sync": { "post": { "operationId": "run-sync-automation-lab-mercadolibre-search-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": { "queries": { "title": "Search queries", "type": "array", "description": "Keywords to search on the selected MercadoLibre country site.", "items": { "type": "string" } }, "startUrls": { "title": "Start URLs", "type": "array", "description": "Optional MercadoLibre search/category URLs. Use this for category pages or filtered search URLs.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "site": { "title": "MercadoLibre site", "enum": [ "MLM", "MLB", "MLA", "MCO", "MLC", "MPE", "MLU", "MEC" ], "type": "string", "description": "Country marketplace to search when using queries.", "default": "MLM" }, "maxItems": { "title": "Maximum listings", "minimum": 1, "maximum": 10000, "type": "integer", "description": "Total number of listing rows to save across all searches.", "default": 20 }, "maxPagesPerSearch": { "title": "Maximum pages per search", "minimum": 1, "maximum": 50, "type": "integer", "description": "Safety cap for pagination on each query or start URL.", "default": 5 }, "sort": { "title": "Sort order", "enum": [ "relevance", "price_asc", "price_desc", "newest", "best_selling" ], "type": "string", "description": "Sort search results. Relevance uses MercadoLibre's default ranking.", "default": "relevance" }, "condition": { "title": "Condition", "enum": [ "all", "new", "used" ], "type": "string", "description": "Filter by item condition when supported by the selected site.", "default": "all" }, "useProxy": { "title": "Use Apify Proxy", "type": "boolean", "description": "Recommended. MercadoLibre often shows verification pages to datacenter or workspace IPs.", "default": true }, "proxyGroups": { "title": "Proxy groups", "type": "array", "description": "Proxy groups to use. RESIDENTIAL is recommended for MercadoLibre search pages.", "items": { "type": "string" }, "default": [ "RESIDENTIAL" ] }, "proxyCountryCode": { "title": "Proxy country code", "minLength": 2, "maxLength": 2, "type": "string", "description": "Optional two-letter country code matching the target marketplace, e.g. MX, BR, AR, CO, CL, PE, UY, EC.", "default": "MX" } } }, "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 } } } } } } } } } } ```