# MercadoLibre Reviews Scraper (`axlymxp/mercadolibre-reviews-scraper`) Actor

Scrape MercadoLibre & MercadoLivre product reviews plus the rating summary — average score, 5-to-1 star distribution, photo/video counts, and MercadoLibre's own AI review summary. 18 countries, no proxy needed. Pay only for the results you get.

- **URL**: https://apify.com/axlymxp/mercadolibre-reviews-scraper.md
- **Developed by:** [axly](https://apify.com/axlymxp) (community)
- **Categories:** E-commerce, Business
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 1,000 dataset items

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

## MercadoLibre Reviews Scraper

Scrape **product reviews and rating summaries** from **MercadoLibre** and
**MercadoLivre** across 18 Latin-American countries. For every catalog product you
get the full review list **plus** the rating summary MercadoLibre computes itself:
average score, the 5→1 **star distribution**, photo/video counts, and an
**AI-generated review summary**.

Unlike other review scrapers, this one returns the **AI summary** and **star
distribution** — not just raw review text. And it runs against an open endpoint, so
**no proxy is required**.

### Who it's for

- **Brands & product researchers** — read one AI summary and a star breakdown
  instead of 800 individual reviews.
- **Sellers** — track review velocity, complaints and photo evidence on your own
  and competitors' catalog products.
- **Analysts & ML teams** — assemble clean, labelled review datasets (rating, date,
  media, country) for sentiment analysis.

### Output

The dataset contains two row types, distinguished by `record_type`.

#### `summary` — one row per product

| Field | Type | Description |
| ----- | ---- | ----------- |
| `product_id` | string | Catalog product id |
| `rating` | number | Average score (0–5) |
| `total_ratings` | number | Total number of ratings |
| `total_comments` | string | Comment count label |
| `stars_5` … `stars_1` | number | Count of ratings at each star level |
| `pictures` | number | Review photos across the product |
| `videos` | number | Review videos across the product |
| `ai_summary` | string | MercadoLibre's AI-written review digest |
| `site` | string | Country site id |
| `scraped_at` | string | ISO-8601 timestamp |

#### `review` — one row per review

| Field | Type | Description |
| ----- | ---- | ----------- |
| `review_id` | number | Review id |
| `rating` | number | Star rating (1–5) |
| `text` | string | Review body |
| `date_relative` | string | Relative date (e.g. `Hace 9 meses`) |
| `created_date` | string | Absolute ISO-8601 date |
| `country` | string | Reviewer country |
| `variant` | string | Purchased variant, when shown |
| `likes` | number | Helpful-vote count |
| `picture_count` / `video_count` | number | Media attached to the review |
| `picture_urls` | array | Review photo URLs |
| `site` | string | Country site id |
| `scraped_at` | string | ISO-8601 timestamp |

### Use cases

- **Sentiment at a glance** — pull the `summary` rows for a catalogue and rank
  products by rating and 1-star share.
- **Complaint mining** — filter `review` rows to `rating <= 2` and cluster the text.
- **Photo evidence** — collect `picture_urls` from high-rated reviews for listings
  or ads.
- **Competitor monitoring** — schedule daily and watch `total_ratings` and the
  distribution move.

### Input parameters

| Field | Type | Default | Description |
| ----- | ---- | ------- | ----------- |
| `productIds` | array | `["MLA57692573"]` | Catalog product ids or `/p/` URLs |
| `site` | enum | `MLA` | Default country site for plain ids |
| `maxReviewsPerProduct` | integer | `100` | Per-product review cap |
| `includeSummary` | boolean | `true` | Emit a summary row per product |
| `maxItems` | integer | `100000` | Global row cap |
| `proxyConfiguration` | proxy | off | Optional — the endpoint is open |

#### Example input

```json
{
  "productIds": ["MLA57692573", "https://www.mercadolibre.com.mx/x/p/MLM1466527953"],
  "maxReviewsPerProduct": 200,
  "includeSummary": true
}
```

### Getting product IDs

This actor needs **catalog product ids** — the `MLA…`/`MLB…`/`MLM…` code in a
product URL's `…/p/MLA57692573` segment. You can feed the full product URL and the
actor extracts the id. (Item ids like `MLA-1234567890` are seller listings without
a catalog review page.) Pair it with the **MercadoLibre Scraper** actor, whose rows
include `product_id`, to review an entire search or category.

### Scheduling & integrations

Run on a **schedule** and export to **Google Sheets, Make, Zapier or S3**, or pull
the dataset via API:

```
https://api.apify.com/v2/datasets/<datasetId>/items?format=json
```

### Use it from an AI assistant (MCP)

Callable from AI agents via the **Apify MCP server** — an assistant can fetch "the
rating summary and worst reviews for product MLA57692573" and read structured rows.

### FAQ

**Do I need a proxy?** No — reviews come from an open endpoint.

**Why do I get "no reviews found"?** You likely passed an item id (`MLA-1234…`)
instead of a catalog product id (`MLA57692573`), or the product has no reviews yet.

**How many reviews can I get per product?** Set `maxReviewsPerProduct`; the actor
pages until it reaches that cap or runs out of reviews.

**Which countries?** All 18 MercadoLibre sites (Argentina, Brazil, Mexico, Chile,
Colombia, Peru, and more).

**Is it legal?** The actor collects only public review data. You are responsible
for using it in line with MercadoLibre's terms and applicable law.

# Actor input Schema

## `productIds` (type: `array`):

Catalog product ids (e.g. MLA57692573) or product-page URLs (…/p/MLA57692573). Use catalog product ids, not item ids (MLA-1234…).

## `site` (type: `string`):

Default country marketplace (used for plain ids without a URL).

## `maxReviewsPerProduct` (type: `integer`):

Stop after this many reviews for each product.

## `includeSummary` (type: `boolean`):

Emit one summary row per product (average score, star distribution, photo/video counts, AI review summary) before its reviews.

## `maxItems` (type: `integer`):

Global cap across all products (summary + review rows).

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

Reviews are served from an open endpoint, so no proxy is needed. Configure one only if you want to route through a specific region.

## Actor input object example

```json
{
  "productIds": [
    "MLA57692573",
    "https://www.mercadolibre.com.mx/.../p/MLM1234567"
  ],
  "site": "MLA",
  "maxReviewsPerProduct": 100,
  "includeSummary": true,
  "maxItems": 100000,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}
```

# Actor output Schema

## `dataset` (type: `string`):

No description

# 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 = {
    "productIds": [
        "MLA57692573"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("axlymxp/mercadolibre-reviews-scraper").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 = { "productIds": ["MLA57692573"] }

# Run the Actor and wait for it to finish
run = client.actor("axlymxp/mercadolibre-reviews-scraper").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 '{
  "productIds": [
    "MLA57692573"
  ]
}' |
apify call axlymxp/mercadolibre-reviews-scraper --silent --output-dataset

```

## MCP server setup

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

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/JegMaoYJo9qerpugz/builds/REjzwcB8eGNGSYyoq/openapi.json