# Mercadolivre Product Scraper (`yasmany.casanova/mercadolivre-product-scraper`) Actor Read Mercado Livre Brazil product pages: price, Pix price, installments, stock, the seller with its MercadoLíder level and reputation, ratings by stars, reviews, full spec sheet, photos, variations and the other offers. Up to 1000 products per run. - **URL**: https://apify.com/yasmany.casanova/mercadolivre-product-scraper.md - **Developed by:** [Yasmany Grijalba Casanova](https://apify.com/yasmany.casanova) (community) - **Categories:** E-commerce - **Security:** Limited permissions - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 product reads 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 Product Scraper Read **Mercado Livre Brazil** product pages and get everything they show: the **offer** (price, Pix price, installments, stock), **the seller** with its MercadoLíder level, reputation, sales, service and delivery marks, **FULL** and delivery, the **ratings by stars** with the review summary and the first reviews, the **full spec sheet**, the **photos**, the **variations** and **the other offers** of a catalog product. Up to 1000 products per run. [![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 { "products": [ "https://www.mercadolivre.com.br/geladeira-brastemp-frost-free-385-litros-duplex-inox-brm46mk/p/MLB64339046", "https://www.mercadolivre.com.br/headphone-philips-bluetooth-tah2209bk-preto-25h-bateria/p/MLB47648222" ], "proxyConfiguration": { "useApifyProxy": false, "proxyUrls": ["http://user:password@proxy.example.com:8000"] } } ``` > **Tip**: The **Mercado Livre Search Scraper** returns each result's product link. Paste those links here to read every product of a search with its seller and full page. *** ### Features | Feature | Description | |---------|-------------| | **The Offer** | Price, Pix price and the price in other payment methods, list price, discount, installments, units in stock | | **The Seller** | Name, page, official store, MercadoLíder level, reputation colour, sales, service and delivery marks | | **Delivery** | FULL fulfilment, the delivery promise, international sellers, the warranty | | **Ratings** | Rating, number of reviews, the count per star, the review summary and the first reviews | | **Catalog** | Brand, model, the full spec sheet, category, photos in full size, variations with their price and stock | | **Other Offers** | The other sellers' offers a catalog page lists beside the one it shows | | **Any Offer** | A catalog link with `?pdp_filters=item_id:MLB...` reads that listing's offer | | **Fair Billing** | You pay per product read with its offer. Products not found, out of stock, without an offer and errors are free | *** ### Use Cases - **Price Monitoring**: Track the price, Pix price and installments of your products and your competitors' - **Buy Box Watch**: See which seller holds a catalog product, and the other offers next to it - **Seller Analysis**: Compare sellers' MercadoLíder levels, reputations and delivery marks - **Catalog Enrichment**: Fill your catalog with specs, photos, variations and ratings - **Review Insight**: Rating distributions and Mercado Livre's own summary of the reviews *** ### Input Parameters | Parameter | Type | Default | Description | |-----------|------|---------|-------------| | `products` | array | none | **Required.** Product links, one per line, up to 1000. Repeats are read once | | `proxyConfiguration` | object | none | **Required.** Your provider's proxy URL with an unblocking mode. See [Proxy setup](#proxy-setup) | | `maxConcurrency` | integer | `10` | Products fetched at once, 1 to 50. Lower it if your proxy plan allows fewer simultaneous connections | A product is read from its page, as copied from the site: | Link | What it reads | |------|---------------| | `https://www.mercadolivre.com.br//p/MLB64339046` | A catalog product, shared by every seller: the offer Mercado Livre picks | | `https://www.mercadolivre.com.br/p/MLB64339046?pdp_filters=item_id:MLB6173551336` | That listing's offer on the catalog page | | `https://www.mercadolivre.com.br//up/MLBU3797247649`, or `MLBU3797247649` | A seller's own product page | An `MLB...` id alone can be a catalog product or a listing, so it needs its link. A listing's short link (`produto.mercadolivre.com.br/MLB-...`) is read too, but it only redirects to the product page and depends on the proxy following it: prefer the product page. An entry that is not a product is skipped, with an `error` row saying why, and the rest of the run goes on. *** ### 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 product. A page that is refused is tried up to 3 times; when the refusals came quickly, it gets one more round of 3 at the end of the run, so 6 requests at most. - An unblocking proxy opens the page itself, so each product takes **30 to 60 seconds**; the Actor reads 10 at a time (`maxConcurrency`), about 100 products in 8 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 (shortened here: the page has 10 photos, 40 specs and 5 reviews): ```json { "record_type": "product", "status": "available", "product_id": "MLB47648222", "item_id": "MLB5421210492", "catalog_product_id": "MLB47648222", "user_product_id": null, "title": "Headphone Philips Bluetooth TAH2209BK Preto 25h Bateria", "url": "https://www.mercadolivre.com.br/p/MLB47648222", "condition": "new", "brand": "Philips", "model": "TAH2209BK/00", "price": 116.0, "price_condition": null, "standard_price": 116.0, "list_price": null, "discount_percentage": null, "currency": "BRL", "installment_count": 12, "installment_value": 11.46, "installment_interest_free": false, "available_quantity": 50, "sold_quantity": 10000, "rating": 4.9, "review_count": 5290, "rating_distribution": { "5": 4878, "4": 282, "3": 70, "2": 22, "1": 38 }, "seller_id": "1384164924", "seller_name": "headhead", "seller_url": "https://www.mercadolivre.com.br/pagina/headhead", "is_official_store": false, "official_store_id": null, "seller_level": "MercadoLíder Platinum", "seller_reputation": "5_green", "seller_sales": 10000, "seller_service": "Bom atendimento", "seller_delivery": "Entrega no prazo", "listing_type": "gold_special", "is_full": true, "free_shipping": false, "shipping_text": "Chegará hoje grátis por ser sua primeira compra", "ships_from_abroad": null, "warranty": "12 meses de garantia de fábrica.", "highlights": ["MAIS VENDIDO", "5º em Fones de Ouvido Philips"], "best_seller_position": 5, "category": ["Eletrônicos, Áudio e Vídeo", "Áudio", "Fones de Ouvido", "Headphone"], "category_id": "MLB196208", "domain_id": "MLB-HEADPHONES", "image_url": "https://http2.mlstatic.com/D_NQ_NP_614675-MLA83205246100_042025-OO.jpg", "images": [ "https://http2.mlstatic.com/D_NQ_NP_614675-MLA83205246100_042025-OO.jpg", "https://http2.mlstatic.com/D_NQ_NP_828742-MLA83496395509_042025-OO.jpg" ], "variations": [ { "name": "Cor", "options": [ { "label": "Preto", "product_id": "MLB47648222", "selected": true, "price": 116.0, "available": true, "url": "https://www.mercadolivre.com.br/headphone-philips-bluetooth-tah2209bk-preto-25h-bateria/p/MLB47648222" } ] } ], "other_offers": [ { "type": "BEST_INSTALLMENTS", "item_id": "MLB6263926190", "selected": false, "price": 119.0, "list_price": null, "seller_name": "ON PLUS", "installments": "4x R$ 29,75 sem juros" }, { "type": "BEST_PRICE", "item_id": "MLB5421210492", "selected": true, "price": 116.0, "list_price": null, "seller_name": "headhead", "installments": null } ], "specs": { "Marca": "Philips", "Linha": "Auriculares", "Modelo": "TAH2209BK/00", "Cor": "Preto" }, "description": "HEADPHONE PHILIPS TAH2209BK – BLUETOOTH\nFone de ouvido Philips TAH2209BK com conexão Bluetooth e até 25 horas de autonom...", "review_summary": "O produto é altamente elogiado pelo conforto e materiais de boa qualidade, destacandose pelo design leve e adaptável...", "top_reviews": [ { "rating": 4, "text": "Fone de qualidade, demora bastante a descarregar e abafa o som exterior...", "date": "Há 1 ano", "likes": 124 } ], "input_url": "https://www.mercadolivre.com.br/p/MLB47648222", "scraped_at": "2026-10-27T14:41:07.338190+00:00" } ``` #### Two views of the same data | View | Columns | Use it for | |------|---------|------------| | **Products** (default) | Everything the page shows | Catalog, ratings, the whole row | | **Offers** | Price, Pix price, installments, stock, seller, other offers | Price and buy box monitoring | Both are on the **Output** tab and export to JSON, CSV or Excel. Through the API, add `?view=offers` to the dataset items URL. *** ### Data Fields | Field | Type | Description | |-------|------|-------------| | `record_type` | string | `product`, `not_found` (no such product) or `error` | | `status` | string | `available`, `out_of_stock`, `no_offer` (the page shows the product without an offer) or `offer_not_shown` (the link asked for a listing the page does not show) | | `product_id` | string | The product the link names: `MLB...` (catalog) or `MLBU...` (seller's product) | | `item_id` | string | The listing (anúncio) whose offer the row carries | | `catalog_product_id`, `user_product_id` | string | The catalog product and the seller's product of that listing | | `title`, `url`, `condition` | string | Title, product page, and `new`, `used` or `refurbished` | | `brand`, `model` | string | From the spec sheet | | `price` | number | The price in large type | | `price_condition` | string | What that price depends on: `pix`, `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 | | `currency` | string | `BRL` | | `installment_count`, `installment_value` | number | The installment plan | | `installment_interest_free` | boolean | The installments are interest free ("sem juros") | | `available_quantity` | number | Units in stock, rounded down as the page shows it: "+50 disponíveis" is `50` | | `sold_quantity` | number | Units sold, rounded down as the page shows it: "+10 mil vendidos" is `10000` | | `rating`, `review_count` | number | The rating, 1 to 5, and how many buyers rated | | `rating_distribution` | object | Ratings per star, `"5"` to `"1"` | | `seller_id`, `seller_name`, `seller_url` | string | The seller and its page | | `is_official_store`, `official_store_id` | boolean, number | The seller is an official store, and its id | | `seller_level` | string | `MercadoLíder`, `MercadoLíder Gold`, `MercadoLíder Platinum`; null without a level | | `seller_reputation` | string | Mercado Livre's reputation colour, `1_red` to `5_green` | | `seller_sales` | number | The seller's sales, rounded down as the page shows it | | `seller_service`, `seller_delivery` | string | The seller's marks: "Bom atendimento", "Entrega no prazo" | | `listing_type` | string | `gold_special` (Clássico) or `gold_pro` (Premium) | | `is_full`, `free_shipping` | boolean | Ships through FULL; delivery free for every buyer | | `shipping_text` | string | The delivery promise, as shown to a visitor who is not logged in | | `ships_from_abroad` | string | The country an international seller ships from, such as `China` | | `warranty` | string | The warranty the page states | | `highlights`, `best_seller_position` | array, number | Labels such as `MAIS VENDIDO`, `1º em Geladeiras`; the best seller rank | | `category`, `category_id`, `domain_id` | array, string | The category path and Mercado Livre's category and product domain | | `image_url`, `images` | string, array | The main photo and every photo, in full size | | `variations` | array | Each option list (colour, voltage...) with its options: label, product, price, stock, link | | `other_offers` | array | The offers a catalog page lists: type, listing, price, seller, installments, and which one is shown | | `specs` | object | The full spec sheet | | `description` | string | The seller's description | | `review_summary`, `top_reviews` | string, array | Mercado Livre's summary of the reviews, and the first reviews with their rating, date and likes | | `input_url` | string | The page read | | `error` | object | On `not_found` and `error` rows: `error_code`, `message` and `details` | | `scraped_at` | string | ISO 8601 timestamp (UTC) | Delivery promises are those Mercado Livre shows a visitor who is not logged in, for the location it guesses from the proxy. A promise that is free only on a first purchase ("grátis por ser sua primeira compra") or above an order value is not counted as `free_shipping`. Without an offer on the page (`no_offer`, `offer_not_shown`) the offer and seller columns are empty: they are never filled with another listing's offer. *** ### 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.
Which offer does a catalog link read? The one Mercado Livre shows on the page, the buy box. `other_offers` lists the others the page shows next to it, with their seller and price. To read one of them, add `?pdp_filters=item_id:` to the link; the **Mercado Livre Search Scraper** links sponsored results that way.
Why is a product "offer_not_shown" or "no_offer"? The page shows the product but no offer for it: the listing in the link is not the one Mercado Livre shows, or no seller is offering it now. Those rows keep the product's data (title, specs, ratings, photos) and are not charged.
Why did a product come back as an error? Mercado Livre did not return its page after its 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. Error rows are not charged; run those products again later. If 10 products in a row fail that way, the proxy is failing for all of them, so the run stops there instead of trying the rest, and its status message says how many were left untried.
What am I charged for? One event per product read with its offer (`available`). Rows `out_of_stock`, `not_found`, `no_offer`, `offer_not_shown` and `error` are not charged: an out-of-stock page has no price, seller or delivery to deliver. A product given twice is read, and charged, once. Your proxy provider bills its own requests.
*** ### Support 1. **Check the FAQ** above for common questions 2. **Test with the prefilled example**, with your proxy, to confirm it works 3. **Contact support** through [Apify](https://apify.com) for additional assistance # Actor input Schema ## `products` (type: `array`): Mercado Livre product links, one per line, up to 1000: catalog pages (/p/MLB...) or sellers' product pages (/up/MLBU...), as copied from the site or from the Mercado Livre Search Scraper. A catalog link with ?pdp_filters=item_id:MLB... reads that listing's offer. A seller's product ID alone (MLBU...) works too. ## `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`): Products fetched at once, from 1 to 50. 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 { "products": [ "https://www.mercadolivre.com.br/geladeira-brastemp-frost-free-385-litros-duplex-inox-brm46mk/p/MLB64339046", "https://www.mercadolivre.com.br/headphone-philips-bluetooth-tah2209bk-preto-25h-bateria/p/MLB47648222" ], "proxyConfiguration": { "useApifyProxy": false }, "maxConcurrency": 10 } ``` # Actor output Schema ## `products` (type: `string`): One row per product link with everything the page shows ## `offers` (type: `string`): Price, Pix price, installments, stock and seller of each offer # 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 = { "products": [ "https://www.mercadolivre.com.br/geladeira-brastemp-frost-free-385-litros-duplex-inox-brm46mk/p/MLB64339046", "https://www.mercadolivre.com.br/headphone-philips-bluetooth-tah2209bk-preto-25h-bateria/p/MLB47648222" ], "proxyConfiguration": { "useApifyProxy": false } }; // Run the Actor and wait for it to finish const run = await client.actor("yasmany.casanova/mercadolivre-product-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 = { "products": [ "https://www.mercadolivre.com.br/geladeira-brastemp-frost-free-385-litros-duplex-inox-brm46mk/p/MLB64339046", "https://www.mercadolivre.com.br/headphone-philips-bluetooth-tah2209bk-preto-25h-bateria/p/MLB47648222", ], "proxyConfiguration": { "useApifyProxy": False }, } # Run the Actor and wait for it to finish run = client.actor("yasmany.casanova/mercadolivre-product-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 '{ "products": [ "https://www.mercadolivre.com.br/geladeira-brastemp-frost-free-385-litros-duplex-inox-brm46mk/p/MLB64339046", "https://www.mercadolivre.com.br/headphone-philips-bluetooth-tah2209bk-preto-25h-bateria/p/MLB47648222" ], "proxyConfiguration": { "useApifyProxy": false } }' | apify call yasmany.casanova/mercadolivre-product-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,yasmany.casanova/mercadolivre-product-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/Uu5dyedc7DbgxOiY8/builds/6upqDDSZlEReluKXw/openapi.json