# Mercado Libre Catalogue by Category (`ikmal_suzali_atr/mercadolibre-catalog`) Actor

Every product on a Mercado Libre category listing (Brazil (mercadolivre.com.br), Mexico (mercadolibre.com.mx), Argentina (mercadolibre.com.ar), Chile (mercadolibre.cl), Colombia (mercadolibre.com.co)): id, name, brand, price, original price, rating, seller and sponsored flag, page by page,…

- **URL**: https://apify.com/ikmal_suzali_atr/mercadolibre-catalog.md
- **Developed by:** [AtTheRate AI](https://apify.com/ikmal_suzali_atr) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Mercado Libre Catalogue by Category

Pulls every product on a Mercado Libre category listing across five Latin American storefronts (Brazil, Mexico, Argentina, Chile and Colombia), one row per product with price, seller, shipping label, sales volume text and a sponsored flag. Built for brands and marketplace sellers who need the whole shelf of a category in its real order.

### Login: optional

No account is needed. Mercado Libre walls the plain-HTTP replay of a session with its account-verification page (`/gz/account-verification`), so the actor reads listings through a real browser on a residential exit in the market's country, which the site serves anonymously.

If Mercado Libre walls the browser too (it can tighten this at any time), you can run as your own logged-in session: log in at https://www.mercadolivre.com.br (or your market's site), export the cookies with **Cookie-Editor** or **EditThisCookie** (**Export → JSON**, or paste the raw `Cookie:` header `name1=value1; name2=value2`) into the optional `sessionCookies` input, and keep the proxy in the account's country (BR, MX, AR, CL or CO). With cookies set the actor holds one sticky exit for the whole run. The field is stored encrypted by Apify, values are never logged (only the count and cookie names), and only cookies for the market's own domain (e.g. `mercadolivre.com.br` for `br`) are used.

If the wall still appears, the run stops with one of two messages: *"… requires a logged-in session … Supply sessionCookies …"* (no cookies were given) or *"… supplied session is logged out / expired — re-export cookies …"* (cookies were attached but the site still walled them; log in again and export a fresh set). Use an account you own and respect Mercado Libre's terms of use.

### What you get

- Complete coverage page by page, with `category`, `page` and `position` on every row.
- Seller-level visibility: `seller` is the store behind the listing, which makes a category a competitive map.
- Price with the discount split out: `price`, `original_price` when reduced, and `currency` per market.
- `is_sponsored` per row, from the "Patrocinado" advertising component on the card.
- Demand straight from the listing: `sold_text` is the site's sales count text and `shipping` the delivery promise.
- Both identifiers the site uses, `catalog_id` and `item_id`, plus `labels` for card badges and `parent_category` when subcategories are on.

### Input

Give it listing category paths or full listing URLs plus a market.

```json
{
  "categories": ["/beleza-cuidado-pessoal/cuidados-com-cabelo-shampoo/"],
  "locale": "br",
  "maxPages": 1,
  "expandSubcategories": true,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "BR"
  },
  "delayMs": 1200,
  "callsPerSession": 60
}
```

- `categories` (required): listing paths such as `/beleza-cuidado-pessoal/cuidados-com-cabelo-shampoo/` or URLs such as `https://lista.mercadolivre.com.br/celulares-telefones/`.
- `locale`: `br`, `mx`, `ar`, `cl` or `co`. Default `br`.
- `maxPages`: pages per category. `0` means every page. Listings are paged at 48 products.
- `expandSubcategories`: also crawl the children from the department menu.
- `sessionCookies` (optional, secret): your logged-in Mercado Libre cookies, as a Cookie-Editor / EditThisCookie JSON export or a raw `Cookie` header. Only needed if the site walls anonymous browsing; see *Login: optional*.
- `proxyConfiguration`: residential inside the market's own country. Required. The default is BR. Use the country the account belongs to.

### Output

One dataset row per product, in listing order.

```json
{
  "platform": "mercadolibre",
  "locale": "br",
  "category": "/beleza-cuidado-pessoal/cuidados-com-cabelo-shampoo/",
  "page": 1,
  "position": 1,
  "id": "MLB1234567890",
  "catalog_id": "MLB1234567890",
  "item_id": "MLB9876543210",
  "name": "Shampoo Anticaspa 400ml",
  "price": 39.9,
  "original_price": 59.9,
  "currency": "BRL",
  "rating": 4.7,
  "in_stock": true,
  "is_sponsored": true,
  "seller": "Loja Exemplo",
  "sold_text": "+1 mil",
  "shipping": "Frete grátis",
  "labels": ["MAIS VENDIDO"],
  "product_url": "https://www.mercadolivre.com.br/p/MLB1234567890",
  "fetched_at": "2026-09-12T03:00:00.000Z"
}
```

Values above are illustrative: they follow the shape of an anonymous Brazilian residential test run. Field names are exactly what the actor writes. `brand` is null on most rows because the cards rarely publish one, and `rating_count` is always null because the card shows only an average.

### Use cases

- Seller mapping: group `seller` by `position` to see which stores control the top of a shelf.
- Price and discount tracking per market from `price`, `original_price` and `currency`.
- Demand ranking from `sold_text`, to separate listings that rank well from listings that sell.
- Ad share from `is_sponsored` paired with `position` and `seller`.
- Free-shipping penetration from `shipping`, a major ranking factor here.

### Notes and limits

- A residential proxy inside the market's country is required. Listings are read in a browser because the site walls plain HTTP; if it walls the browser as well, the run stops with a message naming the wall, never an empty result, and `sessionCookies` from your own logged-in browser is the way past it.
- Listing pages hold 48 organic products plus sponsored cards, so `maxPages: 10` is about 480+ per category; Mercado Libre stops paging at 42 pages (2,000 results). For anonymous visitors Mercado Libre renders bare category paths (e.g. `/beleza-cuidado-pessoal/`, `/celulares-telefones/celulares-smartphones/`) as landing pages with a few carousel cards; the actor reports those as `non_listing_pages` instead of emitting carousel rows. Use a listing URL as the site shows it after you narrow a category, e.g. `/beleza-cuidado-pessoal/cuidados-com-cabelo-shampoo` or `/celulares-telefones/celulares-smartphones/novo/`.
- Only listing paths are accepted. A path that is not a `lista` or `listado` path is counted in `failed_categories`.
- Currency follows the market and prices are normalised to numbers: BRL, MXN, ARS, CLP, COP.

### FAQ

**Do I need a proxy?** Yes, residential inside the market's country: BR, MX, AR, CL or CO. The input defaults to BR. Without it the site serves a login wall. If you supply `sessionCookies`, use the account's country.

**How many results can I get?** `maxPages: 0` walks the category at 48 products per page.

**Does it need a login or an API key?** No. It works anonymously through the browser. `sessionCookies` is an optional fallback for when Mercado Libre walls anonymous traffic.

**What happens if the category is blocked?** The run fails loudly with the blocked URL and the country the proxy should be in, so a block is never mistaken for an empty category.

# Actor input Schema

## `categories` (type: `array`):

Mercado Libre listing category paths or lista.*/listado.* URLs, e.g. "/beleza-cuidado-pessoal/cuidados-com-cabelo-shampoo/" or "https://lista.mercadolivre.com.br/celulares-telefones/acessorios-celulares/". Enable "Include subcategories" to crawl children from the site's department menu. Bare category roots are landing pages for anonymous visitors (reported as non-listing); use a listing URL such as /celulares-telefones/celulares-smartphones/novo/.

## `locale` (type: `string`):

Which storefront / locale.

## `maxPages` (type: `integer`):

0 = all pages.

## `expandSubcategories` (type: `boolean`):

Also crawl each category's subcategories when the site exposes them.

## `delayMs` (type: `integer`):

Pause between page fetches.

## `callsPerSession` (type: `integer`):

Re-mint the session after this many page fetches.

## `sessionCookies` (type: `string`):

Optional. The actor works anonymously through a browser on a residential exit in the market's country. Only if Mercado Libre walls you, paste the cookies of YOUR OWN logged-in Mercado Libre browser session: a JSON export from Cookie-Editor / EditThisCookie ("Export as JSON": an array of {name, value, domain, path, expires, httpOnly, secure, sameSite}) or a raw Cookie header ("name1=value1; name2=value2"). Only cookies for the market's own domain (e.g. mercadolivre.com.br) are used. Stored encrypted; values are never logged.

## `proxyConfiguration` (type: `object`):

On the Apify platform this decides egress. A residential proxy in the storefront's country is required (BR for the default); with sessionCookies, use the account's country — the actor then keeps one sticky exit for the whole run. On our own servers it is ignored and our residential proxy is used.

## Actor input object example

```json
{
  "categories": [
    "/beleza-cuidado-pessoal/cuidados-com-cabelo-shampoo/"
  ],
  "locale": "br",
  "maxPages": 2,
  "expandSubcategories": false,
  "delayMs": 1200,
  "callsPerSession": 60,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "BR"
  }
}
```

# Actor output Schema

## `results` (type: `string`):

One row per product.

## `summary` (type: `string`):

Counts for the run: what was requested, captured, skipped and failed.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "categories": [
        "/beleza-cuidado-pessoal/cuidados-com-cabelo-shampoo/"
    ],
    "maxPages": 2
};

// Run the Actor and wait for it to finish
const run = await client.actor("ikmal_suzali_atr/mercadolibre-catalog").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "categories": ["/beleza-cuidado-pessoal/cuidados-com-cabelo-shampoo/"],
    "maxPages": 2,
}

# Run the Actor and wait for it to finish
run = client.actor("ikmal_suzali_atr/mercadolibre-catalog").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "categories": [
    "/beleza-cuidado-pessoal/cuidados-com-cabelo-shampoo/"
  ],
  "maxPages": 2
}' |
apify call ikmal_suzali_atr/mercadolibre-catalog --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,ikmal_suzali_atr/mercadolibre-catalog"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/OAxcvahF93VmhJQDk/builds/r17Lw3WHrcf8N3NhY/openapi.json