Mercado Livre BR — Product Search Scraper API

🇺🇸 English | 🇧🇷 Português

What this does

Extract structured product data from Mercado Livre Brasil — search results to JSON, no API key, residential proxy included. Returns up to ~2,000 products per keyword in minutes.

✓ Validated 2026-05-24: 25/25 products extracted and validated against production SERP in 7s (smoke test).

Quick example

Input:

{ "query": "notebook gamer", "maxItems": 50 }

Output (first result, real data from smoke test):

{
  "title": "Notebook Gamer Lenovo LOQ 15IRX9 Intel Core i5-13450HX RTX 3050 8GB 512GB SSD windows 11",
  "price": "5279.00",
  "original_price": "7299.00",
  "discount": 27,
  "currency": "BRL",
  "product_url": "https://click1.mercadolivre.com.br/mclics/clicks/external/MLB/count",
  "image_url": "https://http2.mlstatic.com/D_Q_NP_2X_709548-MLA88463970962_072025-E.webp",
  "seller_name": "Mercado Livre",
  "seller_location": null,
  "seller_rating": null,
  "rating": null,
  "reviews_count": null,
  "installments": "ou R$ 5.999 em 10x R$ 599 , 90 sem juros",
  "categories": [],
  "badges": ["FULL"],
  "sponsored": true,
  "shipping_free": true,
  "shipping_cost": null,
  "scraped_at": "2026-05-25T02:09:46.487016Z"
}

Output fields

Field	Type	Notes
title	string	Product name as shown on the search card.
price	number|null	Current price in BRL.
original_price	number|null	Pre-discount price (strikethrough).
discount	int|null	Discount percentage (e.g. 15).
currency	string	Always "BRL".
product_url	string	Canonical URL, tracking params stripped.
image_url	string|null	Main product image.
seller_name	string|null	Store name when visible on card.
seller_location	null	Always null in v0.1 — see Known limits.
seller_rating	null	Always null in v0.1 — see Known limits.
rating	float|null	0.0–5.0 stars when shown.
reviews_count	int|null	Number of reviews when shown.
installments	string|null	Raw installment text as displayed by ML. Format varies between cards (ex: "em 10x R$ 491,50", "ou R$ 5.174 em 10x R$ 517,47 sem juros"). Parse client-side if needed.
categories	string[]	Always [] in v0.1 — see Known limits.
badges	string[]	Normalized tokens from {FULL, MAIS VENDIDO, OFERTA DO DIA, RECOMENDADO, FRETE GRÁTIS}.
sponsored	bool	True for ads slots.
shipping_free	bool	True when "Frete grátis" is displayed.
shipping_cost	number|null	Always null in v0.1 (rarely on SERP).
scraped_at	string	ISO 8601 UTC timestamp.

Use cases

• Price monitoring (e-commerce sellers): track competitor pricing daily across ML categories; export to BigQuery / Sheets.
• Market intelligence (brands): detect MAP violations and unauthorized resellers; alert on price drops > X%.
• AI agents (Claude / Cursor users): real-time BR pricing inside agent workflows via the companion MCP server (coming v0.2).

Pricing

$1.49 per 1,000 results. No subscription. First 100 results free for testing.

Compliance

