# MercadoLibre Search Scraper — Price, Seller & Rating (`khadinakbar/mercadolibre-search-scraper`) Actor Scrape MercadoLibre search results across 11 LATAM countries: title, price, discount, seller, rating, reviews, free shipping, installments, and result position. Keyword or search URL. MCP-ready. - **URL**: https://apify.com/khadinakbar/mercadolibre-search-scraper.md - **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community) - **Categories:** E-commerce, MCP servers - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $4.00 / 1,000 product listeds This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. 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 — Price, Seller & Rating Scrape **MercadoLibre search results** across 11 Latin American marketplaces. Give it a keyword or a search/category URL and get back clean, structured product cards: title, price, discount, seller, rating, free-shipping, installments, condition, and the result position — ready for price monitoring, market research, and AI agents. ### What it does For each keyword (or pasted search URL) the actor opens the MercadoLibre results page, paginates through the listing, and returns one row per product card. It auto-detects the country from the marketplace domain and renders pages through residential proxies so the data matches what a real shopper in that country sees. ### When to use it - **Price & promo monitoring** — track prices, discounts, and installments for a search term over time. - **Market & competitor research** — see who ranks for a keyword, official stores vs resellers, ratings, and ad placements. - **Catalog & assortment analysis** — pull the top N results for many keywords across countries. - **Feed an AI agent** — narrow input (keyword + country), structured JSON out, predictable per-result cost. Need full product detail pages (description, all photos, attributes, seller reputation)? This actor returns **search-result cards**, not product detail pages. Use it to discover items, then enrich the `url` / `itemId` separately. ### Supported countries Mexico (MX), Argentina (AR), Brazil/Mercado Livre (BR), Chile (CL), Colombia (CO), Uruguay (UY), Peru (PE), Ecuador (EC), Venezuela (VE), Bolivia (BO), Paraguay (PY). ### Output One dataset row per result card: | Field | Description | |---|---| | `position` | 1-based rank in the run | | `itemId` | MercadoLibre item id, e.g. `MLM1422978828` | | `title` | Product title | | `price` | Current price (number) | | `currency` | Marketplace currency, e.g. `MXN` | | `originalPrice` | Struck-through price before discount, when shown | | `discountPercent` | Discount %, when shown | | `condition` | `new` / `used` / `refurbished`, when labelled | | `sellerName` | Seller or official store, when shown | | `rating` | Average star rating 0–5, when shown | | `reviewsCount` | Number of reviews, when shown | | `freeShipping` | True when the card advertises free shipping | | `shippingText` | Raw shipping label, e.g. `Llega gratis hoy` | | `installments` | Installments text, e.g. `12 meses sin intereses de $675` | | `thumbnail` | Product image URL | | `isSponsored` | True for ads / promoted listings | | `url` | Product page URL | | `country` | Marketplace country code | #### Example row ```json { "position": 5, "itemId": "MLM63043376", "title": "Celular Motorola Moto G06 256gb 4gb Color Verde", "price": 2117, "currency": "MXN", "originalPrice": 5999, "discountPercent": 64, "sellerName": "Telmov", "rating": 4.8, "freeShipping": true, "shippingText": "Llega gratis hoy", "installments": "24 meses de $127.94", "thumbnail": "https://http2.mlstatic.com/D_Q_NP_2X_927719-MLA100483414444_122025-E.webp", "isSponsored": false, "url": "https://www.mercadolibre.com.mx/celular-motorola-moto-g06-256gb-4gb-color-verde/p/MLM63043376", "country": "MX" } ```` ### Pricing Pay-per-event: - **Actor start** — $0.005 per run (covers browser launch + proxy warm-up). - **Product listed** — $0.004 per result card returned. A 50-result run costs about **$0.21**; 1,000 results about **$4.00** plus the start fee. You are only billed for results actually returned. ### Input | Field | Type | Description | |---|---|---| | `searchQueries` | string\[] | Keywords to search, one per line. Defaults to `celular`. | | `startUrls` | string\[] | Full MercadoLibre search/category URLs; country auto-detected. | | `country` | enum | Marketplace for keyword searches. Default `MX`. | | `sort` | enum | `relevance`, `price_asc`, `price_desc`, `most_recent`. | | `maxResults` | integer | Total cards across all queries. Default 50, max 5000. | | `enableCaptchaSolver` | boolean | Solve reCAPTCHA walls automatically. Default true. | | `proxyConfiguration` | proxy | Primary proxy. **Residential strongly recommended.** | #### Example input ```json { "searchQueries": ["celular samsung", "notebook gamer"], "country": "MX", "sort": "price_asc", "maxResults": 100 } ``` #### Call from the API ```bash curl -X POST "https://api.apify.com/v2/acts/khadinakbar~mercadolibre-search-scraper/runs?token=YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "searchQueries": ["celular"], "country": "MX", "maxResults": 50 }' ``` #### Call from JavaScript (apify-client) ```js import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: 'YOUR_TOKEN' }); const run = await client.actor('khadinakbar/mercadolibre-search-scraper').call({ searchQueries: ['notebook gamer'], country: 'AR', maxResults: 200, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` ### Reliability & proxies MercadoLibre serves a *suspicious-traffic* / captcha wall to datacenter and out-of-country IPs. For the best success rate, set the proxy to **Apify Residential** with the country that matches your search. If a page is blocked, the actor automatically rotates to a fresh in-country residential IP and, when a reCAPTCHA wall appears, solves it — so blocked attempts are retried rather than returned empty. If every attempt is blocked and nothing is scraped, the run fails honestly with a clear message instead of reporting an empty success. ### MCP / AI agents This actor is MCP-ready: a single narrow input (`searchQueries` + `country`) returns compact, flat JSON rows. Discover it as `apify--mercadolibre-search-scraper`. ### FAQ **Does it return product detail pages?** No — it returns search-result cards. Use the `url`/`itemId` to fetch details separately. **Why are some prices without a discount?** The card simply isn't on promotion; `originalPrice`/`discountPercent` are omitted. **Can I scrape a filtered search?** Yes — apply filters on MercadoLibre in your browser and paste the resulting URL into `startUrls`. **Why is `reviewsCount` often empty?** MercadoLibre's compact search cards show the star rating but not always the review count. ### Legal This actor collects only publicly available data shown on MercadoLibre search pages. You are responsible for using the scraped data in compliance with MercadoLibre's Terms of Service, applicable laws (including data-protection and copyright law), and for not overloading the target site. It does not access private data or bypass authentication. Not affiliated with or endorsed by MercadoLibre / Mercado Livre. # Actor input Schema ## `searchQueries` (type: `array`): Free-text keywords to search on MercadoLibre, one per line (e.g. 'celular samsung', 'notebook gamer'). Each keyword runs against the country chosen below and is paginated up to maxResults. Defaults to 'celular'. NOT a URL — to scrape a specific results/category page paste it into startUrls instead. ## `startUrls` (type: `array`): Full MercadoLibre search or category result URLs, one per line (e.g. 'https://listado.mercadolibre.com.mx/celular' or a filtered listado/lista URL). The country is auto-detected from each URL's domain. Use this for pre-filtered searches you built in the browser. NOT a single product page — this actor scrapes results lists, not product details. ## `country` (type: `string`): MercadoLibre marketplace to search when using keywords (e.g. 'MX' for Mexico, 'BR' for Brazil/Mercado Livre). Sets the site domain and pins a matching in-country residential exit IP. Defaults to 'MX'. Ignored for startUrls, whose country comes from the URL. ## `sort` (type: `string`): Order of the keyword search results: relevance (MercadoLibre default), lowest price, highest price, or newest. Applies to keyword searches only. Defaults to 'relevance'. For startUrls the sort encoded in the URL is kept as-is. ## `maxResults` (type: `integer`): Maximum number of product cards to return across all keywords/URLs combined (MercadoLibre serves ~50 per page). Controls cost: you are billed per result returned. Defaults to 50, max 5000. MercadoLibre caps organic pagination near 2000 per search. ## `enableCaptchaSolver` (type: `boolean`): When MercadoLibre serves a reCAPTCHA wall on a retry, solve it automatically (managed 2captcha key, small extra cost per solve). Leave on for the highest success rate. Turn off to rely on proxy/IP rotation only. Defaults to true. ## `proxyConfiguration` (type: `object`): Proxy used for the primary fetch attempts. For the best success rate select Apify Proxy → RESIDENTIAL and the matching country; the actor falls back to managed in-country residential + captcha solving on blocks. Defaults to automatic Apify Proxy so runs always start. Datacenter IPs are blocked by MercadoLibre, so residential is strongly recommended. ## Actor input object example ```json { "searchQueries": [ "celular samsung", "notebook gamer" ], "startUrls": [ "https://listado.mercadolibre.com.mx/celular" ], "country": "MX", "sort": "relevance", "maxResults": 50, "enableCaptchaSolver": true, "proxyConfiguration": { "useApifyProxy": true } } ``` # Actor output Schema ## `datasetItemsJson` (type: `string`): All scraped result cards as JSON. ## `datasetItemsCsv` (type: `string`): All scraped result cards as CSV. ## `datasetUrl` (type: `string`): Console dataset view. # 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": [ "celular" ], "maxResults": 50, "proxyConfiguration": { "useApifyProxy": true } }; // Run the Actor and wait for it to finish const run = await client.actor("khadinakbar/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 = { "searchQueries": ["celular"], "maxResults": 50, "proxyConfiguration": { "useApifyProxy": True }, } # Run the Actor and wait for it to finish run = client.actor("khadinakbar/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 '{ "searchQueries": [ "celular" ], "maxResults": 50, "proxyConfiguration": { "useApifyProxy": true } }' | apify call khadinakbar/mercadolibre-search-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=khadinakbar/mercadolibre-search-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "MercadoLibre Search Scraper — Price, Seller & Rating", "description": "Scrape MercadoLibre search results across 11 LATAM countries: title, price, discount, seller, rating, reviews, free shipping, installments, and result position. Keyword or search URL. MCP-ready.", "version": "0.1", "x-build-id": "ieWQ3KbDyzzxGNtoo" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/khadinakbar~mercadolibre-search-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-khadinakbar-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/khadinakbar~mercadolibre-search-scraper/runs": { "post": { "operationId": "runs-sync-khadinakbar-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/khadinakbar~mercadolibre-search-scraper/run-sync": { "post": { "operationId": "run-sync-khadinakbar-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": { "searchQueries": { "title": "Search keywords", "type": "array", "description": "Free-text keywords to search on MercadoLibre, one per line (e.g. 'celular samsung', 'notebook gamer'). Each keyword runs against the country chosen below and is paginated up to maxResults. Defaults to 'celular'. NOT a URL — to scrape a specific results/category page paste it into startUrls instead.", "items": { "type": "string" } }, "startUrls": { "title": "Search / category URLs", "type": "array", "description": "Full MercadoLibre search or category result URLs, one per line (e.g. 'https://listado.mercadolibre.com.mx/celular' or a filtered listado/lista URL). The country is auto-detected from each URL's domain. Use this for pre-filtered searches you built in the browser. NOT a single product page — this actor scrapes results lists, not product details.", "items": { "type": "string" } }, "country": { "title": "Country", "enum": [ "MX", "AR", "BR", "CL", "CO", "UY", "PE", "EC", "VE", "BO", "PY" ], "type": "string", "description": "MercadoLibre marketplace to search when using keywords (e.g. 'MX' for Mexico, 'BR' for Brazil/Mercado Livre). Sets the site domain and pins a matching in-country residential exit IP. Defaults to 'MX'. Ignored for startUrls, whose country comes from the URL.", "default": "MX" }, "sort": { "title": "Sort order", "enum": [ "relevance", "price_asc", "price_desc", "most_recent" ], "type": "string", "description": "Order of the keyword search results: relevance (MercadoLibre default), lowest price, highest price, or newest. Applies to keyword searches only. Defaults to 'relevance'. For startUrls the sort encoded in the URL is kept as-is.", "default": "relevance" }, "maxResults": { "title": "Max results", "minimum": 1, "maximum": 5000, "type": "integer", "description": "Maximum number of product cards to return across all keywords/URLs combined (MercadoLibre serves ~50 per page). Controls cost: you are billed per result returned. Defaults to 50, max 5000. MercadoLibre caps organic pagination near 2000 per search.", "default": 50 }, "enableCaptchaSolver": { "title": "Solve captchas (2captcha)", "type": "boolean", "description": "When MercadoLibre serves a reCAPTCHA wall on a retry, solve it automatically (managed 2captcha key, small extra cost per solve). Leave on for the highest success rate. Turn off to rely on proxy/IP rotation only. Defaults to true.", "default": true }, "proxyConfiguration": { "title": "Proxy", "type": "object", "description": "Proxy used for the primary fetch attempts. For the best success rate select Apify Proxy → RESIDENTIAL and the matching country; the actor falls back to managed in-country residential + captcha solving on blocks. Defaults to automatic Apify Proxy so runs always start. Datacenter IPs are blocked by MercadoLibre, so residential is strongly recommended.", "default": { "useApifyProxy": true } } } }, "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 } } } } } } } } } } ```