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

{
  "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

$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:

$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.

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:

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

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