• Public data only — search results page, no login, no PII collected.
• Respects rate-limit conventions — randomized 200-800ms delays between pages.
• Apify Residential Proxy BR — used in production runs (default in input_schema). Required when running from datacenter IPs, which Mercado Livre blocks.
• User-Agent: realistic browser identification. The robots.txt at lista.mercadolivre.com.br permits crawler access to /lista/* (the endpoint this actor uses) for User-agent: *. The actor does not impersonate or identify as a known bot crawler — following standard practice for commercial data services.

Known limits

• Hard cap ~2,000 items per query imposed by Mercado Livre itself (40 pages × 50 items). If you request maxItems: 5000, the actor collects everything available and finishes with status SUCCEEDED — never silently truncates.
• badges populated via aria-label substring match. SERP badges are sparse (~5-10% of cards in our calibration); expect mostly []. Roadmap v0.2 will enrich via product page inspection.
• seller_location, seller_rating, categories require PDP follow-up — not in v0.1 scope. The fields stay in the JSON contract (always null / []) and become populated in v0.2.
• Sponsored cards return tracking URLs (click1.mercadolivre.com.br/...) instead of canonical product URLs. Affects ~12% of items in the smoke calibration. Roadmap v0.2 will follow redirects to recover canonical URL.

Support

Response within 24h via Apify issues.

Changelog

• 2026-05-24 v0.1 — Initial release.

---

🇧🇷 Português

O que faz

Extrai dados estruturados de produtos do Mercado Livre Brasil — resultados de busca em JSON, sem API key, residential proxy incluso. Retorna até ~2.000 produtos por palavra-chave em minutos.

✓ Validado em 2026-05-24: 25/25 produtos extraídos e validados contra SERP real em 7s (teste integração).

Exemplo rápido

Entrada:

{ "query": "notebook gamer", "maxItems": 50 }

Saída (primeiro resultado): mesmo JSON acima.

Campos de saída

Campo	Tipo	Notas
title	string	Nome do produto.
price	número|null	Preço atual em BRL.
original_price	número|null	Preço antes do desconto (riscado).
discount	int|null	Desconto em % (ex. 15).
currency	string	Sempre "BRL".
product_url	string	URL canônica, sem parâmetros de tracking.
image_url	string|null	Imagem principal.
seller_name	string|null	Nome da loja quando exibido no card.
seller_location	null	Sempre null na v0.1 — ver Limites conhecidos.
seller_rating	null	Sempre null na v0.1 — ver Limites conhecidos.
rating	float|null	0.0–5.0 estrelas.
reviews_count	int|null	Número de avaliações.
installments	string|null	Texto bruto do parcelamento como exibido pelo ML. Formato varia entre cards (ex: "em 10x R$ 491,50", "ou R$ 5.174 em 10x R$ 517,47 sem juros"). Parse no cliente se necessário.
categories	string[]	Sempre [] na v0.1.
badges	string[]	Tokens normalizados de {FULL, MAIS VENDIDO, OFERTA DO DIA, RECOMENDADO, FRETE GRÁTIS}.
sponsored	bool	true para slots patrocinados.
shipping_free	bool	true quando "Frete grátis" aparece.
shipping_cost	número|null	Sempre null na v0.1 (raro na SERP).
scraped_at	string	Timestamp ISO 8601 UTC.

Casos de uso

• Monitoramento de preços (sellers de e-commerce): acompanhe preços de concorrentes diariamente; exporte pra BigQuery ou Sheets.
• Inteligência de mercado (marcas): detecte violação de preço mínimo (MAP) e revendedores não autorizados; alerta de queda > X%.
• Agentes IA (Claude / Cursor): consulte preços BR em tempo real dentro do workflow do agente, via o MCP server companion (v0.2).

Preços

$1.49 por 1.000 resultados. Sem assinatura. Primeiros 100 resultados grátis pra teste.

Conformidade

• Apenas dados públicos — página de resultados, sem login, sem PII.
• Respeita convenções de rate-limit — delays randomizados 200-800ms entre páginas.
• Apify Residential Proxy BR — usado em runs de produção (default no input_schema). Obrigatório quando rodando a partir de IPs de datacenter, que o Mercado Livre bloqueia.
• User-Agent: identificação realista de browser. O robots.txt em lista.mercadolivre.com.br permite acesso de crawlers a /lista/* (endpoint usado por este actor) para User-agent: *. O actor não se passa por nem se identifica como bot crawler conhecido — prática padrão para serviços comerciais de dados.

Limites conhecidos

• Hard cap de ~2.000 itens por query imposto pelo próprio Mercado Livre (40 páginas × 50 itens). Se você pedir maxItems: 5000, o actor coleta todo o disponível e encerra com status SUCCEEDED — nunca trunca em silêncio.
• badges preenchidos via heurística de substring em aria-label. Os badges aparecem em poucos cards na SERP (~5-10% na nossa calibração); espere [] na maioria. Roadmap v0.2 vai enriquecer via inspeção do PDP.
• seller_location, seller_rating, categories exigem visita à página do produto — não estão no escopo da v0.1. Os campos ficam no contrato JSON (sempre null / []) e ganham conteúdo na v0.2.
• Cards sponsored retornam URLs de tracking (click1.mercadolivre.com.br/...) em vez de URLs canônicas do produto. Afeta ~12% dos itens na calibração do smoke. Roadmap v0.2 vai seguir os redirects pra recuperar a URL canônica.

Suporte

Resposta em até 24h via issues do Apify.

Histórico

• 2026-05-24 v0.1 — Lançamento inicial.