MercadoLivre search $1/1000 results

What does this MercadoLivre search scraper do?

This Actor extracts structured product data from MercadoLivre — Brazil's largest e-commerce marketplace — straight from its search results. Pass one or more keywords and get back clean JSON for every product, including title, price, discount, installments, rating, brand, seller, official-store and shipping info, FULL fulfillment, sponsored flag, and category. You can also choose how MercadoLivre orders the results — by relevance, lowest price, or highest price — so a run can return exactly the cheapest (or priciest) listings for each keyword.

Why scrape MercadoLivre search results?

• 📊 Price monitoring — track price changes, discounts, and installment offers for any product category over time.
• 🛒 Competitor research — see which sellers, prices, and products rank for your target keywords.
• 📈 Market analysis — aggregate listing data to find top-rated products, best-sellers, and high-volume sellers.
• 🔎 Lead generation — discover official brand stores and their catalogues at scale.
• 🔥 Trend discovery — spot emerging products and categories by keyword before competitors do.
• 🤖 Automation — schedule runs and push results into spreadsheets, databases, or dashboards through Apify integrations.

Why an Actor instead of doing it yourself?

Unlike a manual search, this Actor turns MercadoLivre's keyword results into structured data at scale. MercadoLivre's official API no longer offers free, open product search (it requires authenticated, restricted access), and the website is built for browsing one page at a time — so collecting listings by hand or with a DIY scraper means fighting pagination, sponsored listings, and bot protection.

How to use this MercadoLivre search scraper

1. Visit the Actor page on Apify and click Try for free — no credit card required.
2. In the Input tab, type one or more search terms (e.g. fitness, pets, mouse gamer).
3. Set Max Items to control how many products to scrape per term — you're charged per product returned.
4. Pick a Sort Results By order — keep Most relevant for MercadoLivre's default ranking, or switch to Lowest price first / Highest price first to scrape a price extreme.
5. Click Start and wait a few seconds for the run to finish.
6. Open the Output tab or download the dataset as JSON, CSV, Excel, or HTML.

To trigger a run via the Apify API:

curl -X POST \
  "https://api.apify.com/v2/acts/riseandcode~apify-mercadolivre-search/runs?token=<YOUR_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "searchTerms": ["fitness", "pets"],
    "maxItems": 100,
    "sortBy": "price_asc"
  }'

Input

Configure the Actor in the Input tab or via JSON.

