By the end of this tutorial, you will have a Python script that turns a Mercado Livre Brasil keyword search into structured JSON: one row per listing with the price in Brazilian reais, the crossed-out original price and discount when the card shows one, the installment offer, the seller, condition, free-shipping and Full flags, rating and review count.
This is for anyone who follows prices on mercadolivre.com.br: watching notebook or phone prices, checking which offers ship free, or comparing what a brand store charges. We use the Apify Actor Mercado Livre Brazil Scraper (reventadata/mercadolivre-scraper), called from Python through the Apify API. You will learn how to configure a search, narrow it by condition, price band and shipping, run the Actor and read its rows.
⏱️ What it takes: one pip install, one environment variable and three short Python blocks.
Prerequisites
To follow this tutorial, you will need:
-
Python 3.11+ installed locally (
apify-client3.x requires it). - The Apify API client for Python.
- An Apify account and API token. Your token is on the API & Integrations page in Apify Console.
Install the client:
pip install "apify-client~=3.0"
The code reads the token from an environment variable:
export APIFY_API_TOKEN="your_apify_token_here"
What you'll achieve
You will run a keyword search on Mercado Livre Brasil and get back one row per listing card: itemId (the MLB... number), title, url, price in BRL, originalPrice and discountPercentage when the card shows a crossed-out price, installments, seller, condition, isFreeShipping, isFullFulfillment, rating, reviewsCount, imageUrl and matchedKeyword.
Note: The Actor is unofficial and not affiliated with Mercado Livre or Mercado Libre. It reads the search result pages on
lista.mercadolivre.com.br, one row per listing card, and does not open product pages.
Example use case: Suppose you want new Lenovo notebooks between R$ 1,500 and R$ 3,000 that ship free. Set searchQueries: ["notebook lenovo"], condition: "new", minPrice: 1500, maxPrice: 3000 and freeShippingOnly: true, and the dataset holds only listings that pass those filters.
Step 1: Access Mercado Livre Brazil Scraper
Go to the Mercado Livre Brazil Scraper page on Apify Store. Its README lists the input fields and shows a sample output record.
In this tutorial we run it from Python, so all we need from the page is the Actor name: reventadata/mercadolivre-scraper.
Step 2: Configure search parameters
The main input is searchQueries, the only required field: a list of keywords in Portuguese, as a shopper would type them, for example notebook lenovo, iphone 15 or vestido de festa. The Actor turns each keyword into a search URL on lista.mercadolivre.com.br (notebook lenovo becomes /notebook-lenovo), walks its result pages and saves one row per listing.
Let's initialize the client and define the input:
import os
from apify_client import ApifyClient
# 1. Initialize ApifyClient with token from environment
client = ApifyClient(os.environ["APIFY_API_TOKEN"])
# 2. Define the search parameters
run_input = {
"searchQueries": ["notebook lenovo"],
"condition": "all",
"maxItems": 20,
}
This is the Actor's own example input: the notebook lenovo search, any condition, stopping at 20 saved listings.
Step 3: Configure optional settings and filters
The Actor sends your filters to the site in the search URL and checks each row again before saving it:
| Parameter | Default | What it does |
|---|---|---|
searchQueries |
none (required) | Keywords to search. |
condition |
all |
all, new or used. |
minPrice, maxPrice
|
none | Whole reais. Sent as the site's price-range filter and checked on each row. |
freeShippingOnly |
false |
Keep only listings whose card says free shipping. |
maxItems |
100 |
Total listings to save across all keywords. |
proxyConfiguration |
on | Proxy handled for you by default. |
With every filter set (condition: "used", a 1,500 to 3,000 band, free shipping), the URL of the second result page looks like this:
https://lista.mercadolivre.com.br/notebook-lenovo_Condicao_Usado_PriceRange_1500-3000_CustoFrete_Gratis_Desde_49
💡 A few combinations that work well:
-
New only, in a budget:
condition: "new"withminPriceandmaxPrice. -
Free shipping only:
freeShippingOnly: true. -
Several products at once: put more keywords in
searchQueriesand raisemaxItems, since it is a total.
One filter is always on: listings whose title says the item is damaged or for parts (defeito, quebrado, para peças, para conserto, trincado, sucata) are dropped, accents or not.
Step 4: Run the Actor
Now we start the run with .call(), which waits until the Actor finishes, and then read the dataset:
# 3. Start the Actor run and wait for it to complete
print("Starting Mercado Livre extraction...")
run = client.actor("reventadata/mercadolivre-scraper").call(run_input=run_input)
if run is None or run.status != "SUCCEEDED":
status = run.status if run else "unknown"
raise SystemExit(f"Run did not succeed (status: {status}).")
# 4. Fetch the resulting dataset items
items = client.dataset(run.default_dataset_id).list_items().items
print(f"Extraction complete! Retrieved {len(items)} listings.\n")
Behind the scenes:
- The Actor fetches each result page with proxy handled for you.
- It walks the result pages in steps of 48 listings until
maxItemsis reached, a page holds fewer than 20 listings, or the results run out, and saves eachitemIdonce even when it appears under several keywords.
Step 5: View and download results
Let's print the fields that matter for price tracking:
for item in items:
print(item.get("title"))
print(f" Price: R$ {item.get('price')}")
if item.get("originalPrice") is not None:
print(f" Was: R$ {item['originalPrice']} ({item.get('discountPercentage')}% off)")
print(f" Seller: {item.get('seller')}")
print(f" Installments: {item.get('installments')}")
print(f" Free shipping: {item.get('isFreeShipping')}")
if item.get("rating") is not None:
print(f" Rating: {item.get('rating')} ({item.get('reviewsCount')} reviews)")
print("-" * 50)
The dataset also exports as JSON, CSV, XML, Excel, HTML table, RSS or JSONL.
Here is a sample from a run dated 2026-11-20: one listing from the notebook lenovo search, saved by the Actor (not output of the snippet above; scrapedAt, the time a row is built, is left out):
{
"itemId": "MLB80693418",
"title": "Notebook Lenovo Ideapad Core 3 304 8gb 128gb Ssd15.3 Fhd W11",
"url": "https://www.mercadolivre.com.br/notebook-lenovo-ideapad-core-3-304-8gb-128gb-ssd153-fhd-w11/p/MLB80693418",
"price": 2944,
"originalPrice": 3999,
"currency": "BRL",
"discountPercentage": 26,
"installments": "10x R$ 309,90 sem juros",
"seller": "Mercado Livre",
"condition": "new",
"isFreeShipping": true,
"isFullFulfillment": true,
"rating": 4.9,
"reviewsCount": 7,
"imageUrl": "https://http2.mlstatic.com/D_Q_NP_2X_786207-MLA120431028507_102026-E.webp",
"matchedKeyword": "notebook lenovo"
}
Understanding your results
The key fields:
-
itemId: the listing'sMLB...number. -
price: the selling price in BRL, parsed from the card's reais and centavos. -
originalPrice: the crossed-out price,nullwhen the card shows none. -
discountPercentage: the card's own discount label; computed from the two prices only when the card has no label. -
installments: the installment offer, such as10x R$ 309,90 sem juros. -
seller: the seller name on the card, with the leading "Por" removed. -
condition:usedwhen the title saysusadoorrecondicionado, otherwisenew. -
isFreeShipping: the card says "frete grátis" or "chegará grátis". -
isFullFulfillment: the card displays the Mercado Livre Full badge or fulfillment icon. -
rating,reviewsCount: each can benullwhen the listing has no value for it. -
matchedKeyword: which of your keywords found the listing.
In the sample, the discount and the prices agree: 3,999 minus 2,944 is 1,055 reais, 26.4% of the crossed-out price.
Pro tips
-
Use
itemIdas the key. It is the listing'sMLB...number, and the Actor saves each listing once per run, even when two keywords both find it. Line runs up byitemIdto follow a price. -
Read the full installment line on the card. In the sample,
installmentsreads "10x R$ 309,90 sem juros": ten payments total 3,099 reais, 155 more than the 2,944 price.installmentskeeps only that part, so multiply it out before you compare. -
Treat
conditionas a title check. It is set from the wordsusadoandrecondicionadoin the title. Withcondition: "used", a used listing whose title says neither is dropped. -
Check
isFullFulfillment. It is set when the card displays the Mercado Livre Full badge or icon. - Pick keywords with care. Rows are whatever the site returns for the search; the Actor does not re-check titles against your keyword, so check a small run's titles before you scale up.
Troubleshooting
-
Run ended FAILED with no rows: the Actor fails a run that saves zero listings when a search page was blocked, unreachable or showed no listing cards; a search whose cards were all dropped by your filters ends SUCCEEDED with a status message saying so. Check the keyword spelling, then loosen the price band,
conditionorfreeShippingOnly. -
Fewer rows than
maxItems: the results ran out, or filters dropped listings. Read the log withclient.log(run.id).get(): its summary line startsFinished Mercado Livre scraper: pushed N listing(s).and counts rejections by reason (price_out_of_bounds,condition_mismatch,no_free_shipping,damaged_parts_only,duplicate_item). -
Invalid
condition: it acceptsall,neworused; any other value is refused before the run starts. -
Prices with centavos:
priceis a number in reais, so2944is R$ 2.944,00.
Next steps
To repeat a search, save the input as a task and add an Apify schedule, which runs an Actor or task on a cron expression. To trigger your own code when a run succeeds, add a webhook on ACTOR.RUN.SUCCEEDED: its payload carries the run, including defaultDatasetId.
For current pricing and details, see the Store page.
Links:
What are you planning to scrape on Mercado Livre? Drop a comment! 💬
Top comments (0)