# LatAm Product Price Intelligence (`qw3rt4/latam-product-price-intelligence`) Actor

Find, match, analyze, and rank compatible public product offers across six verified Latin American marketplaces.

- **URL**: https://apify.com/qw3rt4/latam-product-price-intelligence.md
- **Developed by:** [Miguel Fuentealba](https://apify.com/qw3rt4) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 27.3% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $50.00 / 1,000 completed price analyses

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?

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

## LatAm Product Price Intelligence

> **Unofficial tool.** This independent Actor is not affiliated with, sponsored,
> endorsed, or operated by Mercado Libre. Mercado Libre and related marks belong
> to their respective owners.

LatAm Product Price Intelligence is an Apify Actor that finds public product offers across six verified Latin American Mercado Libre marketplaces, rejects incompatible listings, calculates robust market-price statistics in the local currency, and ranks the best valid offers.

It is not a generic search-results scraper. The processing pipeline is:

**SEARCH → EXTRACT → NORMALIZE → MATCH → FILTER → ANALYZE → RANK**

### What problem it solves

Marketplace searches commonly mix the requested product with accessories, other models, other storage capacities, and promotional noise. Using every returned price produces misleading market averages and false “deals.” This Actor applies deterministic, explainable product matching before doing any price analysis.

The Actor supports Chile, Argentina, Colombia, Peru, Brazil, and Uruguay. It uses low-cost HTTP first and launches a browser only when the cloud response requires JavaScript rendering. It does not call an LLM or use an external database.

### Features

- Six cloud-verified country marketplaces with local domains, currencies, languages, and condition routes
- Async HTTP, timeouts, retries with backoff, pagination, and clear 403/429 errors
- Playwright fallback only when static HTML contains no listing cards
- Optional Apify Proxy configuration, enabled by default for reliable cloud runs
- Deterministic normalization for brands, product families, models, variants, capacities, colors, and common model codes
- Strong rejection of accessories and incompatible model, code, capacity, and variant combinations
- Explainable match scores and rejection reasons
- IQR/MAD price-outlier detection and robust price statistics
- Listing-level currency detection with independent statistics and ranking per currency
- Dynamic offer ranking based only on available price, match, shipping, and official-store signals
- Ranked compatible offers in the Apify Dataset and a full summary in the `OUTPUT` record
- JSON, CSV, and Excel-compatible Dataset exports
- Predictable pay-per-event billing: one charge only after a complete analysis

### Example input

```json
{
  "query": "Samsung Galaxy S25 256GB",
  "country": "CL",
  "maxOffers": 50,
  "condition": "new",
  "minMatchScore": 0.8
}
```

#### Input fields

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `query` | string | required | Specific product name; include the model and capacity when relevant. |
| `country` | string | `CL` | `CL`, `AR`, `CO`, `PE`, `BR`, or `UY`. |
| `maxOffers` | integer | `50` | Maximum listings inspected, from 5 to 100. |
| `condition` | string | `new` | `new`, `used`, or `all`. |
| `minMatchScore` | number | `0.80` | Match confidence threshold from 0 to 1. |

### Output

Each compatible offer is stored as a Dataset item:

```json
{
  "id": "MLC2836919992",
  "title": "Samsung Galaxy S25 256G Azul Marino",
  "price": 599990,
  "currency": "CLP",
  "url": "https://www.mercadolibre.cl/...",
  "condition": "new",
  "seller": {
    "name": "Samsung",
    "reputation": null,
    "officialStore": true
  },
  "shipping": { "free": true },
  "attributes": {},
  "normalized": {
    "brand": "samsung",
    "family": "galaxy s",
    "model": "s25",
    "storageGb": 256,
    "color": "blue"
  },
  "match": {
    "matched": true,
    "score": 0.96,
    "reasons": []
  },
  "isOutlier": false,
  "offerScore": 0.94
}
```

Fields unavailable on the public search page are `null` or empty; the Actor never fabricates seller reputation or product attributes.

The run summary is stored in the default key-value store as `OUTPUT`:

```json
{
  "status": "matches_found",
  "message": "Found 31 compatible offers among 47 public listings.",
  "query": "Samsung Galaxy S25 256GB",
  "country": "CL",
  "offersFound": 47,
  "offersMatched": 31,
  "offersRejected": 16,
  "rejectionReasons": {
    "accessory_detected": 5,
    "storage_mismatch": 7,
    "variant_mismatch": 4
  },
  "outliers": 2,
  "priceIntelligence": {
    "currency": "CLP",
    "min": 749990,
    "percentile25": 799990,
    "median": 829990,
    "average": 833450,
    "percentile75": 879990,
    "max": 919990,
    "spreadPercent": 22.67
  },
  "bestOffer": {
    "id": "MLC123456789",
    "title": "...",
    "price": 749990,
    "currency": "CLP",
    "seller": null,
    "matchScore": 0.98,
    "offerScore": 0.94,
    "url": "https://..."
  },
  "durationSeconds": 3.42,
  "requests": 2
}
```

The values above illustrate the schema only; each run uses current public offers.
When no listing passes the compatibility filter, `status` is
`no_compatible_offers`, `message` explains what happened, and
`rejectionReasons` shows why the public listings were rejected. An empty matched
Dataset therefore does not claim that the product is unavailable everywhere.

When compatible listings use more than one currency, the summary also returns
`priceIntelligenceByCurrency` and `bestOffersByCurrency`. Statistics, outlier
detection, and ranking are calculated independently for each currency; the Actor
does not invent or silently apply an exchange rate. The legacy `priceIntelligence`
and `bestOffer` fields remain populated for single-currency results.

### Use cases

- Market-price research before purchasing or selling a product
- E-commerce competitive-price checks
- Sourcing and procurement shortlists
- Structured product-offer feeds for spreadsheets and BI tools
- Deal discovery with low-price outliers explicitly flagged

### Run locally

Requirements: Python 3.11+ and the Apify CLI.

```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements-dev.txt
apify run
```

The repository includes the example development input at `storage/key_value_stores/default/INPUT.json`, so the command works immediately. Edit that file to test another product, or use `apify run --input-file path/to/input.json`. Local Dataset and `OUTPUT` data are written under `storage/` by the Apify SDK.

The normal local path uses HTTP and does not need a local browser. If a local
response also requires the browser fallback, install Chromium once with
`playwright install chromium` inside the virtual environment.

Quality checks:

```powershell
ruff format .
ruff check .
pytest
```

To simulate pay-per-event billing locally without a real charge:

```powershell
$env:ACTOR_TEST_PAY_PER_EVENT = "true"
apify run --purge
Remove-Item Env:ACTOR_TEST_PAY_PER_EVENT
```

The SDK writes the simulated event to the local `charging-log` Dataset. Its local
test price can differ from the Store price. It also logs synthetic Dataset-item
events in test mode; those default events must be removed in Console. Verify that
`price-analysis` itself appears exactly once.

### API usage

After deployment, start the Actor through the Apify API using your Actor ID and API token:

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/YOUR_USERNAME~latam-product-price-intelligence/runs?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query":"Samsung Galaxy S25 256GB","country":"CL","maxOffers":50,"condition":"new"}'
```

The run response links to its default Dataset and key-value store. Apify also provides synchronous endpoints and generated clients; choose the execution mode appropriate for your workflow.

### Deploy

Authenticate the Apify CLI, then run:

```powershell
apify login
apify push
```

No deployment or credential operation is performed automatically by this repository.

### Limitations

- Supported marketplaces are Chile, Argentina, Colombia, Peru, Brazil, and Uruguay. Mexico is temporarily unavailable because repeated private cloud tests were blocked by the public marketplace with HTTP 403. Other countries are rejected explicitly rather than routed to the wrong domain.
- Matching is deterministic and optimized for common technology naming. Unusual categories or incomplete titles can require a lower threshold or future category-specific rules.
- Portuguese accessory, color, condition, and shipping terms are supported for Brazil; broader category-specific Portuguese vocabulary can still require additional rules.
- The Actor reads public search-result HTML. Mercado Libre can change its markup or restrict automated requests; in that case the Actor fails clearly instead of emitting fabricated data.
- Seller reputation and detailed attributes are returned as `null`/empty when search results do not expose them reliably.
- `all` condition searches can contain items whose condition is not displayed in the result card; those items use `null` for `condition`.
- No historical prices, alerts, CAPTCHA handling, login scraping, or other retailers are included. The browser fallback renders public pages only and does not solve challenges or bypass authentication.

### Privacy

The Actor processes the submitted product query and public marketplace results. It does not request login credentials, access private listings, create user accounts, or send data to an external database. Apify stores run inputs and outputs according to the retention and privacy settings of your Apify account.

### Troubleshooting

**HTTP 403** — Mercado Libre denied the public request. Keep an available Apify
Proxy option enabled and retry with a new run.

**HTTP 407** — The selected proxy option is not available on the current Apify
plan. Use Datacenter with the `Anywhere` location, choose an available custom
proxy, or select No proxy for a direct attempt. Saved Datacenter inputs with a
legacy country value are normalized to `Anywhere` automatically.

**Cloud run returns no parseable listings** — Keep Apify Proxy enabled in the
input's Connection section. The Actor automatically retries once with its browser
fallback. If both paths return no cards, the selected proxy is restricted and the
run fails instead of fabricating results.

**HTTP 429** — The marketplace rate-limited the run. The Actor retries with backoff and then fails clearly if the limit persists.

**No parseable listings** — Confirm the same query returns public results in a browser. Mercado Libre may have changed its page structure; update the offline parser fixture and selectors together.

**Too few matches** — Make the query precise and include model/capacity. For genuinely ambiguous titles, lower `minMatchScore` cautiously.

### Pricing

This Actor is prepared for pay-per-event pricing at a launch price of **USD 0.05
per completed price analysis**. A run emits exactly one `price-analysis` event
after scraping, compatibility filtering, price analysis, and ranking complete,
and before paid results are delivered.

When monetization is configured in Apify Console, keep the recommended synthetic
`apify-actor-start` event at its default price and remove
`apify-default-dataset-item`. The start event covers the first five seconds of
compute; removing the Dataset-item event prevents an extra fee for every matched
offer. The publication checklist in `STORE_PUBLICATION.md` records this as a
required go-live check.

Invalid input, scraping failures, and runs whose maximum charge limit cannot cover
the event do not deliver paid output. The Apify Store run screen shows the active
price and lets users set a maximum charge limit before execution; the price
configured in the Store Console is the authoritative price.

### Responsible use

Use this Actor only for lawful access to public data and follow Mercado Libre's terms and applicable regulations. It does not bypass authentication, solve CAPTCHAs, or implement aggressive anti-bot evasion. This is an independent, unofficial tool and is not endorsed by Mercado Libre.

# Actor input Schema

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

Use a precise product name including model and capacity when relevant.

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

Country marketplace used for the search, local currency, and optional proxy location.

## `maxOffers` (type: `integer`):

Maximum number of public search listings to inspect.

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

Search new items, used items, or both.

## `minMatchScore` (type: `number`):

Advanced confidence threshold. Higher values are stricter.

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

Residential Apify Proxy is recommended for reliable cloud access to public marketplace pages.

## Actor input object example

```json
{
  "query": "Samsung Galaxy S25 256GB",
  "country": "CL",
  "maxOffers": 50,
  "condition": "new",
  "minMatchScore": 0.8,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `offers` (type: `string`):

Clean, compatible offers ranked by offer score.

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

Status, message, rejection reasons, counts, robust price statistics, best offer, duration, and request usage.

# 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 = {
    "query": "Samsung Galaxy S25 256GB",
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("qw3rt4/latam-product-price-intelligence").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 = {
    "query": "Samsung Galaxy S25 256GB",
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("qw3rt4/latam-product-price-intelligence").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 '{
  "query": "Samsung Galaxy S25 256GB",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call qw3rt4/latam-product-price-intelligence --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,qw3rt4/latam-product-price-intelligence"
        }
    }
}

```

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/vWpXRRIXVk1GdoJlq/builds/6LLHgC2VwHtHuQUVn/openapi.json