Mercado Libre Scraper & API — 17 Countries

Scrape Mercado Libre listings and product pages across 17 Latin American marketplaces with a single parser. Search by keyword, by category URL, or feed it product URLs directly.

Built on a browser with a coherent fingerprint and a residential proxy that exits in each marketplace's own country, because nothing else reaches the data: plain HTTP, a Chrome TLS fingerprint and even a solved proof-of-work all end at the anti-bot wall.

---

Why this one

Per-row currency. On six marketplaces — Uruguay, Paraguay, Dominican Republic, Nicaragua, Guatemala and Panama — the local currency and US$ appear in the same results page. Summing prices without reading each row's currency produces a meaningless number. Every row carries its own currency.

The dual-price pair, which nobody else returns. Venezuelan product pages show US$ 580.80 and Bs. 476,314. This Actor returns both plus exchange_rate_implied, derived from the page's structured data — not from the rendered price, which splits the cents into a separate element and shifts the rate by 0.14%. Measured across product pages on one day, the derived rate came out identical on every single one.

A primary key that does not lie. item_id comes from the page's embedded search results array. Three link shapes coexist on one results page — articulo.…/MLA-…, /p/MLA… and /up/MLAU… — and a URL pattern silently drops the third, which can be 40% of the page.

Blocking is reported, not hidden. The anti-bot wall answers HTTP 200 with a well-formed page and zero listings. Every run reports wall_hits, captcha_hits, retries and robots-policy counters, and a run that scraped nothing because every page was blocked fails instead of reporting success with zero rows.

---

Coverage

Site	Country	Currency	iphone results measured	Mixed currencies	Catalog pages	Installments
MLA	Argentina	ARS	5078	No	Yes	Yes
MLM	Mexico	MXN	6372	No	Yes	Yes
MCO	Colombia	COP	5305	No	Yes	Yes
MLC	Chile	CLP	3496	No	Yes	Yes
MLU	Uruguay	UYU	1882	Yes	Yes	Yes
MPE	Peru	PEN	2229	No	Yes	Yes
MLV	Venezuela	VES	436	No	No	No
MEC	Ecuador	USD	358	No	Yes	Yes
MBO	Bolivia	BOB	27	No	No	No
MPY	Paraguay	PYG	65	Yes	No	No
MRD	Dominican Republic	DOP	40	Yes	No	No
MCR	Costa Rica	CRC	60	No	No	No
MNI	Nicaragua	NIO	42	Yes	No	No
MGT	Guatemala	GTQ	30	Yes	No	No
MHN	Honduras	HNL	31	No	No	No
MSV	El Salvador	USD	29	No	No	No
MPA	Panama	PAB	26	Yes	No	No

Two different marketplaces in one platform. The large ones return thousands of results per query and use catalog product pages; the small ones return dozens, have no catalog pages, and one page is the entire result set — there is nothing to paginate. The Actor detects this: it requests the next page only when the previous one came back full, so a query in Panama costs exactly one page load.

Not available: Brazil (MLB) and Cuba (MCU). Brazil is out until there is a documented LGPD basis; Cuba is unreviewed and its proxy route is unverified. The Actor refuses those inputs with a clear error instead of silently accepting them.

---

Input

Field	Type	Default	What it does
siteId	string	MLA	Which marketplace. One of the 17 above
searchQueries	array	[]	Free-text searches, e.g. iphone
categoryUrls	array	[]	Category listing URLs to scrape directly
startUrls	array	[]	Listing or product URLs. Product URLs are scraped as detail pages
maxItems	integer	100	Hard cap on rows
scrapeDetail	boolean	false	Open every product page. Multiplies page loads by ~40
allowPagination	boolean	true	Follow _Desde_ pagination. See the note below
respectRobots	boolean	false	Skip every path robots.txt disallows
categorySlicing	boolean	true	Also fetch page 1 of each allowed sub-category
maxSlices	integer	20	Cap on sub-category pages per query
maxConcurrency	integer	2	Parallel pages. Each listing page is 2.4-4.5 MB
useCache	boolean	true	Reuse listings seen in the last 24 hours

