# OLX Brazil Scraper — Ads, Prices, Location & Seller Data (`haketa/olx-brasil-scraper`) Actor

Scrape OLX Brasil (olx.com.br) classified ads by keyword, category or URL. Get title, price, price drops, photos, location (city, neighbourhood, state, DDD), attributes, vehicle specs, market-price benchmarks and seller data. Export to JSON/CSV/Excel for price monitoring, leads and market research.

- **URL**: https://apify.com/haketa/olx-brasil-scraper.md
- **Developed by:** [Haketa](https://apify.com/haketa) (community)
- **Categories:** E-commerce, Real estate, Lead generation
- **Features:** Limited permissions
- **Stats:** 36 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## OLX Brazil Scraper — Classified Ads, Prices, Locations, Vehicle Specs & Seller Data

> **Extract structured classified listings from OLX Brasil ([olx.com.br](https://www.olx.com.br)) — Brazil's largest online marketplace.** Turn any keyword search, department category, or regional URL into a clean, normalized dataset: **ad title, numeric BRL price, price-drop flags, full photo gallery, municipality / neighborhood / state (UF) / DDD phone area code, category-specific attributes, OLX Pay & Delivery flags, and seller type** — plus optional detail-page enrichment for **seller name & public ID, full description, vehicle specifications, and vehicle market-price benchmarks**.

Export every result to **JSON, CSV, Excel, HTML, XML, or the Apify API** — no login, no manual scraping.

[![Apify Actor](https://img.shields.io/badge/Apify-Actor-blue)](https://apify.com/haketa/olx-brasil-scraper)
[![Live Data](https://img.shields.io/badge/Data-Live%20at%20Run%20Time-orange)]()
[![Scale](https://img.shields.io/badge/Scale-1%2C000%2B%20Results%20Pagination-green)]()
[![Pricing](https://img.shields.io/badge/Pricing-Pay%20Per%20Result-yellow)]()
[![Region](https://img.shields.io/badge/Region-Brazil%20%F0%9F%87%A7%F0%9F%87%B7-brightgreen)]()
[![Coverage](https://img.shields.io/badge/Categories-Cars%20%C2%B7%20Property%20%C2%B7%20Electronics-purple)]()
[![Currency](https://img.shields.io/badge/Currency-BRL%20\(R%24\)-success)]()
[![Export](https://img.shields.io/badge/Export-JSON%20%C2%B7%20CSV%20%C2%B7%20Excel-lightgrey)]()

***

### ⚡ At a glance

| Feature | Details |
|---|---|
| 🎯 **Target marketplace** | **[OLX Brasil (olx.com.br)](https://www.olx.com.br)** — Brazil's #1 classifieds marketplace across all 27 federative units (UFs) |
| 🗂️ **Supported verticals** | Autos & Parts (`autos-e-pecas`), Real Estate (`imoveis`), Electronics & Phones (`eletronicos-e-celulares`), Home & Appliances, Fashion, Jobs, Agro & Industry, Services, and more |
| 💰 **Price intelligence** | Normalized integer `price` in BRL (`R$`), formatted `priceText`, previous `oldPrice`, and `priceDropped` reduction badge |
| 📍 **Structured location** | Broken down into `state` (2-letter UF), `city` (municipality), `neighbourhood`, `ddd` (phone area code), and `locationLabel` |
| 🧩 **Dynamic attributes** | Category-specific `attributes` object (brand, model, storage, condition, battery health, mileage, fuel, rooms, m², condo fee, etc.) |
| 🚗 **Detail enrichment** | Optional `fetchDetails: true` extracts `sellerName`, `sellerId`, full `description`, vehicle specs (`vehicleYear`, `vehicleMileage`, `vehicleFuel`, `vehicleTransmission`), and **vehicle market-price benchmarks** (`marketPriceMin`, `marketPriceMedian`, `marketPriceMax`) |
| 🔁 **Pagination & Scale** | Automatic multi-page traversal (~50 ads/page) supporting **1,000+ results pagination** per run with deterministic `listId` deduplication |
| 📦 **Bulk export** | JSON, JSONL, CSV, Excel (XLSX), HTML, XML, RSS, and REST API endpoints |

***

### 🔎 Why scrape OLX Brasil?

**[OLX Brasil](https://www.olx.com.br)** is the heartbeat of Brazil's recommerce, automotive, and real estate classifieds economy, hosting **tens of millions of active listings** across São Paulo, Rio de Janeiro, Minas Gerais, Paraná, Rio Grande do Sul, Bahia, Distrito Federal, and every state in the country. Whether you are tracking smartphone resale values, benchmarking used-car prices against FIPE/market medians, monitoring apartment rents by neighborhood, or building B2B lead lists of professional dealerships (`isProfessional: true`), OLX Brasil holds the live ground truth.

Collecting this data manually or with basic scripts quickly runs into roadblocks:

- **Massive pagination:** High-volume categories and keywords span dozens to hundreds of pages (~50 ads per page).
- **Inconsistent Brazilian currency & attribute formatting:** Prices appear as `R$ 2.490`, while critical product specifications (storage, condition, mileage, rooms, condo fees) are nested inside category-specific attribute arrays.
- **Regional access blocks:** OLX Brasil restricts non-Brazilian and datacenter IP ranges, requiring automatic session management over Brazilian residential IPs.

This **OLX Brasil scraper** handles session rotation, multi-page traversal, BRL price parsing, location splitting, and `listId` deduplication out of the box — delivering an analysis-ready dataset in seconds.

#### Common reasons teams use this OLX Brasil data extractor

- 📊 **E-commerce & Recommerce Price Monitoring** — Track live asking prices and `priceDropped` events for iPhones, notebooks, consoles, and appliances across Brazil.
- 💸 **Reselling & Arbitrage Sourcing** — Spot underpriced electronics, collectibles, and auto parts the moment they are published (`publishedAt`).
- 🚗 **Used-Car & Motorcycle Valuation** — Extract vehicle listings with odometer mileage, model year, fuel type, transmission, and OLX's built-in **market-price range (`marketPriceMin` / `Median` / `Max`)** to identify below-market inventory.
- 🏠 **Real Estate Market Intelligence** — Benchmark apartment and house sale/rental prices (`imoveis`) by state (`state`), municipality (`city`), and neighborhood (`neighbourhood`).
- 🏢 **B2B Lead Generation** — Filter `isProfessional == true` (or `sellerType == "Professional"`) and group by `ddd` area code and `state` to build targeted lists of car dealerships, real estate brokerages, and electronics stores.

***

### ✨ What this OLX Brasil scraper does

- ✅ **Search by keyword, category, or exact URL** — Run multiple keywords in `searchQueries`, select a department in `category`, browse a whole category without keywords, or paste custom filtered URLs in `startUrls`.
- ✅ **Unlocked 1,000+ results pagination** — Automatically steps through result pages (`?o=1, 2, 3 …`), collecting ~50 ads per page until your `maxItemsPerSearch` or `maxTotalItems` target is reached.
- ✅ **100% deduplicated output** — Every listing is keyed on its unique OLX `listId`, ensuring zero duplicates even when searches overlap.
- ✅ **Normalized BRL pricing & discount tracking** — Converts Brazilian currency strings into numeric `price` and `oldPrice` integers alongside `priceDropped: true/false`.
- ✅ **Granular Brazilian geography** — Separates every listing's location into `state` (UF), `city`, `neighbourhood`, and `ddd` (2-digit telephone area code).
- ✅ **Rich category `attributes` dictionary** — Preserves all structured item properties (e.g., `Marca`, `Modelo`, `Condição`, `Memória interna`, `Quilometragem`, `Quartos`, `Área útil`) as a clean JSON object.
- ✅ **Seller & marketplace badges** — Captures `isProfessional`, `sellerType` (`Private` vs `Professional`), `isFeatured`, `hasOlxPay`, `hasOlxDelivery`, and `sellerGoogleRating`.
- ✅ **Optional deep ad enrichment (`fetchDetails: true`)** — Opens each ad page to extract `sellerName`, `sellerId`, full text `description`, structured `vehicleBrand` / `vehicleModel` / `vehicleYear` / `vehicleMileage` / `vehicleFuel` / `vehicleTransmission` / `vehicleBodyType` / `vehicleDoors`, and **market-price benchmarks**.

***

### 🎯 Use cases

#### 1. Used-Car Dealerships, Auto Portals & Fleet Buyers

- **Instant below-market car alerts:** Scrape `autos-e-pecas` with `fetchDetails: true`, compare each listing's asking `price` against `marketPriceMedian`, and flag vehicles priced >12% below median market value.
- **Dealer inventory intelligence:** Filter `isProfessional: true` across São Paulo (`DDD 11`) or Rio (`DDD 21`) to monitor professional dealer stock and pricing velocity.

#### 2. Recommerce Platforms, Flippers & Electronics Resellers

- **Smartphone & console price indexes:** Track daily median asking prices for `iphone 13`, `iphone 14`, `iphone 15`, `playstation 5`, and `macbook` stratified by storage (`Memória interna`), condition (`Condição`), and battery health (`Saúde da bateria`).
- **OLX Pay & Delivery sourcing:** Filter `hasOlxPay == true` and `hasOlxDelivery == true` to find nationwide shippable inventory with buyer protection.

#### 3. Real Estate Analysts & Proptech Teams

- **Rental & sale yield mapping:** Scrape `category: "imoveis"` (or state-specific URLs via `startUrls`) and extract room counts, square footage, condominium fees, and IPTU from `attributes` across Brazilian municipalities.

#### 4. B2B Sales & Marketplace Growth Teams

- **Merchant acquisition pipelines:** Identify high-volume professional sellers (`isProfessional: true`) operating in specific states (`state`) and phone regions (`ddd`) for B2B SaaS, financing, or logistics outreach.

***

### 📥 Input parameters

Configure the actor via the Apify Console form or pass JSON through the API. All parameters are optional — running with empty inputs returns a diverse 100-item sample across Brazil's most popular searches.

| Parameter | Type | Default | Prefill | Description |
|---|---|---|---|---|
| `searchQueries` | `array<string>` | `[]` | `["iphone"]` | One or more search keywords (e.g., `["iphone 13", "honda civic", "apartamento"]`). Each keyword runs as an independent paginated search. Leave empty to browse your chosen `category` or run a popular multi-category mix. |
| `category` | `string` | `""` | `""` | Optional OLX department slug (`autos-e-pecas`, `imoveis`, `eletronicos-e-celulares`, etc.). Empty = all categories. |
| `minPrice` | `integer` | — | — | Minimum asking price in Brazilian Reais (BRL). |
| `maxPrice` | `integer` | — | — | Maximum asking price in Brazilian Reais (BRL). |
| `fetchDetails` | `boolean` | `false` | `false` | When `true`, visits each individual ad page to enrich `sellerName`, `sellerId`, `description`, vehicle specs, and market-price benchmarks. Leave `false` for maximum speed. |
| `maxItemsPerSearch` | `integer` | `0` | `100` | Maximum ads to collect per keyword or start URL. `0` = unlimited (governed by `maxTotalItems`). |
| `maxTotalItems` | `integer` | `0` | — | Global cap across all searches in the run (`0` = unlimited). Set to `1000`+ for deep sweeps. |
| `startUrls` | `array<string>` | `[]` | — | Advanced: Paste full `olx.com.br` search, category, state, or city URLs. Overrides `searchQueries` and `category` when provided. |
| `proxyConfiguration` | `object` | Residential `BR` | Residential `BR` | Proxy settings. **Brazilian (`BR`) residential proxy** is enabled by default and strongly recommended. |

#### Sample Input Recipes

##### Recipe 1: Fast keyword search (100 listings in ~15 seconds)

```json
{
  "searchQueries": ["iphone"],
  "maxItemsPerSearch": 100,
  "fetchDetails": false
}
```

##### Recipe 2: Deep 1,000+ listing category & multi-keyword extraction

```json
{
  "searchQueries": ["iphone 13", "iphone 14", "iphone 15", "samsung s23", "macbook"],
  "category": "eletronicos-e-celulares",
  "minPrice": 1000,
  "maxPrice": 8000,
  "maxItemsPerSearch": 300,
  "maxTotalItems": 1500
}
```

##### Recipe 3: Used cars with full specs & market-price benchmarks

```json
{
  "searchQueries": ["honda civic", "toyota corolla"],
  "category": "autos-e-pecas",
  "fetchDetails": true,
  "maxItemsPerSearch": 100
}
```

##### Recipe 4: State / City / Custom Sort via `startUrls`

```json
{
  "startUrls": [
    "https://www.olx.com.br/estado-sp/regiao-de-sao-paulo/imoveis/aluguel?q=apartamento",
    "https://www.olx.com.br/estado-rj/rio-de-janeiro-e-regiao/autos-e-pecas/carros-vans-e-utilitarios"
  ],
  "maxItemsPerSearch": 500,
  "maxTotalItems": 1000
}
```

***

### 📤 Output schema & field reference

Each OLX ad is normalized into a flat JSON record. Below is a real record from a verified run:

```json
{
  "listId": "1500809561",
  "title": "iPhone 14 Plus 128GB Midnight c/ Caixa",
  "price": 2490,
  "priceText": "R$ 2.490",
  "oldPrice": null,
  "priceDropped": false,
  "category": "Celulares e Smartphones",
  "categoryId": "3060",
  "isProfessional": false,
  "isFeatured": false,
  "state": "RJ",
  "city": "Niterói",
  "neighbourhood": "Largo da Batalha",
  "ddd": "21",
  "locationLabel": "Niterói, Largo da Batalha",
  "publishedAt": "2026-10-31T11:09:29.000Z",
  "imageUrl": "https://img.olx.com.br/images/43/437679042999046.jpg",
  "imageCount": 5,
  "images": [
    "https://img.olx.com.br/images/43/437679042999046.jpg",
    "https://img.olx.com.br/images/45/455669524947931.jpg"
  ],
  "attributes": {
    "Categoria": "Celulares e Smartphones",
    "Marca": "APPLE",
    "Modelo": "IPHONE 14",
    "Condição": "Usado - Excelente",
    "Memória interna": "128GB",
    "Cor": "Preto",
    "Saúde da bateria": "Boa (80% até 94%)",
    "Aceita trocas": "Não"
  },
  "sellerGoogleRating": null,
  "hasOlxPay": true,
  "hasOlxDelivery": false,
  "sellerName": null,
  "sellerId": null,
  "sellerType": "Private",
  "phoneVerified": null,
  "description": null,
  "vehicleBrand": null,
  "vehicleModel": null,
  "vehicleYear": null,
  "vehicleMileage": null,
  "vehicleFuel": null,
  "vehicleTransmission": null,
  "vehicleBodyType": null,
  "vehicleDoors": null,
  "marketPriceMin": null,
  "marketPriceMedian": null,
  "marketPriceMax": null,
  "marketSampleSize": null,
  "url": "https://rj.olx.com.br/rio-de-janeiro-e-regiao/celulares/iphone-14-plus-128gb-midnight-c-caixa-1500809561",
  "searchTerm": "iphone",
  "scrapedAt": "2026-11-01T23:45:11.000Z"
}
```

#### 🏷️ Core Listing, Price & Marketplace Fields

| Field | Type | Coverage | Description |
|---|---|---|---|
| `listId` | `string` | 🟢 High (100%) | Unique OLX Brasil ad identifier used for deduplication |
| `title` | `string` | 🟢 High (100%) | Listing headline as published by the seller |
| `price` | `integer \| null` | 🟢 High (~98%) | Normalized integer price in BRL (`null` only when unpriced / "a combinar") |
| `priceText` | `string \| null` | 🟢 High (~98%) | Original formatted price string (e.g., `"R$ 2.490"`) |
| `oldPrice` | `integer \| null` | 🟡 Conditional | Previous BRL price when the listing has been discounted |
| `priceDropped` | `boolean` | 🟢 High (100%) | `true` if OLX displays a price-reduction badge on the listing |
| `category` | `string` | 🟢 High (100%) | Human-readable OLX subcategory name (e.g., `"Celulares e Smartphones"`) |
| `categoryId` | `string` | 🟢 High (100%) | Internal OLX numeric category ID |
| `attributes` | `object \| null` | 🟢 High (~98%) | Key-value dictionary of category-specific attributes (brand, model, condition, rooms, mileage, etc.) |
| `hasOlxPay` | `boolean` | 🟢 High (100%) | `true` when OLX Pay online checkout is enabled |
| `hasOlxDelivery` | `boolean` | 🟢 High (100%) | `true` when OLX Delivery shipping is enabled |
| `isFeatured` | `boolean` | 🟢 High (100%) | `true` when the ad is promoted / pinned |
| `publishedAt` | `string` | 🟢 High (100%) | ISO-8601 timestamp when the ad was published |
| `url` | `string` | 🟢 High (100%) | Canonical direct URL to the OLX ad |
| `searchTerm` | `string` | 🟢 High (100%) | Keyword, category, or start URL that produced this record |
| `scrapedAt` | `string` | 🟢 High (100%) | ISO-8601 UTC extraction timestamp |

#### 📍 Location & Media Fields

| Field | Type | Coverage | Description |
|---|---|---|---|
| `state` | `string` | 🟢 High (100%) | Two-letter Brazilian state code (`SP`, `RJ`, `MG`, `PR`, `RS`, `BA`, `SC`, `DF`, etc.) |
| `city` | `string` | 🟢 High (100%) | Brazilian municipality name (e.g., `"São Paulo"`, `"Niterói"`, `"Belo Horizonte"`) |
| `neighbourhood` | `string \| null` | 🟢 High (~96%) | Neighborhood (`bairro`) name within the municipality |
| `ddd` | `string` | 🟢 High (100%) | 2-digit Brazilian telephone area code (`11`, `21`, `31`, `41`, `51`, etc.) |
| `locationLabel` | `string` | 🟢 High (100%) | Combined location label displayed on the listing card |
| `imageUrl` | `string \| null` | 🟢 High (~99%) | Primary thumbnail/main photo URL |
| `imageCount` | `integer` | 🟢 High (100%) | Total number of photos attached to the listing |
| `images` | `array<string>` | 🟢 High (~99%) | Full array of high-resolution photo URLs |

#### 👤 Seller, Vehicle Specs & Market Benchmarks (`fetchDetails` Enrichment)

| Field | Type | Coverage | Description |
|---|---|---|---|
| `isProfessional` | `boolean` | 🟢 High (100%) | `true` for commercial/professional accounts, `false` for private sellers (always populated) |
| `sellerType` | `string` | 🟢 High (100%) | `"Professional"` or `"Private"` (always populated) |
| `sellerGoogleRating` | `number \| null` | 🟡 Conditional | Seller's Google rating when displayed on professional accounts |
| `sellerName` | `string \| null` | 🟡 Opt-in (`fetchDetails`) | Seller display name extracted from the detail page |
| `sellerId` | `string \| null` | 🟡 Opt-in (`fetchDetails`) | Seller public UUID on OLX Brasil |
| `description` | `string \| null` | 🟡 Opt-in (`fetchDetails`) | Full plain-text ad description |
| `vehicleBrand` · `vehicleModel` | `string \| null` | 🟡 Opt-in (`fetchDetails`) | Vehicle manufacturer and model (for `autos-e-pecas` listings) |
| `vehicleYear` · `vehicleMileage` | `string \| null` | 🟡 Opt-in (`fetchDetails`) | Model year and odometer reading in km |
| `vehicleFuel` · `vehicleTransmission` | `string \| null` | 🟡 Opt-in (`fetchDetails`) | Fuel type (`Flex`, `Gasolina`, `Diesel`, `Álcool`) & transmission (`Automático`, `Manual`) |
| `vehicleBodyType` · `vehicleDoors` | `string \| null` | 🟡 Opt-in (`fetchDetails`) | Body style (`Sedã`, `SUV`, `Hatch`) and door count |
| `marketPriceMin` · `Median` · `Max` | `number \| null` | 🟡 Opt-in (`fetchDetails`) | OLX market-price floor, median (`p50`), and ceiling for comparable vehicles |
| `marketSampleSize` | `integer \| null` | 🟡 Opt-in (`fetchDetails`) | Number of comparable vehicles used in the market-price benchmark |

***

### 🗂️ OLX Brasil Categories & State URL Reference

#### Built-in Department Slugs (`category`)

| Department | `category` Value | Typical Attributes Extracted |
|---|---|---|
| **Autos & Parts** | `autos-e-pecas` | Brand, Model, Year, Mileage (km), Fuel, Transmission, Doors, Color, Final Plate |
| **Real Estate** | `imoveis` | Property Type, Rooms (`Quartos`), Bathrooms, Area (`m²`), Garage Spaces, Condo Fee, IPTU |
| **Electronics & Phones** | `eletronicos-e-celulares` | Brand, Model, Condition, Internal Storage (`Memória`), Color, Battery Health |
| **For Your Home** | `para-a-sua-casa` | Category, Condition, Type, Material |
| **Home Appliances** | `eletrodomesticos` | Type, Brand, Condition, Voltage (`110V` / `220V`) |
| **Fashion & Beauty** | `moda-e-beleza` | Category, Gender, Condition, Size |
| **Sports & Leisure** | `esportes-e-lazer` | Type, Condition, Brand |
| **Music & Hobbies** | `musica-e-hobbies` | Instrument/Hobby Type, Condition |
| **Kids & Baby** | `artigos-infantis` | Subcategory, Condition |
| **Pets** | `animais-de-estimacao` | Animal Type, Breed |
| **Agro & Industry** | `agro-e-industria` | Equipment Category, Condition |
| **Business & Office** | `comercio-e-escritorio` | Equipment Type, Condition |
| **Jobs** | `vagas-de-emprego` | Role, Contract Type |
| **Services** | `servicos` | Service Category |

#### Targeting Specific Brazilian States via `startUrls`

To restrict scraping to a single Brazilian state (UF), pass `https://www.olx.com.br/estado-{uf}?q={keyword}` (or combine with a category slug like `https://www.olx.com.br/{category}/estado-{uf}`) in `startUrls`:

- **São Paulo (`SP`):** `https://www.olx.com.br/estado-sp`
- **Rio de Janeiro (`RJ`):** `https://www.olx.com.br/estado-rj`
- **Minas Gerais (`MG`):** `https://www.olx.com.br/estado-mg`
- **Paraná (`PR`):** `https://www.olx.com.br/estado-pr`
- **Rio Grande do Sul (`RS`):** `https://www.olx.com.br/estado-rs`
- **Bahia (`BA`):** `https://www.olx.com.br/estado-ba`
- **Santa Catarina (`SC`):** `https://www.olx.com.br/estado-sc`
- **Distrito Federal (`DF`):** `https://www.olx.com.br/estado-df`

***

### 🔁 Pagination & scale

The **OLX Brazil Scraper** is designed for both quick 100-item checks and **1,000+ listing production runs**:

- **Automatic multi-page pagination:** Each OLX Brasil search page returns ~50 organic ads. The scraper automatically increments the `?o=2, 3, 4 …` pagination parameter until it reaches your `maxItemsPerSearch` / `maxTotalItems` target or the end of available results.
- **Category-only browsing:** If you select a `category` (e.g., `imoveis` or `autos-e-pecas`) and leave `searchQueries` empty, the actor paginates directly through the entire category feed nationwide.
- **Cross-search deduplication:** Every record is deduplicated in memory by `listId`. Running overlapping keywords or multi-region `startUrls` never produces duplicate rows (**0% duplicates** verified across 500+ ad runs).
- **Scaling past 5,000+ ads:** For massive nationwide pulls, pass multiple state URLs (`estado-sp`, `estado-rj`, `estado-mg`, `estado-pr`, `estado-rs`) in `startUrls` or split by price bands (`minPrice` / `maxPrice`).

***

### 💻 API Integration Examples

#### Python (`apify-client`)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_APIFY_TOKEN")

run = client.actor("haketa/olx-brasil-scraper").call(run_input={
    "searchQueries": ["iphone 14", "iphone 15"],
    "category": "eletronicos-e-celulares",
    "minPrice": 2000,
    "maxTotalItems": 1000,
    "fetchDetails": False,
})

for ad in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(f"R$ {ad['price']} | {ad['title']} | {ad['city']}-{ad['state']} (DDD {ad['ddd']}) | {ad['url']}")
```

#### Node.js / TypeScript (`apify-client`)

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: 'YOUR_APIFY_TOKEN' });

const run = await client.actor('haketa/olx-brasil-scraper').call({
    searchQueries: ['honda civic'],
    category: 'autos-e-pecas',
    fetchDetails: true,
    maxItemsPerSearch: 150,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
const belowMedian = items.filter(
    (ad) => ad.price && ad.marketPriceMedian && ad.price < ad.marketPriceMedian * 0.9
);
console.log(`Total cars: ${items.length} | >10% below median market price: ${belowMedian.length}`);
```

#### cURL

```bash
curl -X POST "https://api.apify.com/v2/acts/haketa~olx-brasil-scraper/runs?token=YOUR_APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "searchQueries": ["iphone"],
    "maxItemsPerSearch": 100
  }'
```

***

### ❓ Frequently Asked Questions

#### How many ads can I scrape per run, and how fast?

You can collect **1,000+ ads** in a single run. In default listing mode (`fetchDetails: false`), the actor scrapes ~50 ads per page and typically collects **100 ads in ~12–20 seconds** and **500 ads in ~45 seconds** with 0% duplicates.

#### Do I need an OLX Brasil account or login?

No. The actor extracts publicly available marketplace listings without logging in or requiring any OLX credentials.

#### Why is the Brazilian (`BR`) residential proxy enabled by default?

OLX Brasil blocks non-Brazilian and datacenter IP addresses at the edge. The actor comes pre-configured with Apify's Brazilian residential proxy pool (`apifyProxyCountry: "BR"`) and automatic session warm-up/rotation so runs succeed reliably.

#### When should I enable `fetchDetails: true`?

Leave `fetchDetails: false` when you need fast, low-cost extraction of prices, titles, photos, locations (`city`, `neighbourhood`, `state`, `ddd`), seller type (`Private` vs `Professional`), and category `attributes`. Enable `fetchDetails: true` when you specifically need the full text `description`, `sellerName`, `sellerId`, or vehicle market-price benchmarks (`marketPriceMin` / `Median` / `Max`).

#### Can I scrape a whole category without entering keywords?

Yes! Pick any department in `category` (for example `imoveis` or `autos-e-pecas`), leave `searchQueries` empty, and set `maxTotalItems: 1000`. The scraper will paginate directly through the category's nationwide listing stream.

#### Can I get seller phone numbers?

OLX Brasil masks direct phone numbers behind authenticated in-app chat. However, the actor extracts the listing's **`ddd` phone area code**, **`isProfessional` / `sellerType`**, and (when `fetchDetails: true`) **`sellerName`** and **`sellerId`**.

***

### 🔗 Related scrapers

Exploring classifieds and real estate marketplaces across Latin America and globally? Check out these sibling scrapers from [haketa](https://apify.com/haketa):

- [ZAP Imóveis Scraper (Brazil)](https://apify.com/haketa/zapimoveis-scraper) — Brazilian real estate listings, prices & seller contacts
- [VivaReal Scraper (Brazil)](https://apify.com/haketa/vivareal-scraper) — Brazil-wide property sales and rentals
- [OLX Poland Scraper](https://apify.com/haketa/olx-poland-classifieds-scraper) — OLX classifieds for Poland (`olx.pl`)
- [Marktplaats Scraper (Netherlands)](https://apify.com/haketa/marktplaats-scraper) — Netherlands' #1 classifieds marketplace
- [Kijiji Scraper (Canada)](https://apify.com/haketa/kijiji-scraper) — Canada's leading classified-ads platform
- [OfferUp Scraper (US)](https://apify.com/haketa/offerup-scraper) — US local buy-and-sell marketplace listings
- [Kleinanzeigen Scraper (Germany)](https://apify.com/haketa/kleinanzeigen-scraper) — Germany's largest classifieds marketplace

***

### 🔍 SEO Keywords

OLX Brazil scraper · OLX Brasil scraper · scrape OLX Brasil · olx.com.br data extractor · OLX Brasil API · Brazilian classifieds scraper · Brazil used car price scraper · OLX imóveis scraper · OLX carros scraper · OLX lead generation · bulk export JSON CSV Excel API · 1,000+ results pagination · B2B intelligence · recommerce Brazil dataset

***

### 📋 Changelog

| Version | Date | Notes |
|---|---|---|
| **1.2.0** | **2026-11** | **Unlocked 1,000+ deep pagination & category-only browsing:** Changed `maxItemsPerSearch` default to `0` (auto-governed by `maxTotalItems`), removed the 100-item clamp when users explicitly request `1,000+` items on default/category runs, enabled direct category pagination when `searchQueries` is empty, and raised pagination ceiling to 1,000 pages. |
| **1.1.0** | **2026-11** | **App Router RSC stream + legacy parser:** Updated search page extractor to decode OLX Brasil's current streaming payload alongside legacy `__NEXT_DATA__`. Verified 500 unique ads in ~44s with 0% duplicates and 100% core field fill. |
| **1.0.0** | **2026-07** | Initial release — Keyword, category & `startUrls` scraping, BRL price & discount normalization, UF/city/neighborhood/DDD breakdown, category `attributes`, and optional `fetchDetails` vehicle & seller enrichment. |

# Changelog

This Actor's version history is a separate document: https://apify.com/haketa/olx-brasil-scraper/changelog.md

# Actor input Schema

## `searchQueries` (type: `array`):

What do you want to find on OLX Brasil? Add one or more keywords such as 'iphone', 'honda civic' or 'apartamento' — each one runs as its own search. Leave this empty to get a ready-made mix of Brazil's most popular listings.

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

Focus your search on a single OLX department (cars, real estate, electronics, and more). Pick 'All categories' to search across the whole marketplace.

## `minPrice` (type: `integer`):

Only return ads priced at or above this value (in Brazilian Reais). Leave empty for no minimum.

## `maxPrice` (type: `integer`):

Only return ads priced at or below this value (in Brazilian Reais). Leave empty for no maximum.

## `fetchDetails` (type: `boolean`):

Open each ad page for extra data: full description, seller name & type, vehicle specs (fuel, mileage, transmission) and vehicle market-price benchmarks. Slower and uses more traffic — leave off for fast price/listing collection.

## `maxItemsPerSearch` (type: `integer`):

Maximum number of ads to collect per search term or URL. Set 0 for unlimited (governed by Max total items).

## `maxTotalItems` (type: `integer`):

Global cap across all searches. Set 0 for unlimited.

## `startUrls` (type: `array`):

Power-user option: paste full OLX Brasil search, category or region URLs to scrape them directly. Handy for targeting an exact state, city or sort order — apply those filters on olx.com.br, then copy the resulting URL here. When provided, these take priority over the search terms above.

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

OLX Brasil loads most reliably through Brazilian residential proxies. Keep the default (Apify residential, Brazil) for best results.

## Actor input object example

```json
{
  "searchQueries": [
    "iphone 13",
    "playstation 5"
  ],
  "category": "",
  "fetchDetails": false,
  "maxItemsPerSearch": 100,
  "maxTotalItems": 0,
  "startUrls": [
    "https://www.olx.com.br/eletronicos-e-celulares/celulares?q=iphone"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "BR"
  }
}
```

# Actor output Schema

## `listId` (type: `string`):

OLX listing ID

## `title` (type: `string`):

Ad title

## `price` (type: `string`):

Numeric price in Reais

## `priceText` (type: `string`):

Price as shown on OLX

## `oldPrice` (type: `string`):

Previous price before a drop

## `priceDropped` (type: `string`):

Whether the ad shows a price reduction badge

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

Ad category name

## `categoryId` (type: `string`):

OLX category ID

## `isProfessional` (type: `string`):

Whether the seller is a professional/business account

## `isFeatured` (type: `string`):

Whether the ad is featured/promoted

## `state` (type: `string`):

Brazilian state

## `city` (type: `string`):

Municipality

## `neighbourhood` (type: `string`):

Neighbourhood

## `ddd` (type: `string`):

Area phone code

## `locationLabel` (type: `string`):

Location as shown on OLX

## `publishedAt` (type: `string`):

Ad publication date (ISO)

## `imageUrl` (type: `string`):

First image URL

## `imageCount` (type: `string`):

Number of photos

## `images` (type: `string`):

All image URLs

## `attributes` (type: `string`):

Category-specific attributes (brand, model, condition, etc.)

## `sellerGoogleRating` (type: `string`):

Seller's Google rating, if shown

## `hasOlxPay` (type: `string`):

Whether OLX Pay is available

## `hasOlxDelivery` (type: `string`):

Whether OLX Delivery is available

## `url` (type: `string`):

Ad detail page URL

## `sellerName` (type: `string`):

Seller name (with Fetch ad details)

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

Seller public account ID (with Fetch ad details)

## `sellerType` (type: `string`):

Private or Professional (with Fetch ad details)

## `phoneVerified` (type: `string`):

Whether the seller's phone is verified (with Fetch ad details)

## `description` (type: `string`):

Full ad description (with Fetch ad details)

## `vehicleBrand` (type: `string`):

Vehicle brand (with Fetch ad details)

## `vehicleModel` (type: `string`):

Vehicle model (with Fetch ad details)

## `vehicleYear` (type: `string`):

Vehicle model year (with Fetch ad details)

## `vehicleMileage` (type: `string`):

Odometer reading (with Fetch ad details)

## `vehicleFuel` (type: `string`):

Vehicle fuel type (with Fetch ad details)

## `vehicleTransmission` (type: `string`):

Vehicle transmission (with Fetch ad details)

## `vehicleBodyType` (type: `string`):

Vehicle body type (with Fetch ad details)

## `vehicleDoors` (type: `string`):

Number of doors (with Fetch ad details)

## `marketPriceMin` (type: `string`):

Vehicle market price floor benchmark (with Fetch ad details)

## `marketPriceMedian` (type: `string`):

Vehicle market median price benchmark (with Fetch ad details)

## `marketPriceMax` (type: `string`):

Vehicle market price ceiling benchmark (with Fetch ad details)

## `marketSampleSize` (type: `string`):

Number of comparable vehicles in the benchmark (with Fetch ad details)

## `searchTerm` (type: `string`):

Query/URL used

## `scrapedAt` (type: `string`):

Extraction timestamp

# 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 = {
    "searchQueries": [
        "iphone"
    ],
    "maxItemsPerSearch": 100,
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ],
        "apifyProxyCountry": "BR"
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("haketa/olx-brasil-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 = {
    "searchQueries": ["iphone"],
    "maxItemsPerSearch": 100,
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
        "apifyProxyCountry": "BR",
    },
}

# Run the Actor and wait for it to finish
run = client.actor("haketa/olx-brasil-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 '{
  "searchQueries": [
    "iphone"
  ],
  "maxItemsPerSearch": 100,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ],
    "apifyProxyCountry": "BR"
  }
}' |
apify call haketa/olx-brasil-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,haketa/olx-brasil-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/i0EDHVSccRLRY5vJH/builds/2zlyfUzCWPIlHh3te/openapi.json