lista.mercadolivre.com.br 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.
curl -X GET 'https://api.parse.bot/scraper/3805251d-c51a-458d-ad8f-cb8b5a906b4f/search_listings?query=smartwatch&category_id=MLB3937' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for product listings on the Mercado Livre Brazil 'Ofertas' page. Without a category_id, returns all current deals. The query parameter filters results locally by name within the fetched listings, so it works best combined with a category_id to narrow the pool.
| 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). 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": "MLB4328800327",
"URL": "https://produto.mercadolivre.com.br/MLB-4328800327-smartwatch-bettdow-fb055-185-esportivo-ia-musica-gps-3atm-_JM",
"Name": "Smartwatch Bettdow Fb055 1.85 Esportivo Ia Música Gps 3atm",
"Price": 360.05,
"Discount": 63,
"Store_Name": "N/A",
"Original_Price": 999,
"Promotion_Status": "MAIS VENDIDO"
}
],
"total_count": 25,
"average_price": 527.68
},
"status": "success"
}
}About the lista.mercadolivre.com.br 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.
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.
- 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 | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.