{
  "siteId": "MLV",
  "searchQueries": ["iphone"],
  "maxItems": 500,
  "scrapeDetail": false
}

Pagination and robots.txt — read this before running

Mercado Libre's robots.txt allows page 1 of a search and disallows page 2 (Disallow: /*_Desde_).

• allowPagination is on by default, and with it on the Actor requests paths robots.txt disallows. You are the one running it.
• respectRobots: true stays inside the allowed paths. Coverage drops to page 1 per query plus category slices, and skipped pages are counted as pages_truncated_by_robots_policy.
• Either way there is a hard ceiling of roughly 2,000 items per query. Paginating to the very end of an Argentine iphone search reaches about 39% of what the site itself says it has. categorySlicing is the only route past that ceiling; how much extra coverage it gives has not been measured and is not promised.

---

Output

One row per listing, in snake_case. Product text stays in the marketplace's own language — Envío gratis, Frete grátis, Reacondicionado — because that is data, not interface.

From listing pages

Field	Notes
item_id	Primary key, cache key, dedupe key
title · url · thumbnail
price · currency · currency_symbol	Per row, never per marketplace
price_original	Only when a struck-through price is shown
seller_name · condition · shipping_text · installments_text	Fill rates vary widely by marketplace
variations_text
link_kind · is_catalog	publication, catalog or user_product
position · query · source_url	Where the row came from
site_id · scraped_at · from_cache · data_age_hours	Every row declares its age

Only with scrapeDetail: true

rating · reviews_count · location · sold_quantity_text · available_quantity_text · attributes · seller_id · description · images · brand · sku · availability · breadcrumb · warranty_text · price_local · currency_local · exchange_rate_implied

None of these appear on listing pages on any marketplace. Competing Actors that promise them from listings return null.

Stock and sales figures are ranges, not numbers. Mercado Libre publishes +25 vendidos, never 25 — its own API returns RANGO_1_50 for the same data. This Actor returns the text as served in sold_quantity_text. Any derived number is named _min, because a minimum is what it is. No exact integer is invented from a range.

Run statistics

Written to the log and to the RUN_STATS key-value record:

queries · pages_fetched · items_pushed · items_from_cache
wall_hits · captcha_hits · shell_hits · degraded_hits · retries · sessions_retired
pages_truncated_by_robots_policy · pages_disallowed_by_robots_fetched
detail_pages_fetched · pages_skipped_resumed · errors

Failed pages go to a separate ERRORS dataset, never mixed into the results.

---

Pricing

Pay per result, in two events, because opening a product page costs about 40 times what a listing row costs:

Event	What it is
item-scraped	One listing delivered
item-detail-scraped	One listing enriched with its product page

What is never charged:

1. Results that were not delivered.
2. Pages that hit the anti-bot wall. The wall costs a full browser load and the Actor absorbs it. You pay for data, not for attempts.
3. A product page that was not opened. If the detail fetch fails, you get the listing row and are charged the listing rate.

Cached rows are charged normally and always declare their age — from_cache, scraped_at, data_age_hours. In a marketplace, serving a cached price without saying how old it is would be selling a possibly false number.

---

Reliability

The site returns an anti-bot wall on a fraction of requests, and it answers HTTP 200 with a well-formed page. The Actor separates six different responses: a page with data, an exhausted page, the wall, a CAPTCHA, a page that had not finished rendering, and a page that returns a plausible but nearly empty result set. Only the first is treated as data. A wall retires the proxy session and retries with a fresh one.

A sustained CAPTCHA rate stops the run. This Actor never solves CAPTCHAs, by any method.

---

What this Actor does not do

• It never signs in. No account, no session cookies, no OAuth, no API key.
• It never solves CAPTCHAs.
• It does not scrape buyer questions or reviews. That is text written by identifiable people.
• It does not return seller phone numbers or email addresses. Some Actors in this category do. This one does not.
• It does not touch seller profile pages (/perfil/), which robots.txt disallows.
• It does not rehost images. Rows carry image URLs.
• It does not run on Brazil or Cuba.

Data removal

Listings are cached for at most 24 hours and every row declares its age. To request removal of a listing or of seller data, write to privacy@actorstack.dev with the item_id. Requests are actioned on receipt.