--- title: "Mercado Libre API: Category Prices and Reviews as JSON" description: "Pull Mercado Libre best sellers and offers by category as JSON: price, previous price, shipping and reviews, at 1 credit per call." url: https://perceptlayer.com/blog/mercado-libre-api-product-search --- [Blog](https://perceptlayer.com/blog) / [API guides](https://perceptlayer.com/blog/category/api-guides) # Mercado Libre API: Category Prices and Reviews as JSON 17 Aug 2026 Perceptlayer 7 min read The [Mercado Libre API](https://perceptlayer.com/apis/mercadolibre) returns product data for Latin American marketplaces as JSON, with one key and no scraper. Call `/v1/mercadolibre/category-products` with a `site` and a `category_id` and you get the category's best sellers and offers, each with price, previous price, currency, discount label and shipping text. Every call costs 1 credit. ## Key takeaways - `GET /v1/mercadolibre/category-products` takes `site` and `category_id` and returns products with `price`, `previous_price`, `currency` and `discount_label`. - There's no free-text product search endpoint in the list. Use `category-discovery` to turn a query into a category, then pull that category. - `reviews` and `review-summary` take a `site` and an `id`, and `id_type` switches between `item` and `product`. - Tracking one category daily for 30 days costs 30 credits. Adding weekly review summaries for 33 products brings it to 162 credits, inside the 1,000 free credits a month. - Failed calls cost nothing and return `X-Credits-Used: 0`. ## Which Mercado Libre endpoints return product data? Eleven endpoints cover the marketplace, and each costs 1 credit per successful call. Four of them matter for price and review tracking: `categories` for category data, `category-products` for the products in a category, `reviews` for individual reviews and `review-summary` for the rating overview. The rest cover discovery, shipping, stores and suggestions. | Endpoint | Returns | Required parameters | | --- | --- | --- | | `/v1/mercadolibre/categories` | Categories | none | | `/v1/mercadolibre/category-discovery` | Category Discovery | `site`, `q` | | `/v1/mercadolibre/category-products` | Category Products | `site`, `category_id` | | `/v1/mercadolibre/reviews` | Reviews | `site`, `id` | | `/v1/mercadolibre/review-summary` | Review Summary | `site`, `id` | | `/v1/mercadolibre/shipping-options` | Shipping Options | `item_id`, `zip_code` | Related Products, Suggestions, Category Attributes, Store and Stores round out the set. All of them sit on the [Mercado Libre API page](https://perceptlayer.com/apis/mercadolibre), part of the [Marketplaces APIs](https://perceptlayer.com/verticals/marketplaces). ## How do you get a key and make the first call? Sign up, verify an email address and you get 1,000 free credits every month, with no credit card. Send the key in the `X-API-Key` header. Keys start with `sk_live_`. The [authentication docs](https://docs.perceptlayer.com/authentication) cover the `api_key` query parameter for places where headers aren't possible, and the [quick start](https://docs.perceptlayer.com/quickstart) walks through a first call. [Get a free API key](https://perceptlayer.com/signup), then call `categories` for a category: ```bash curl "https://api.perceptlayer.com/v1/mercadolibre/categories?site=MLA&category_id=MLA1574" \ -H "X-API-Key: $API_KEY" ``` `site` and `category_id` are both optional on this endpoint. The `site` values are MLA, MLB, MLM, MLC, MCO, MPE, MLU, MEC and MLV, one per country marketplace. The recorded sample below is MLA, which resolves to `mercadolibre.com.ar` and prices in `ARS`. ## How do you find the category you want to track? Start from a keyword and let `category-discovery` map it to categories, because the API has no free-text item search. It takes `site` and `q` (up to 200 characters) and an optional `limit`. It returns matching categories (the [Category Discovery page](https://perceptlayer.com/apis/mercadolibre/category-discovery) lists the fields); pass a category's ID to `category-products`. `suggestions` takes `site`, `q` (up to 100 characters) and `limit`. ```bash curl "https://api.perceptlayer.com/v1/mercadolibre/category-discovery?site=MLA&q=camara%20de%20seguridad&limit=5" \ -H "X-API-Key: $API_KEY" ``` Do this once per category and store the IDs. Category discovery is a setup step, not part of the tracking loop, so it costs you a handful of credits in total rather than per run. If you need the fields a category's items must carry, [Category Attributes](https://perceptlayer.com/apis/mercadolibre/category-attributes) takes only a `category_id`. ## Which parameters does Category Products take? `category-products` takes two required parameters and nothing else. The [Category Products](https://perceptlayer.com/apis/mercadolibre/category-products) page has the playground if you'd rather try it in the browser first. | Parameter | Type | Required | Notes | | --- | --- | --- | --- | | `site` | string | yes | One of MLA, MLB, MLM, MLC, MCO, MPE, MLU, MEC, MLV | | `category_id` | string | yes | For example `MLA1574` | Here's the call behind the recorded response: ```bash curl "https://api.perceptlayer.com/v1/mercadolibre/category-products?site=MLA&category_id=MLA1574" \ -H "X-API-Key: $API_KEY" ``` There's no `limit` or `offset` on this endpoint, so one call returns whatever the category's lists hold at that moment. ## What does a price record look like? Each product carries the current `price`, the `previous_price`, the `currency` and a `discount_label`, plus shipping text and a `fulfilled_by_mercado_libre` flag. That's enough to build a price history without opening a single product page. This is an excerpt of the recorded response for category `MLA1574` on `MLA`: ```json { "success": true, "data": { "site": "MLA", "category_id": "MLA1574", "products": [ { "position": 2, "tab": "affiliate-profile-best-sellers", "item_id": "MLA1550818153", "product_id": "MLA43779215", "title": "Camara Seguridad Geotek 3mp Ip Wifi Exterior Full Hd Domo Vision Nocturna …", "brand": "GEOTEK", "official_store": true, "highlight": "MÁS VENDIDO", "price": 46567, "previous_price": 74999, "currency": "ARS", "discount_label": "37% OFF", "shipping_text": "Envío gratis", "shipping_note": "por ser tu primera compra", "fulfilled_by_mercado_libre": true } ], "total": 33, "source_tabs": [ { "id": "affiliate-profile-best-sellers", "title": "Más vendidos", "count": 18 }, { "id": "affiliate-profile-offers", "title": "Ofertas", "count": 15 } ] }, "meta": { "endpoint_family": "category_products", "billable": true, "duration_ms": 764 } } ``` Three things worth knowing. `tab` says which list a product came from, and `source_tabs` counts them: 18 best sellers and 15 offers make the `total` of 33. `item_id` identifies the listing, while `product_id` is only present on some products, so don't treat it as always there. And `previous_price` is a single value per product, not a series. Your own stored snapshots are the history. ## How do you turn this into a price tracker? Call the endpoint on a schedule, key each product by `item_id`, and store `price`, `previous_price` and `currency` with a timestamp. Compare today's price to the last stored one, not to `previous_price`. The script below does the first half: it pulls the category and prints the products whose listed discount is deepest. ```python import os import requests BASE = "https://api.perceptlayer.com" HEADERS = {"X-API-Key": os.environ["API_KEY"]} resp = requests.get( f"{BASE}/v1/mercadolibre/category-products", headers=HEADERS, params={"site": "MLA", "category_id": "MLA1574"}, timeout=30, ) resp.raise_for_status() print("credits used:", resp.headers.get("X-Credits-Used")) rows = [] for p in resp.json()["data"]["products"]: old, new = p.get("previous_price"), p.get("price") if old and new: rows.append((round(100 * (old - new) / old), p["item_id"], new, p["currency"])) for pct, item_id, price, currency in sorted(rows, reverse=True)[:10]: print(f"{pct}% off {item_id} {price} {currency}") ``` Writing each run to a database table keyed by `item_id` and date gives you the history. Handle failures as covered in [Docs: Errors](https://docs.perceptlayer.com/errors): a 429 or 503 carries a `Retry-After` header. ## How do you pull reviews and rating summaries? Use `review-summary` for the overview and `reviews` for the individual entries, both keyed by `site` and `id`. Set `id_type` to `item` or `product` to say what the `id` is. `reviews` also accepts `limit`, `offset`, `rating` (an integer filter) and `order` ( `relevance` or `date`). We don't have a recorded response for these two, so check the [Review Summary](https://perceptlayer.com/apis/mercadolibre/review-summary) and [Reviews](https://perceptlayer.com/apis/mercadolibre/reviews) pages for the returned fields. ```bash curl "https://api.perceptlayer.com/v1/mercadolibre/review-summary?site=MLA&id=MLA43779215&id_type=product" \ -H "X-API-Key: $API_KEY" curl "https://api.perceptlayer.com/v1/mercadolibre/reviews?site=MLA&id=MLA43779215&id_type=product&order=date&limit=20" \ -H "X-API-Key: $API_KEY" ``` The `product_id` from the category response is the natural `id` here, with `id_type=product`. Where a product has no `product_id`, use its `item_id` with `id_type=item`. A sensible pattern is to poll `review-summary` for every tracked product and fetch `reviews` only when the summary changes. ## What does tracking one category cost? Tracking one category daily costs 30 credits a month, and adding review summaries for its 33 products once a week brings it to 162. All of these endpoints cost 1 credit per successful call, so the arithmetic is a count of calls. The [credits docs](https://docs.perceptlayer.com/credits) explain how debits work. | Task | Calls | Credits | | --- | --- | --- | | `category-products`, once a day for 30 days | 30 | 30 | | `review-summary`, 33 products × 4 weekly runs | 132 | 132 | | Total for one category | 162 | 162 | That fits comfortably inside the 1,000 free credits a month. Scale it out: 10 categories pulled 4 times a day for 30 days is 10 × 4 × 30 = 1,200 calls × 1 credit = 1,200 credits for the price pulls alone, which is past the free tier. Paid credits come in prepaid packs starting at 10,000 credits, last 12 months, and have no subscription. [Pricing](https://perceptlayer.com/pricing) has what credits cost. Failed calls return `X-Credits-Used: 0`, and the [rate limits](https://docs.perceptlayer.com/rate-limits) are per account. ## When is the official API a better fit? If you sell on the marketplace and need to create listings or manage orders, use Mercado Libre's own [developer platform](https://developers.mercadolibre.com.ar/en_us/register-your-application). You register an application, and calls on behalf of a seller authenticate through [OAuth 2.0 access tokens](https://developers.mercadolibre.com.ar/en_us/identity-and-access-management-oauth-and-tokens), so it's built around a seller's own account: listings, orders and similar seller data. That's the right fit for running a store, but it means registering an app and running the token flow before you read anything. This API is the other trade-off. It only reads public market data and never touches a seller account, so it can't create or change anything. For read-only data across a category, such as best sellers, offers, prices and reviews, with one key and a `site` parameter that switches between the nine country sites, it's the shorter path. Browse the storefront itself, for example [mercadolibre.com.ar](https://www.mercadolibre.com.ar/), to check any value against what a shopper sees. Data is collected from publicly available sources and returned as found at the time of the call, so a price you pull is the price shown then. For the same workflow on other stores see the [Walmart product search API](https://perceptlayer.com/blog/walmart-product-search-api) and the [Google Shopping API](https://perceptlayer.com/blog/google-shopping-api-product-prices). Your next step: open the [Mercado Libre API page](https://perceptlayer.com/apis/mercadolibre), pick `category-products`, enter `MLA` and `MLA1574` in the playground and run the call with your key. ## APIs in this post - [Mercado Libre **1 credit per call** · 11 endpoints](https://perceptlayer.com/apis/mercadolibre) ## Frequently asked questions ### Is there a Mercado Libre product search endpoint? Not for free-text queries. `category-discovery` takes a `site` and a `q` and returns matching categories, and `category-products` then returns the best sellers and offers in a category. `suggestions` takes a `site`, a `q` and an optional `limit`; its response is on the [Mercado Libre API page](https://perceptlayer.com/apis/mercadolibre). Together they cover finding a category and reading its products. ### How much does it cost to monitor Mercado Libre prices? Each call costs 1 credit, whether it's `category-products`, `reviews` or `review-summary`. One category pulled daily for 30 days is 30 calls × 1 credit = 30 credits. Free accounts get 1,000 credits a month, and [pricing](https://perceptlayer.com/pricing) lists what larger packs cost. ### Which Mercado Libre countries can I query? Nine site codes are accepted: MLA, MLB, MLM, MLC, MCO, MPE, MLU, MEC and MLV. Pass one as `site` on most endpoints. Every product carries a `currency` field ( `ARS` for MLA in the recorded sample), so read it from each row and don't compare prices across sites until the currencies match. ### What happens when a call fails? You get an HTTP status and a JSON body with `error.code`, `error.message` and `error.request_id`. Failed calls aren't billed and return `X-Credits-Used: 0`. A 429 or 503 includes `Retry-After` with the seconds to wait. See [Docs: Errors](https://docs.perceptlayer.com/errors) for every code. ### Can an AI agent call these endpoints? Yes. The MCP server at `https://api.perceptlayer.com/mcp` exposes `search_endpoints`, `get_endpoint` and `call_endpoint`. Lookups cost nothing, and `call_endpoint` spends credits on success only. The [AI agents docs](https://docs.perceptlayer.com/ai-agents) show how to add it to Claude Code. mercado libre ecommerce price tracking latin america reviews ## More from the blog 1. [API guides](https://perceptlayer.com/blog/category/api-guides) 2 Oct 2026 Perceptlayer 6 min read ## [AliExpress Product API: Search, Reviews and Shipping](https://perceptlayer.com/blog/aliexpress-api-product-search-reviews) Chain AliExpress search, product, product-reviews and product-shipping, with every required parameter, at 1 credit per call, and cost a 100-product review pull. 2. [API guides](https://perceptlayer.com/blog/category/api-guides) 22 Oct 2026 Perceptlayer 9 min read ## [Idealo API: Compare Product Prices Across Shops as JSON](https://perceptlayer.com/blog/idealo-api-price-comparison-json) Search idealo.de by keyword, then pass a product\_id to the offers endpoint. Endpoints, parameters, a real search response and the cost at 1 credit per call. 3. [API guides](https://perceptlayer.com/blog/category/api-guides) 31 Aug 2026 Perceptlayer 8 min read ## [App Store Reviews API: Apple App Store Data as JSON](https://perceptlayer.com/blog/app-store-reviews-api) Call GET /v1/apple-app-store/product-reviews with an app's product\_id to get ratings, titles and review text as JSON. Parameters, a real response, 1 credit.