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'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace lista-mercadolivre-com-br-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: MercadoLivre SDK — browse deals, filter by category, find cheapest."""
from parse_apis.Mercado_Livre_Brazil__Offers__API import MercadoLivre, Listing, NotFoundError
client = MercadoLivre()
# Search for deals in the jewelry & watches category (MLB3937)
for listing in client.listings.search(query="relogio", category_id="MLB3937", limit=5):
print(listing.name, listing.price, listing.original_price, listing.store_name)
# Find the lowest-priced watch deal in the jewelry category
cheapest = client.listings.lowest_price(query="relogio")
if cheapest:
print(cheapest.name, cheapest.price, cheapest.url)
# List all current active deals on the Ofertas page
for deal in client.listings.list_recent(limit=3):
print(deal.id, deal.name, deal.price, deal.promotion_status)
# Error handling: catch NotFoundError for invalid operations
try:
result = client.listings.lowest_price(query="xyznonexistent999")
if result:
print(result.name, result.price)
else:
print("No matching items found")
except NotFoundError as exc:
print(f"Resource not found: {exc}")
print("exercised: listings.search / listings.lowest_price / listings.list_recent")
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 | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 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.