# Kuantum Mercado Libre Search — Listings (`kuantum/mercado-libre-search-owned`) Actor

Search public Mercado Libre listings and extract structured product, price, and availability data with Kuantum Mercado Libre Search. Replace manual marketplace research with repeatable runs. Try it now and get your next market snapshot.

- **URL**: https://apify.com/kuantum/mercado-libre-search-owned.md
- **Developed by:** [\[R\] Kuantum](https://apify.com/kuantum) (community)
- **Categories:** E-commerce
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per usage

This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.

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

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Mercado Libre Search — Public Listings Actor

Search public Mercado Libre listings across Latin America through a hardened, proxy-capable Apify Actor. Enter a country, keyword, and optional filters to receive structured listing data in the default dataset.

### Store description

Mercado Libre Search is designed for reliable product intelligence: newest-first discovery, country-aware marketplaces, category and price filtering, seller filtering, shipping and condition filters, retries, response validation, duplicate detection, and transparent run metadata. It uses Apify proxy infrastructure when direct marketplace access is blocked.

#### Use cases

- Monitor current product prices and availability.
- Find newly published listings by country and keyword.
- Compare sellers, categories, conditions, and shipping options.
- Export clean listing rows to Apify Datasets for downstream analysis.

#### Input example

```json
{
  "country": "AR",
  "query": "iphone 15",
  "condition": "new",
  "sort": "date_desc",
  "limit": 50,
  "pages": 2,
  "useResidentialProxy": true
}
```

The Actor writes listing rows to its default dataset, stores a `CHECKPOINT` during collection, and stores `SEARCH_RESULT` with full raw pages, duplicate IDs, metadata warnings, and run statistics. Proxy traffic and Actor compute may incur Apify charges.

***

## Local client

This is a local, dependency-free Node.js client for Mercado Libre's public item search API.

### Run a newest-first search

```bash
npm run search -- --country argentina --query "iphone" --category MLA1055 --price-min 100 --price-max 1000 --condition new --sort date_desc
```

Supported site IDs include `MLA` (Argentina), `MLB` (Brazil), `MLM` (Mexico), `MLC` (Chile), `MCO` (Colombia), `MPE` (Peru), `MLU` (Uruguay), `MLV` (Venezuela), plus the other Mercado Libre regional site codes supported by the client.

Options:

- `--site` or `--country` required: site ID or country name/code.
- `--query` required: product search text.
- `--category` or `--category-id` optional: category ID (sent as the API's `category` filter).
- `--price-min`, `--price-max`, or `--price` optional: price range (`--price 100-1000` also works).
- `--condition` optional: for example `new` or `used`.
- `--listing-type` optional: listing type ID such as `gold_pro`.
- `--shipping` optional: use values returned by Mercado Libre filters, commonly `free`.
- `--buying-mode`, `--seller-id`, `--official-store-id` optional filters.
- `--limit` optional: results per request, default `50`.
- `--pages` optional: number of pages, default `1`, maximum `20` (about 1,000 results through offset pagination).
- `--sort` optional: sort value, default `date_desc`.
- `--output` optional: JSON output path, default `data/search-<timestamp>.json`.
- `--dry-run` optional: print generated request URLs without calling the API.
- `--force` optional: allow overwriting an existing output file.
- `--format` optional: `json`, `csv`, or `both`; JSON preserves raw API pages and CSV contains deduplicated listings.
- `--checkpoint` optional: checkpoint path; defaults beside the output and is removed after success.
- `--resume PATH` optional: resume from a prior checkpoint.
- `--allow-external-output` optional: permit an output path outside the project `data/` directory.

The saved file contains the complete API response for every page, including every field returned in each listing. It also records metadata warnings when Mercado Libre does not provide enough information to verify a requested sort or filter. The public search API can filter public listings by seller with `--seller-id`; private seller-account inventory requires OAuth and a different endpoint.

Run local validation without network access:

```bash
npm test
```

### Owned Apify Actor

The same hardened search core is available as an Apify Actor. It uses Apify proxy infrastructure, pushes deduplicated listings to the default dataset, and stores `CHECKPOINT` and `SEARCH_RESULT` records in the default key-value store.

```bash
npm install
npm run actor:validate
npm run actor:run -- --input '{"country":"AR","query":"iphone","pages":1}'
npm run actor:push
```

Set `useResidentialProxy` to `true` for the intended 403-resistant path. Proxy traffic and Actor execution may incur Apify charges.

Resume an interrupted search:

```bash
npm run search -- --site MLA --query "iphone" --pages 10 --output data/iphones.json
npm run search -- --site MLA --query "iphone" --pages 10 --output data/iphones.json --resume data/iphones.json.checkpoint.json --force
```

### Important limits

Mercado Libre documents a default page size of 50. Offset pagination is practically limited to approximately 1,000 results. For larger seller-owned listing exports, use the authenticated `search_type=scan` and `scroll_id` flow instead.

### Example

```bash
npm run search -- --site MLM --query "laptop" --limit 50 --pages 2 --output data/laptops.json
```

# Actor input Schema

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

Mercado Libre site code such as MLA, MLB, or MLM.

## `country` (type: `string`):

Country name or code; use instead of site.

## `query` (type: `string`):

Keyword or phrase to search in public Mercado Libre listings.

## `category` (type: `string`):

Optional Mercado Libre category identifier.

## `priceMin` (type: `number`):

Optional minimum price in the marketplace currency.

## `priceMax` (type: `number`):

Optional maximum price in the marketplace currency.

## `condition` (type: `string`):

Optional condition filter such as new or used.

## `listingType` (type: `string`):

Optional Mercado Libre listing type identifier.

## `shipping` (type: `string`):

Optional shipping filter value returned by the API.

## `buyingMode` (type: `string`):

Optional buying mode filter.

## `sellerId` (type: `string`):

Optional public seller identifier.

## `officialStoreId` (type: `string`):

Optional official store identifier.

## `sort` (type: `string`):

Sort identifier, commonly date\_desc for newest first.

## `limit` (type: `integer`):

Number of listings requested per page.

## `pages` (type: `integer`):

Maximum number of offset pages to retrieve.

## `retries` (type: `integer`):

Maximum retries for transient API failures.

## `timeout` (type: `integer`):

Timeout for each API request.

## `useResidentialProxy` (type: `boolean`):

Route requests through Apify residential proxy infrastructure.

## `proxyGroups` (type: `array`):

Apify proxy groups to use when proxying requests.

## `proxySession` (type: `string`):

Optional stable Apify Proxy session ID for this run. Use only letters, numbers, underscore, dot, and tilde. Do not enter proxy credentials.

## `browserStateKey` (type: `string`):

Optional Key-Value Store key containing an authorized Playwright storageState JSON object.

## `proxyMode` (type: `string`):

Explicit proxy mode: APIFY\_RESIDENTIAL, APIFY\_DATACENTER, CUSTOM, or NONE.

## `customProxyUrl` (type: `string`):

Optional authenticated proxy URL used only with CUSTOM. Prefer an Apify Secret or secured input; never log this value.

## `browserProvider` (type: `string`):

Use local Chromium or a Browserless managed Chromium session. Browserless requires BROWSERLESS\_TOKEN in the Actor environment.

## `browserlessProxy` (type: `string`):

Optional Browserless-managed proxy tier. This is independent of Apify Proxy.

## `challengeRetries` (type: `integer`):

Maximum controlled retries after challenge or HTTP block.

## `warmUpSession` (type: `boolean`):

Visit the public marketplace homepage before search navigation.

## `navigationDelayMinMs` (type: `integer`):

Minimum delay in milliseconds before navigation.

## `navigationDelayMaxMs` (type: `integer`):

Maximum delay in milliseconds before navigation.

## Actor input object example

```json
{
  "sort": "date_desc",
  "limit": 50,
  "pages": 1,
  "retries": 3,
  "timeout": 30000,
  "useResidentialProxy": true,
  "proxyGroups": [
    "RESIDENTIAL"
  ],
  "proxyMode": "APIFY_RESIDENTIAL",
  "browserProvider": "LOCAL",
  "browserlessProxy": "NONE",
  "challengeRetries": 3,
  "warmUpSession": true,
  "navigationDelayMinMs": 3000,
  "navigationDelayMaxMs": 7000
}
```

# Actor output Schema

## `listings` (type: `string`):

Structured listing rows written by the Actor.

# 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 = {};

// Run the Actor and wait for it to finish
const run = await client.actor("kuantum/mercado-libre-search-owned").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 = {}

# Run the Actor and wait for it to finish
run = client.actor("kuantum/mercado-libre-search-owned").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 '{}' |
apify call kuantum/mercado-libre-search-owned --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,kuantum/mercado-libre-search-owned"
        }
    }
}

```

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/keQiqFdotogazIfPz/builds/O9FCXaOtyFnNyQViK/openapi.json