Field	Type	Default	Description
searchTerms	string[]	["pets"]	Required. One or more search terms. Spaces are converted to dashes automatically.
maxItems	integer	50	Maximum products to scrape per search term (50–10000).
sortBy	string	relevance	Result ordering: relevance (MercadoLivre's default ranking), price_asc (lowest price first), or price_desc (highest price first).
excludeSponsored	boolean	false	Skip listings marked as sponsored ("Patrocinado"), leaving only the organic ranking.

Example input:

{
  "searchTerms": ["fitness", "pets"],
  "maxItems": 100,
  "sortBy": "price_asc"
}

Sorting by price

sortBy changes the order MercadoLivre itself applies before the Actor reads the page, so it decides which listings you get, not just how they are arranged:

• price_asc + maxItems: 50 returns the 50 cheapest listings for the keyword — the usual input for price-floor monitoring and repricing.
• price_desc returns the priciest end of the catalogue, useful for premium/high-ticket research.
• relevance keeps MercadoLivre's own ranking, which is what you want when you care about visibility (who ranks where for a keyword).

One thing worth knowing: a price-sorted run is far more stable between runs than a relevance run, which makes day-over-day diffs meaningful.

Excluding sponsored listings

MercadoLivre injects paid placements into its result grids, and they do not respect the ordering — set excludeSponsored: true to drop them and keep the organic ranking only.

Where this matters depends on sortBy. Measured on live pages, relevance results carry a sizeable share of sponsored cards, while price-sorted pages carried none at all. So the filter is close to a no-op on a price_asc run and a substantial change on a relevance one.

Filtered listings never count towards maxItems, so you still get the number of products you asked for — the Actor simply reads further down the results to find them.

Output

One dataset record is pushed per product listing. Download the dataset as JSON, CSV, Excel, or HTML from the Output tab or via the Apify API.

Output example

[
  {
    "searchTerm": "carregador celular",
    "position": 1,
    "productId": "MLB178925",
    "itemId": "MLB3456789012",
    "title": "Carregador Turbo 65W USB-C compatível com Samsung",
    "url": "https://www.mercadolivre.com.br/p/MLB178925",
    "thumbnail": "https://http2.mlstatic.com/D_NQ_NP_123456-MLB789.jpg",
    "seller": "Loja TechBrasil",
    "isOfficialStore": true,
    "brand": "Samsung",
    "price": 89.9,
    "originalPrice": 129.9,
    "currency": "BRL",
    "discountPercentage": 30,
    "installments": "ou 12x R$ 7,49 sem juros",
    "coupon": "Cupom 5% OFF",
    "rating": 4.8,
    "ratingCount": 3627,
    "soldQuantity": 500,
    "shipping": "Frete grátis",
    "isFreeShipping": true,
    "isFull": true,
    "highlight": "MAIS VENDIDO",
    "isSponsored": false,
    "isInternational": false,
    "location": null,
    "category": "MLB-CELL_PHONE_CHARGERS",
    "categoryId": "MLB1000",
    "vertical": "CORE",
    "totalResults": 12480,
    "scrapedAt": "2026-04-28T12:00:00.000Z"
  }
  //...
]

Output fields

Field	Type	Description
searchTerm	string	The search term that produced this result
position	number	1-based position in the results as ordered by sortBy, counted across pages (so with price_asc, position 1 is the cheapest listing)
productId	string | null	Catalog/product-group ID (e.g. MLB178925). Groups all seller offers for the same product. null for listings not linked to a catalog entry.
itemId	string | null	Individual listing ID (e.g. MLB3456789012). Unique per seller offer: two sellers listing the same product share a productId but differ here.
title	string	Product title
url	string	Product page URL
thumbnail	string | null	Product image URL
seller	string | null	Seller or official store name
isOfficialStore	boolean	Whether the seller carries the "Loja oficial" (official store) badge
brand	string | null	Product brand (e.g. "Samsung"). null for listings MercadoLivre does not tie to a catalog entry.
price	number | null	Current price in BRL
originalPrice	number | null	Original price before discount
currency	string	Always "BRL"
discountPercentage	number | null	Discount percentage (e.g. 30)
installments	string | null	Instalment text
coupon	string | null	Coupon badge on the card (e.g. "Cupom 5% OFF"). null when no coupon is offered.
rating	number | null	Average user rating (0–5)
ratingCount	number | null	Number of user ratings (e.g. 3627). null when unavailable.
soldQuantity	number | null	Lower bound on units sold, as MercadoLivre buckets it (25, 50, 100, 500, 1 000, 5 000, 10 000, …) — a card reading "+500 vendidos" reports 500. Read it as a floor and a demand signal, not an exact sales total. null when the site publishes no figure.
shipping	string | null	Shipping label (e.g. "Frete grátis", "Chegará grátis amanhã")
isFreeShipping	boolean	Whether the card promises free shipping — the filterable form of shipping, so you can sort or pivot on it without parsing Portuguese text
isFull	boolean	Whether the listing ships from a MercadoLivre fulfillment center (the FULL badge)
highlight	string | null	Badge text (e.g. "MAIS VENDIDO")
isSponsored	boolean	Whether the listing is a paid ad
isInternational	boolean	Whether the product is sold by a cross-border (international) merchant, indicated by the CBT badge on the card
location	string | null	Where the listing is, as printed on the card (e.g. "Quedas Do Iguaçu - Paraná", or a street address for a property). Only vehicles, real estate and services publish it — retail listings are null.
category	string | null	MercadoLivre domain ID (e.g. "MLB-CELL_PHONE_CHARGERS") — the site's semantic product type. May be null if unavailable.
categoryId	string | null	MercadoLivre category ID (e.g. "MLB1000") — the category-tree node, and the key the official MercadoLibre API accepts at /categories/{id}. Distinct from category above.
vertical	string | null	Marketplace vertical ("CORE" for retail, "MOT" for vehicles, "RES" for real estate)
totalResults	number | null	How many listings MercadoLivre reports for the whole search term (e.g. 12480), repeated on every record of that term — a market-size signal per keyword. It is not how many products a run returns (that is Max Items): the site resolves a broad term to a category, and its own pagination stops well before the total, so very large figures are not all reachable
scrapedAt	string	ISO 8601 timestamp of when the record was scraped

Looking for something else on MercadoLivre?

This Actor covers keyword search — the listing data shown on the results page. Two sibling Actors cover the rest:

• Daily deals — to catch whatever is on promotion across the marketplace right now, regardless of keyword, use our MercadoLivre Deals Scraper, which scrapes the Ofertas do Dia page and returns every discounted product with its deal type and discount percentage.
• Full product details & reviews — feed the product URLs or IDs returned here into our MercadoLivre Product Detail + Reviews to get specs, seller reputation, variants, stock, and customer reviews.

How much does it cost to scrape MercadoLivre?

This Actor uses Apify's pay-per-event pricing: you pay fixed prices for what the Actor does, and you are not charged separately for Apify platform usage (compute, bandwidth, or other infrastructure). There are just two charges:

Event	Price	When it applies
Per search	$0.04	Once for each search term started
Per result	$0.001 ($1.00 / 1,000 items)	For each product returned to the dataset

The per-search fee covers the fixed infrastructure every search relies on — premium residential IPs and the compute to reliably load and parse results — and applies on each term search starts.

Examples:

• One search term returning 50 products → $0.04 + 50 × $0.001 = $0.09
• Two search terms returning 50 products each → 2 × $0.04 + 2 × 50 × $0.001 = $0.18

Apify's free plan includes $5 of free usage per month — enough to try the Actor without paying anything.

Tips to keep costs low

• Set maxItems to only what you need — you pay per product returned.
• Each search term started incurs the per-search fee even if it returns few or no products, so prefer specific terms you know have matching listings.

FAQ

Is it legal to scrape MercadoLivre?

This Actor only collects publicly available product listing data — the same information visible to any visitor without logging in. No private user data is collected. Always comply with MercadoLivre's Terms of Service and applicable local laws. Do not use scraped data in ways that compete unfairly with MercadoLivre or its sellers.

Do I need an API key or MercadoLivre account?

No. The Actor works without any MercadoLivre credentials. You only need a free Apify account to run it.

Can I monitor prices on a schedule?

Yes. Use Apify Schedules to run the Actor automatically (e.g. daily) and store each run's dataset, then compare results over time to build price history.

Does sorting by price return the actual cheapest products?

It returns what MercadoLivre itself ranks as cheapest for that keyword — the same list you'd see using the site's "Menor preço" filter. The site's own ordering is not strictly monotonic, though. It occasionally misplaces a near-tie (R$ 35,17 landing just before R$ 34,90), and a couple of cards per page sit further outside the sequence — a R$ 22 listing showing up early in a "highest price first" run, for example. Those are not sponsored, and the price reported is exactly the one printed on the card: every case we inspected was a catalog listing (its url contains /p/), where the card shows the current winning offer while MercadoLivre appears to have ranked the entry on a different value. Nothing is missing from the result set — sort the dataset by price on your side if you need a strict ladder. Sponsored placements, which do ignore the ordering, were absent from every price-sorted page we measured, but excludeSponsored will drop them if any turn up.

Why is the top result of a "highest price first" run an absurd price?

Because a handful of sellers publish listings at a fictional price instead of taking them down, and price_desc sorts those straight to the top. On the keyword "teclado" we saw a notebook at R$ 100,000,000 and another at R$ 2,300,000. This is the value MercadoLivre actually shows on the card, not a parsing error, so the Actor reports it as-is. If you're researching the genuine premium end of a category, skip the first few records or discard anything above a plausible ceiling for that category.

What's the difference between category and categoryId?

They are two different MercadoLivre identifiers, and the site publishes both. category holds the domain ID — a semantic product type like MLB-COMPUTER_MICE — which is the field this Actor has returned since its first release, under that name. categoryId holds the category ID, the node of MercadoLivre's category tree (MLB1714), which is what the official MercadoLibre API takes at /categories/{id}. If you're joining this dataset to that API, categoryId is the key you want.

Why is location empty for most products?

Because MercadoLivre only prints a location on the verticals where it is part of the offer: vehicles, real estate and services. Measured across seven live result pages, every vehicle and property card carried one and no retail card did. So expect location on a honda civic or apartamento venda run, and null on a mouse run.

What if a search term returns no results?

You are still charged the per-search fee for it. Opening the results page costs the same proxy and compute whether MercadoLivre answers with 50 products or none, and that fee is what covers it — at $0.04, a term that finds nothing costs about four cents. It is a small amount, but it is worth searching terms you know have listings rather than probing with a long list of guesses.

Some fields come back as null — is that expected?

Yes. Not every listing includes all fields. For example, rating only appears when the product has reviews, and originalPrice only when a discount is active. brand and ratingCount are only available for listings tied to a product catalog entry, so individual seller offers and ads often leave them null. Missing fields are set to null rather than omitted so the schema is always consistent.

What's the ideal timeout?

On a clean run, 1,000 items typically land in 5–8 minutes. But don't size your timeout from that number: the timeout is a hard ceiling on the whole execution, retries included, and retries — not throughput — are what actually stretch a run. Keep the default (1 hour) for anything up to 2,500 total items (search terms × Max Items). Above that, budget for the worst case: 120 seconds + 1.5 seconds per item — for example, 5,000 total items → about 2 hours.

The scraper got bot-blocked — what can I do?

Blocks are rare: every run uses premium residential IPs and automatic retries to keep success rates high. If a run still comes back empty or partial, simply run it again — transient blocks usually clear on a retry.

Changelog

2026-09-01

• Improved how a run recovers when MercadoLivre declines to serve a page, so a retry is more likely to succeed than to hit the same wall.

2026-08-31

• Added categoryId and vertical fields to every record — MercadoLivre's category-tree ID (MLB1714) and marketplace vertical (CORE, MOT, RES), so results can be joined to the official MercadoLibre API or split by vertical. The existing category field is unchanged and still holds the domain ID.
• Added a location field to every record — where the listing is, as MercadoLivre prints it on the card. Populated for vehicles, real estate and services; null for retail, which the site does not localize.
• Added an isFreeShipping field to every record — the shipping label as a true/false column, so free-shipping listings are one filter away in a spreadsheet instead of a text match.
• Added a totalResults field to every record — how many listings MercadoLivre reports for the whole search term, so you can size a keyword's market from the same run that samples it. The run log reports it per term as well.

2026-08-29

• Fixed an issue where search terms containing punctuation — such as 100% pure whey — could return no results.
• Improved how a run reacts when MercadoLivre declines to serve a page, so affected runs finish much faster instead of spending time on retries.

Support

If you encounter a bug or have a suggestion for this Actor or for a new one, please reach out via the Issues tab or at contact.riseandcode@gmail.com and we'll look into it ASAP. We respond in English 🇺🇸 and Portuguese 🇧🇷.