Mercado Livre APIlista.mercadolivre.com.br ↗
Access Mercado Livre Brazil Ofertas deals data: prices, discounts, promotion status, and sold units across all categories via 4 structured endpoints.
What is the Mercado Livre API?
This API exposes 4 endpoints covering Mercado Livre Brazil's Ofertas (Deals) page, returning product deal objects with fields including Price, Original_Price, Discount, Store_Name, and Promotion_Status. The search_listings endpoint accepts a category_id and optional keyword query to filter active deals within a given category, while get_listing_details fetches sold-unit counts for individual items by ID or URL.
curl -X GET 'https://api.parse.bot/scraper/3805251d-c51a-458d-ad8f-cb8b5a906b4f/search_listings?query=relogio&category_id=MLB3937' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for product listings on the Mercado Livre Brazil 'Ofertas' (deals) page. Without a category_id, returns all current deals. The query parameter filters results locally by name within the fetched listings. Returns matching listings with pricing, discount, and store information, plus aggregate statistics (total count, average price). Single-page response containing all matching deals in the selected category.
| Param | Type | Description |
|---|---|---|
| query | string | Keyword to filter results by product name (case-insensitive local filter applied after fetching the category page). Works best when combined with category_id. |
| category_id | string | Mercado Livre category ID to filter deals (e.g. MLB3937 for Joias e Relógios, MLB1648 for Informática). When omitted, returns all deals from the main Ofertas page. |
{
"type": "object",
"fields": {
"listings": "array of product deal objects with id, Name, Price, Original_Price, Discount, Store_Name, Promotion_Status, and URL",
"total_count": "integer total number of matching listings",
"average_price": "number average price of matching listings"
},
"sample": {
"data": {
"listings": [
{
"id": "MLB3683540706",
"URL": "https://www.mercadolivre.com.br/relogio-orient-masculino-analogico-prateado-mbss1155a-d2sx/p/MLB17913852",
"Name": "Relogio Orient Masculino Analogico Prateado Mbss1155a D2sx Azul-escuro",
"Price": 299,
"Discount": null,
"Store_Name": "Relojoaria Wenus {icon_cockade}",
"Original_Price": 457.39,
"Promotion_Status": "MAIS VENDIDO"
}
],
"total_count": 2,
"average_price": 186.24
},
"status": "success"
}
}About the Mercado Livre API
What the API Returns
All four endpoints draw from Mercado Livre Brazil's active Ofertas (Deals) page. The core response object across endpoints shares a consistent shape: id, Name, Price, Original_Price, Discount, Store_Name, Promotion_Status, and URL. The search_listings endpoint also returns total_count and average_price for the matched result set, making it useful for quick category-level price summaries.
Filtering and Scope
search_listings accepts two optional parameters: category_id (e.g. MLB3937 for Joias e Relógios) and query. The query parameter applies a case-insensitive local filter against product names within the fetched category results — it does not hit a search index independently. For best results, pair query with a category_id to narrow the pool before filtering. Without category_id, the endpoint returns all current deals across categories.
Single-Item and Lowest-Price Lookups
get_listing_details takes an item_id (either a raw Mercado Livre item ID or a full item URL) and returns Price, Sales (units sold), Promotion_Status, Name, and URL for that specific listing. get_lowest_price_item scans the Ofertas page within a category for the cheapest item matching a keyword, returning the full deal object or null if no match is found.
Freshness and Coverage
get_recent_listings returns all currently active deals and accepts a days parameter for interface compatibility, but that parameter does not filter results — every item returned is an active promotion at the time of the request. Coverage is limited to items appearing on the Ofertas page; standard non-deal listings and search-result pages outside the Ofertas section are not included.
The Mercado Livre API is a managed, monitored endpoint for lista.mercadolivre.com.br — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when lista.mercadolivre.com.br changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official lista.mercadolivre.com.br API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track discount depth over time using Discount and Original_Price fields across electronics categories
- Identify which Ofertas products have the highest Sales counts to gauge deal popularity
- Build a price-drop alert by comparing current Price values from search_listings against a stored baseline
- Find the cheapest active deal in a specific category using get_lowest_price_item with a keyword filter
- Aggregate average_price from search_listings across multiple category_ids for competitive benchmarking
- Monitor Promotion_Status changes on specific item IDs using get_listing_details
- Audit which Store_Name sellers appear most frequently in active Ofertas deals
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 200 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
| Team | $300/mo | 20,000 | 300 req/min |
| Company | $1,000/mo | 100,000 | 500 req/min |
Each endpoint has a fixed posted price per successful call — most fall between 1 and 10 credits — shown on this API's page before you run it. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.