# Mercadolivre Search Scraper (`yasmany.casanova/mercadolivre-search-scraper`) Actor Search Mercado Livre Brazil by term or by a search link with its filters, and get every product card: price, Pix and coupon prices, installments, seller, rating, units sold, FULL and free shipping. Up to 2000 results, sponsored cards flagged. - **URL**: https://apify.com/yasmany.casanova/mercadolivre-search-scraper.md - **Developed by:** [Yasmany Grijalba Casanova](https://apify.com/yasmany.casanova) (community) - **Categories:** E-commerce - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 product founds 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/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. 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. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## 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. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## Mercado Livre Search Scraper Search **Mercado Livre Brazil** and get every product card of the results: the **price**, the **Pix and coupon prices** next to the price in other payment methods, the **installment plan**, the **seller** and whether it is an official store, the **rating**, the **units sold**, **FULL** and **free shipping**, condition and variations. Search by term, or paste a search link with the filters you chose on the site. Up to 2000 results per search, sponsored cards flagged. [![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue?logo=apify)](https://apify.com) [![Proxy](https://img.shields.io/badge/Proxy-Your%20own-red)](#proxy-setup) [![Country](https://img.shields.io/badge/Country-Brazil-green)](https://www.mercadolivre.com.br) *** > ⚠️ **Bring your own proxy** > Mercado Livre serves its pages only to requests that pass its validation. This Actor needs **your provider's proxy URL with an unblocking mode** (offered under names such as unblocker, unlocker, stealth or scraping browser). Any provider works; the Actor is not tied to one. See [Proxy setup](#proxy-setup). > > A run without a proxy stops at the start and says so, without charge. *** ### Quick Start ```json { "query": "geladeira brastemp", "maxResults": 100, "proxyConfiguration": { "useApifyProxy": false, "proxyUrls": ["http://user:password@proxy.example.com:8000"] } } ``` #### Search with the site's filters Search on [mercadolivre.com.br](https://www.mercadolivre.com.br), choose the filters (FULL, free shipping, official stores, condition, price range, sorting) and paste the address of the results page exactly as the browser shows it: ```json { "query": "https://lista.mercadolivre.com.br/eletrodomesticos/refrigeracao/geladeiras/brastemp/geladeira-brastemp_Frete_Full_NoIndex_True", "maxResults": 500, "proxyConfiguration": { "useApifyProxy": false, "proxyUrls": ["http://user:password@proxy.example.com:8000"] } } ``` *** ### Features | Feature | Description | |---------|-------------| | **Every Price on the Card** | The headline price, what it depends on (Pix or a coupon), the price in other payment methods, the list price and the discount | | **Installments** | Number of installments, their value and whether they are interest free | | **Seller** | The seller's name as the card shows it, and whether it is an official store | | **Demand** | Rating and the units sold figure Mercado Livre shows | | **Delivery** | FULL fulfilment, free shipping, the delivery promise and international sellers | | **Search Links** | Paste a results page with its filters and sorting, and the Actor reads that search | | **Sponsored Cards** | Kept and flagged, or left out; positions and organic rank stay the same either way | | **Fair Billing** | You pay per product returned. The summary row and errors are free | *** ### Use Cases - **Price Monitoring**: Track prices, Pix discounts and coupons for a product line - **Competitor Analysis**: See which sellers and official stores rank for your keywords - **Assortment Research**: Map a category: brands, conditions, international sellers, FULL coverage - **Share of Search**: Measure organic and sponsored positions for a term over time *** ### Input Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `query` | string | none | **Required.** A search term (`geladeira brastemp`), or a link to a results page on `lista.mercadolivre.com.br` | | `maxResults` | integer | `50` | Products to return, from 1 to 2000 | | `includeSponsored` | boolean | `true` | Keep the sponsored cards, flagged with `is_sponsored` | | `proxyConfiguration` | object | none | **Required.** Your provider's proxy URL with an unblocking mode. See [Proxy setup](#proxy-setup) | | `maxConcurrency` | integer | `5` | Result pages fetched at once, 1 to 10. Lower it if your proxy plan allows fewer simultaneous connections | Mercado Livre lists 48 products per page plus up to 12 sponsored ones, and stops a search at about 2000 results. A link keeps its filters and sorting; the page number in it is ignored, and the search is read from its first page. Paste the whole address: Mercado Livre applies a filter only with the `_NoIndex_True` at its end, and without it answers the whole search. *** ### Proxy setup In the **Proxy** section of the input, choose **Own proxies** and enter your provider's proxy URL, such as `http://user:password@proxy.example.com:8000`. Use the provider's **unblocking mode**: Mercado Livre turns plain datacenter and residential proxies away with a captcha. ```json { "proxyConfiguration": { "useApifyProxy": false, "proxyUrls": ["http://user:password@proxy.example.com:8000"] } } ``` - Your provider bills you for its requests: one per results page. A page that is refused is tried up to 3 times, and once more later in the run, so 6 requests at most. - An unblocking proxy opens the page itself, so each page takes **30 to 60 seconds**. After the first page the Actor reads up to 5 pages at once (`maxConcurrency`): 500 results take about 3 minutes. - Apify Proxy can be selected too, but Mercado Livre turns away most requests through it, and the run says so. *** ### Output Example One row per product card: ```json { "record_type": "product", "query": "geladeira brastemp", "page": 1, "position": 5, "organic_rank": 1, "is_sponsored": false, "item_id": "MLB4468863199", "catalog_product_id": "MLB64339046", "user_product_id": "MLBU3746223881", "title": "Geladeira Brastemp Frost Free 385 Litros Duplex Inox - BRM46MK", "url": "https://www.mercadolivre.com.br/geladeira-brastemp-frost-free-385-litros-duplex-inox-brm46mk/p/MLB64339046", "image_url": "https://http2.mlstatic.com/D_NQ_NP_649286-MLA104374120634_012026-OO.jpg", "condition": "new", "offer_count": null, "price": 2685.93, "price_condition": "pix", "standard_price": 2769.0, "list_price": 3199.0, "discount_percentage": 16, "coupon_price": null, "currency": "BRL", "installment_count": null, "installment_value": null, "installment_interest_free": null, "seller_name": "Mercado Livre", "is_official_store": true, "rating": 4.8, "sold_quantity": 10000, "free_shipping": true, "is_full": true, "shipping_text": "Frete grátis", "ships_from_abroad": null, "highlight": null, "variations": [], "category_id": "MLB181294", "domain_id": "MLB-REFRIGERATORS", "scraped_at": "2026-10-27T14:28:51.412907+00:00" } ``` Each search ends with one `summary` row: the results Mercado Livre reports, the pages read, the products returned (sponsored among them), the category of the search, its first page, and whether it was complete. #### Three views of the same data | View | Columns | Use it for | |------|---------|------------| | **Products** (default) | Everything on the card | Assortment, ranking, the whole row | | **Prices** | Price, Pix and coupon prices, installments, seller | Price monitoring | | **Summary** | The summary row: results reported, pages read, products returned, complete | Checking a run | All three are on the **Output** tab and export to JSON, CSV or Excel. Through the API, add `?view=prices` or `?view=summary` to the dataset items URL. *** ### Data Fields | Field | Type | Description | |-------|------|-------------| | `record_type` | string | `product`, `summary` or `error` | | `query` | string | The search term or link, as given | | `page`, `position` | number | The results page, and the place in the list with sponsored cards counted | | `organic_rank` | number | The place among organic results only; null on sponsored cards | | `is_sponsored` | boolean | A sponsored placement | | `item_id` | string | The listing (anúncio) the card shows, `MLB...`. Null on a catalog card with several offers and none picked | | `catalog_product_id` | string | The catalog product, `MLB...`, when the listing is in Mercado Livre's catalog | | `user_product_id` | string | The seller's product, `MLBU...` | | `title`, `url`, `image_url` | string | Title, product page and full-size image | | `condition` | string | `new`, `used`, `refurbished` or `open_box` | | `offer_count` | number | On a catalog card with several offers and none picked, how many | | `price` | number | The price the card shows in large type | | `price_condition` | string | What that price depends on: `pix` or `coupon`; null when it is the price for every payment method | | `standard_price` | number | The price in the other payment methods ("ou R$ 2.769 em outros meios") | | `list_price`, `discount_percentage` | number | The struck-through price and the discount the card shows | | `coupon_price` | number | A price with a coupon, when the card offers one beside the price | | `currency` | string | `BRL` | | `installment_count`, `installment_value` | number | The installment plan on the card | | `installment_interest_free` | boolean | The installments are interest free ("sem juros") | | `seller_name` | string | The seller's name, when the card shows it (mostly official stores) | | `is_official_store` | boolean | The seller is an official store | | `rating` | number | The product's rating, 1 to 5 | | `sold_quantity` | number | The units sold figure, rounded down as Mercado Livre shows it: "+10 mil vendidos" is `10000` | | `free_shipping`, `is_full` | boolean | The card shows free delivery; the item ships through FULL | | `shipping_text` | string | The delivery promise ("Chegará grátis amanhã") | | `ships_from_abroad` | string | The country an international seller ships from, such as `China` | | `highlight` | string | The card's label: `MAIS VENDIDO`, `OFERTA IMPERDÍVEL`, `ÚLTIMAS 2`... | | `variations` | array | The colours or options the card lists | | `category_id`, `domain_id` | string | Mercado Livre's category and product domain | | `error` | object | On `error` rows: `error_code`, `message` and `details` | | `scraped_at` | string | ISO 8601 timestamp (UTC) | Prices of R$ 1.000 and more are shown without cents on the card. The Actor gives them back from the card's own data (its tracking data, or interest-free installments that add up to the price); on a card with neither, such as one with interest-bearing installments only, the price is the whole reais the card shows. The **Mercado Livre Product Scraper** reads the exact price. Delivery promises and free shipping are those Mercado Livre shows a visitor who is not logged in, for the location it guesses from the proxy. A card can show free delivery that is only free on a first purchase, which it does not say; the Product Scraper reads the product page, which does, and counts only delivery free for every buyer. *** ### Integrations Use the **API** tab on the Actor page to get ready-to-use code examples in **Python**, **JavaScript**, and **cURL**, generated with the correct parameters for immediate integration. *** ### FAQ
Why do I need my own proxy? Mercado Livre answers a request it does not trust with a captcha, and that includes plain datacenter and residential proxies. Proxy providers sell a mode that gets past this kind of validation, under names such as unblocker, unlocker, stealth or scraping browser. Enter that proxy URL in the input; your provider bills its requests.
How long does a search take? About a minute for the first page, and then up to 5 pages at once: 100 results take about 2 minutes, 500 about 3, 2000 about 10. Rows are saved as each page finishes, so you can read the first results while the run continues.
Why did the run fail with REQUEST_BLOCKED? Mercado Livre did not return the first page after several tries: the proxy did not get past its validation. Check that the proxy URL uses your provider's unblocking mode. `PROXY_FAILED` means the proxy did not connect at all: check its address and password. If a later page fails, the run keeps every page read before it and the summary row says `complete: false`.
Why does the search return products that do not match my term? That is what Mercado Livre shows for it: the site matches terms loosely, so a misspelt or very specific term brings related products. Use a search link with filters to narrow it.
Why are seller_name and rating empty on some cards? The card does not show them: Mercado Livre puts the seller's name mostly on official stores' cards, and a product nobody rated has no rating. The **Mercado Livre Product Scraper** reads the product page, which names every seller with its reputation.
What am I charged for? One event per product returned, sponsored ones included when you keep them. The summary row and error rows are not charged. Your proxy provider bills its own requests.
*** ### Support 1. **Check the FAQ** above for common questions 2. **Test with a small run**, `maxResults` set to 10, to confirm your proxy works 3. **Contact support** through [Apify](https://apify.com) for additional assistance # Actor input Schema ## `query` (type: `string`): What to search for, as you would type it on mercadolivre.com.br (e.g. geladeira brastemp, smart tv samsung 55). Or paste the address of a results page from lista.mercadolivre.com.br, with the filters you chose on the site (FULL, free shipping, official stores, condition, price range, sorting). ## `maxResults` (type: `integer`): Products to return, from 1 to 2000. Mercado Livre lists 48 products per page plus sponsored ones, and stops a search at about 2000 results. ## `includeSponsored` (type: `boolean`): Keep the sponsored cards Mercado Livre mixes into the results, flagged with is_sponsored. Turn off for organic results only. ## `proxyConfiguration` (type: `object`): Required: your proxy. Mercado Livre serves its pages only to requests that pass its validation, so choose your own proxies and enter your provider's proxy URL with an unblocking mode (offered under names such as unblocker, unlocker, stealth or scraping browser), e.g. http://user:password@proxy.example.com:8000. Apify Proxy can be selected too, but Mercado Livre turns away most requests through it. ## `maxConcurrency` (type: `integer`): Result pages fetched at once, from 1 to 10. Lower it if your proxy plan allows fewer simultaneous connections (it answers with errors such as 429 Too Many Requests). ## Actor input object example ```json { "query": "geladeira brastemp", "maxResults": 50, "includeSponsored": true, "proxyConfiguration": { "useApifyProxy": false }, "maxConcurrency": 5 } ``` # Actor output Schema ## `products` (type: `string`): One row per product card, plus a summary row ## `prices` (type: `string`): Price, Pix and coupon prices, installments and seller per card ## `summary` (type: `string`): One row per search: results, pages read, and whether it was complete # 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 = { "query": "geladeira brastemp", "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("yasmany.casanova/mercadolivre-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 = { "query": "geladeira brastemp", "proxyConfiguration": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("yasmany.casanova/mercadolivre-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 '{ "query": "geladeira brastemp", "proxyConfiguration": { "useApifyProxy": false } }' | apify call yasmany.casanova/mercadolivre-search-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,yasmany.casanova/mercadolivre-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/dc8WyHERQgRhuTWhn/builds/NSe3IpfJudC75WcvV/openapi.json