# MercadoLibre Search Scraper (`parsebird/mercadolibre-search-scraper`) Actor Search MercadoLibre by keyword or scrape a results URL to extract product listings: titles, prices, discounts, installments, shipping, sellers, and ratings. - **URL**: https://apify.com/parsebird/mercadolibre-search-scraper.md - **Developed by:** [ParseBird](https://apify.com/parsebird) (community) - **Categories:** E-commerce, Lead generation, Automation - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing from $2.00 / 1,000 product scrapeds 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/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. 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. - **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use). - **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`. - **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`. - **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`. - **Any other language** — 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 Search **MercadoLibre** by keyword or scrape any search, category, or filtered results URL and get clean, structured product data — no coding required.
Search by keyword or paste a results URL, filter by price range, condition, free shipping, and official store, and get titles, prices, discounts, installment plans, shipping, sellers, and ratings as ready-to-use data.
##### Copy to your AI assistant Copy this block into ChatGPT, Claude, Cursor, or any LLM to start using this actor. ``` Use the Apify actor "parsebird/mercadolibre-search-scraper" via the ApifyClient. Example (Python): from apify_client import ApifyClient; client = ApifyClient(""); run = client.actor("parsebird/mercadolibre-search-scraper").call(run_input={"target": "keywordSearch", "targets": ["iphone"], "country": "CO", "sortBy": "relevance", "condition": "any", "maxResults": 20}); items = list(client.dataset(run["defaultDatasetId"]).iterate_items()). Key inputs: target ("keywordSearch" or "resultsUrls"), targets (string array of keywords), startUrls (array of {url} objects for resultsUrls mode), country (CO/PE/UY/EC/DO), sortBy (relevance/price_asc/price_desc), condition (any/new/used), minPrice, maxPrice, freeShipping (boolean), officialStore (boolean), startPage, maxResults. Output fields per item: productId, title, url, imageUrl, searchRank, pageNumber, sourceTarget, sourceUrl, country, currency, currentPrice, previousPrice, discountPercent, installmentsText, shippingText, freeShipping, sellerName, isOfficialStore, isSponsored, rating, categoryId, condition, variations. Full API spec: https://apify.com/parsebird/mercadolibre-search-scraper/api. Get an API token at https://console.apify.com/settings/integrations. ``` ### What does MercadoLibre Search Scraper do? MercadoLibre Search Scraper extracts product listings from [MercadoLibre](https://www.mercadolibre.com/) search results without touching the site's login wall or CAPTCHA. Point it at a keyword or a results URL and it returns structured data for every listing on the page — the same information you'd see scrolling through search results, ready for a spreadsheet or database. 🔎 **Two ways to search** — type keywords and let the actor build the search URL, or paste your own MercadoLibre search, category, or already-filtered results URL directly. 💰 **Server-side filtering** — price range, condition (new/used), free shipping, and official-store filters are applied on MercadoLibre's own search, not guessed client-side. 📄 **Automatic pagination** — set a `maxResults` target and the actor pages through results on its own, de-duplicating listings along the way. 🏷️ **Rich per-listing data** — price, previous price, discount percentage, installment text, shipping badge, seller name, official-store flag, sponsored flag, rating, category ID, and condition, extracted from MercadoLibre's own page data rather than scraped off rendered HTML text. ☁️ **Runs on Apify** — schedule recurring runs, trigger it from the [API](https://docs.apify.com/api/v2) or [integrations](https://apify.com/integrations) (Zapier, Make, n8n, Google Sheets), and export results as JSON, CSV, or Excel. ### What data can you extract from MercadoLibre? | Field | Description | |-------|-------------| | `title` | Product title as shown on the listing card | | `currentPrice` / `previousPrice` | Current and pre-discount price | | `discountPercent` | Discount percentage, when shown | | `installmentsText` | Visible installment/payment plan text | | `shippingText` / `freeShipping` | Shipping badge text and whether it's free | | `sellerName` / `isOfficialStore` | Seller or official-store name, and whether it's an official store | | `isSponsored` | Whether the listing is a paid/sponsored placement | | `rating` | Star rating, when shown on the card | | `categoryId` / `condition` | MercadoLibre category ID and item condition | | `imageUrl` / `url` | Product image and a clean, direct product URL (including for sponsored listings) | See the [Output example](#output-example) below for the full field list. ### Input parameters | Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | target | string | No | keywordSearch | `keywordSearch` or `resultsUrls` | | targets | string array | For keyword search | `["iphone"]` | Keywords to search | | startUrls | object array | For results URLs | — | `{url}` objects — MercadoLibre search/category/filtered URLs | | country | string | No | CO | Marketplace: CO, PE, UY, EC, or DO | | sortBy | string | No | relevance | relevance, price\_asc, or price\_desc | | condition | string | No | any | any, new, or used | | minPrice / maxPrice | integer | No | — | Local-currency price bounds | | freeShipping | boolean | No | false | Keep only free-shipping listings | | officialStore | boolean | No | false | Keep only official-store listings | | postalCode | string | No | — | Accepted but has no effect yet — see FAQ | | startPage | integer | No | 1 | Results page to start from (48–60 listings/page depending on category) | | maxResults | integer | No | 20 | Max products to return; 0 = unlimited (960-item safety ceiling per keyword/URL) | ### How to use MercadoLibre Search Scraper 1. Open the actor's [Input tab](https://apify.com/parsebird/mercadolibre-search-scraper/input-schema) in Apify Console. 2. Choose **Keyword search** and list one or more product keywords, or choose **Results URLs** and paste MercadoLibre search/category URLs directly. 3. Pick a marketplace (Colombia, Peru, Uruguay, Ecuador, or Dominican Republic) and optionally set price range, condition, shipping, or official-store filters. 4. Set **Max results** and click **Start**. 5. When the run finishes, open the **Dataset** tab and export as JSON, CSV, or Excel, or pull results with the [Apify API](https://docs.apify.com/api/v2) or [client libraries](https://docs.apify.com/api/client). #### Python ```python from apify_client import ApifyClient client = ApifyClient("") run = client.actor("parsebird/mercadolibre-search-scraper").call(run_input={ "target": "keywordSearch", "targets": ["iphone"], "country": "CO", "maxResults": 20, }) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item["title"], item["currentPrice"], item["currency"]) ``` #### JavaScript ```javascript import { ApifyClient } from 'apify-client'; const client = new ApifyClient({ token: '' }); const run = await client.actor('parsebird/mercadolibre-search-scraper').call({ target: 'keywordSearch', targets: ['iphone'], country: 'CO', maxResults: 20, }); const { items } = await client.dataset(run.defaultDatasetId).listItems(); console.log(items); ``` ### Output example ```json { "productId": "MCO1066130043", "title": "Apple iPhone 17e (256 Gb) - Rosa Pálido - Distribuidor Autorizado", "url": "https://www.mercadolibre.com.co/apple-iphone-17e-256-gb-rosa-palido-distribuidor-autorizado/p/MCO1066130043", "imageUrl": "https://http2.mlstatic.com/D_Q_NP_2X_663455-MLA107261194434_032026-E.webp", "searchRank": 1, "pageNumber": 1, "sourceTarget": "iphone", "sourceUrl": "https://listado.mercadolibre.com.co/iphone_NoIndex_True", "country": "CO", "postalCode": null, "currency": "COP", "currentPrice": 3299900, "previousPrice": 3479000, "discountPercent": 5.0, "installmentsText": "12 cuotas de $274.992 con 0% interés", "shippingText": "Llega gratis el lunes", "freeShipping": true, "sellerName": "Apple", "isOfficialStore": true, "isSponsored": false, "rating": null, "reviewCount": null, "categoryId": "MCO1055", "condition": null, "variations": [] } ``` ### Use cases - Track competitor pricing and discounts across MercadoLibre categories - Monitor your own official-store listings against third-party sellers - Build a price-comparison feed for a specific product line - Research shipping and installment-plan offers by category or seller - Feed structured MercadoLibre data into a BI dashboard or spreadsheet on a schedule ### How much does it cost to scrape MercadoLibre? This actor uses [pay-per-event pricing](https://docs.apify.com/platform/actors/publishing/monetize#pay-per-event-pricing) — you pay per product saved, not per compute second. | Event | Price per event | Price per 1,000 | |-------|-----------------|-----------------| | product-scraped | $0.0026 | **$2.60** | Scraping 1,000 products costs about $2.60. A quick 20-item test run (the default) costs about $0.05. New Apify accounts get free platform credits, so you can try this actor without entering a card. ### FAQ **Which MercadoLibre countries are supported?** Colombia, Peru, Uruguay, Ecuador, and Dominican Republic. Mexico, Argentina, Chile, and Brazil are deliberately excluded — live testing found their `listado.*` search pages sit behind a much stricter, often CAPTCHA-backed anti-bot layer than the other five marketplaces, even through a country-matched residential proxy, so results there would be unreliable. Product-detail-page scraping for those markets is available on the sibling [MercadoLibre Scraper](https://apify.com/parsebird/mercadolibre-scraper) actor instead. **Why does the postal code field have no effect?** Changing MercadoLibre's delivery location requires completing an authenticated address-confirmation flow inside the page (a modal, not a URL parameter). This actor doesn't automate that flow, so `postalCode` is accepted and echoed back in the output for compatibility, but results reflect each marketplace's default location rather than a specific delivery address. **Is there a "newest" sort option?** No — MercadoLibre's own search UI only offers relevance, lowest price, and highest price sorting. There's no date/newest sort to expose. **Why did my run return fewer results than `maxResults`?** Either the search genuinely has fewer matching products, or MercadoLibre's anti-bot layer blocked a page after repeated retries (the actor retries with a fresh proxy session automatically, then logs a warning and moves on rather than failing the whole run). Very specific filter combinations — especially combining a price range with price sorting — are more prone to this; the actor already routes around that specific combination by sorting results itself instead of asking MercadoLibre to. **Can I scrape a URL I built myself with filters already applied?** Yes — set Search mode to **Results URLs** and paste the URL. The actor scrapes it as-is and paginates from there; the price/condition/shipping filters in the input are ignored in this mode since your URL already encodes them. **Can I schedule recurring runs or get notified of price changes?** Yes. Use Apify's [Scheduler](https://docs.apify.com/platform/schedules) to run this actor on a recurring basis, and combine it with a downstream integration (Zapier, Make, webhooks) to act on the results. **Something not working?** Open an issue on the actor's Issues tab in Apify Console, or check the [API reference](https://apify.com/parsebird/mercadolibre-search-scraper/api) for integration details. ### Other MercadoLibre scrapers - [MercadoLibre Scraper](https://apify.com/parsebird/mercadolibre-scraper) — product detail pages, reviews, and seller storefronts across all nine LATAM marketplaces ### Is it legal to scrape MercadoLibre? Scraping publicly available data is generally legal, but you're responsible for how you use the data and for complying with MercadoLibre's terms of service and applicable law in your jurisdiction, including data protection regulations if you collect personal data. See Apify's [blog post on the legality of web scraping](https://blog.apify.com/is-web-scraping-legal/) for more detail. This actor only reads publicly visible search-results data and does not bypass any login wall. # Actor input Schema ## `target` (type: `string`): 'Keyword search' builds search URLs from the keywords below. 'Results URLs' scrapes the exact search, category, or filtered listing URLs you paste in — the marketplace filters below (sort, price, condition, shipping) are ignored in this mode since your URL already encodes them. ## `targets` (type: `array`): One or more product keywords to search for. Used when Search mode is 'Keyword search'. ## `startUrls` (type: `array`): MercadoLibre search, category, or already-filtered listing URLs to scrape directly. Used when Search mode is 'Results URLs', for example a URL you built yourself on mercadolibre.com.co with filters already applied. ## `country` (type: `string`): Which MercadoLibre marketplace to search. Only used for 'Keyword search' — a Results URL keeps its own country domain. Limited to the five marketplaces that passed repeated live anti-bot testing; see the README for details on the excluded countries. ## `sortBy` (type: `string`): Order for keyword search results. MercadoLibre's search only offers these three orders — there is no "newest" sort on the live site. ## `condition` (type: `string`): Keep all products, or filter to only new or only used/refurbished listings. ## `minPrice` (type: `integer`): Only keep listings priced at or above this amount, in the marketplace's local currency (e.g. COP for Colombia). Leave empty for no minimum. ## `maxPrice` (type: `integer`): Only keep listings priced at or below this amount, in the marketplace's local currency. Leave empty for no maximum. ## `freeShipping` (type: `boolean`): Keep only listings that advertise free shipping. ## `officialStore` (type: `boolean`): Keep only listings from marketplace official stores (e.g. the brand's own storefront). ## `postalCode` (type: `string`): Accepted for compatibility, but has no effect yet: changing MercadoLibre's delivery location requires an authenticated address-confirmation flow (a modal, not a URL parameter) that this actor does not automate. Results reflect each marketplace's default location. Echoed back in the 'postalCode' output field as-is. ## `startPage` (type: `integer`): Which results page to start scraping from (48 listings per page). Default is 1, the first page. ## `maxResults` (type: `integer`): Maximum number of products to save across all keywords or URLs. Leave empty or 0 to return everything available, up to a 960-item (20-page) safety ceiling per keyword or URL. ## Actor input object example ```json { "target": "keywordSearch", "targets": [ "iphone" ], "startUrls": [ { "url": "https://listado.mercadolibre.com.co/iphone" } ], "country": "CO", "sortBy": "relevance", "condition": "any", "freeShipping": false, "officialStore": false, "startPage": 1, "maxResults": 20 } ``` # Actor output Schema ## `dataset` (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 = { "target": "keywordSearch", "targets": [ "iphone" ], "startUrls": [ { "url": "https://listado.mercadolibre.com.co/iphone" } ], "country": "CO", "sortBy": "relevance", "condition": "any", "startPage": 1, "maxResults": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("parsebird/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 = { "target": "keywordSearch", "targets": ["iphone"], "startUrls": [{ "url": "https://listado.mercadolibre.com.co/iphone" }], "country": "CO", "sortBy": "relevance", "condition": "any", "startPage": 1, "maxResults": 20, } # Run the Actor and wait for it to finish run = client.actor("parsebird/mercadolibre-search-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 '{ "target": "keywordSearch", "targets": [ "iphone" ], "startUrls": [ { "url": "https://listado.mercadolibre.com.co/iphone" } ], "country": "CO", "sortBy": "relevance", "condition": "any", "startPage": 1, "maxResults": 20 }' | apify call parsebird/mercadolibre-search-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,parsebird/mercadolibre-search-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 ` 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/u127eUczohEkld8vx/builds/oGXZjiUYO5OozTlhl/openapi.json