# Mercado Livre Search

## Overview

| Property | Value |
|----------|-------|
| **Status** | private |
| **Method** | `GET` |
| **Endpoint** | `/v2/mercado/search` |
| **Base URL** | `https://api.piloterr.com` |
| **Credit Cost** | 1 credit per call |
| **Documentation** | https://www.piloterr.com/library/mercado-search |

## Description

Search Mercado Livre Brazil product listings by keyword and get title, price, seller, rating, condition, and shipping details as structured JSON in real time.

## Authentication

- **Key Name:** `x-api-key`
- **Location:** HTTP Header
- **Get an API key:** https://app.piloterr.com/register

## Example Request

```bash
curl --location --request GET 'https://api.piloterr.com/v2/mercado/search' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
```

## Example Response

### Search for 'iphone 14'

```json
{
  "page": 1,
  "results": [
    {
      "id": "MLB3619890194",
      "url": "https://www.mercadolivre.com.br/apple-iphone-14-128-gb-preto/p/MLB20505848",
      "tags": [
        "good_seller",
        "extended_warranty_eligible",
        "brand_verified"
      ],
      "price": 3799.99,
      "title": "Apple iPhone 14 (128 GB) - Preto",
      "rating": {
        "total": 5312,
        "average": 4.8
      },
      "seller": {
        "id": 223890471,
        "nickname": "APPLE_OFICIAL_BR",
        "reputation_level": "platinum"
      },
      "shipping": {
        "free_shipping": true,
        "store_pick_up": false
      },
      "condition": "new",
      "thumbnail": "https://http2.mlstatic.com/D_NQ_NP_773843-MLB72205109484_102023-O.webp",
      "category_id": "MLB1055",
      "currency_id": "BRL",
      "installments": {
        "rate": 0,
        "amount": 316.67,
        "quantity": 12
      },
      "sold_quantity": 12430,
      "original_price": 4499,
      "available_quantity": 850
    }
  ],
  "total_results": 12847,
  "results_per_page": 20
}
```

## Documentation

## Overview

Mercado Livre is Brazil's largest e-commerce marketplace, with over 140 million active users and tens of millions of product listings. The platform uses Cloudflare to block automated access. Piloterr routes each request through infrastructure that handles the bypass, so you receive paginated search results as structured JSON with a single GET call. No proxy management, no CAPTCHA solving, no parsing.

Each result includes the listing title, current price in BRL, instalment details, seller reputation level, shipping conditions, and buyer rating.

## Quickstart

```
GET https://api.piloterr.com/v2/mercado/search?query=iphone+14
```

## Parameters

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search keyword or phrase |
| `category` | string | no | Mercado Livre category ID |
| `condition` | string | no | `new` or `used` |
| `min_price` | number | no | Minimum price in BRL |
| `max_price` | number | no | Maximum price in BRL |
| `sort` | string | no | Sort order for results |
| `page` | integer | no | Page number |

## Response fields

| Field | Type | Description |
|---|---|---|
| `results[].title` | string | Listing title |
| `results[].price` | number | Current price in BRL |
| `results[].condition` | string | Item condition |
| `results[].seller.reputation_level` | string | Seller reputation badge |
| `results[].rating.average` | number | Average star rating |
| `results[].shipping.free_shipping` | boolean | Free shipping flag |

## Main use cases

- Track real-time price changes on Mercado Livre for competitive pricing intelligence
- Monitor seller reputation to identify key vendors in a product segment
- Build a product comparison feed across Brazilian marketplaces
- Detect discount campaigns by comparing current vs original price at scale
- Enrich analytics dashboards with live Mercado Livre search data