# OLX Brasil Scraper (`dadhalfdev/olx-brasil-scraper`) Actor

Scrape cars, real estate, phones, and other ads from olx.com.br. Use the same listing filters as the site or paste an OLX URL — the URL wins when set.

- **URL**: https://apify.com/dadhalfdev/olx-brasil-scraper.md
- **Developed by:** [Marco Rodrigues](https://apify.com/dadhalfdev) (community)
- **Categories:**
- **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $2.00 / 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?

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

## 🇧🇷 OLX Brasil Scraper

Want [OLX Brasil](https://www.olx.com.br/) ads in a spreadsheet? This scraper makes it easy.

This actor covers the **marketplace**, not just cars: vehicles, real estate, phones, electronics, services, jobs, and other live listing pages.

Use **structured filters** — the same ones as the OLX listing; structured filters work better for AI agents — **or** paste an **`input_url`** once you've already filtered in the browser. When `input_url` is set it overrides the filters below.

OLX lists millions of ads. This actor reads the public listing payload and returns up to 2000 rows per run.

### 💡 Perfect for...

- **Agents:** Export Toyota automatics, 2-bed apartments in SP, or iPhones without paging the site.
- **Dashboards:** Track price, city, and category across OLX.
- **Market research:** Slice cars, motos, real estate, phones, and other verticals.
- **Data analysts:** Export structured OLX rows with public ad URLs.
- **🤖 AI Agents:** Power Claude, Cursor, Codex, the Hermes Agent, and OpenClaw workflows with live OLX results.
- **📚 RAG Systems:** Feed titles, specs, and locations into retrieval pipelines.
- **🔗 AI Workflows:** Plug into LangChain, AutoGPT, CrewAI, and similar stacks.

### ✨ Why you'll love this scraper

- 🔗 **Input URL or Filters:** Paste `/celulares/apple`, `/imoveis/venda/apartamentos`, or `/autos-e-pecas/motos/honda` (`input_url`) if you already filtered in the browser, or use dropdowns (better for AI agents). `input_url` always wins when set.
- 🎯 **Website-Matched Filters:** Category plus the live listing filters for that page — cars (marca, câmbio, combustível, …), motos (tipo, ano, km), real estate (quartos, banheiros, área, IPTU), and phones (marca, condição).
- 🌐 **Nationwide:** All 27 UF slugs as a suffix (`/toyota/estado-sp`, `/celulares/apple/estado-sp`). Prefer `www.olx.com.br/.../estado-sp` over city subdomains.

### 📦 What's inside the data?

Every row includes listing fields from the public payload:

- **Core:** `id`, `url`, `title`, `category`, `price`, `old_price`, `currency` (BRL), `price_reduction`, `installments`
- **Vehicles:** `make`, `model`, `year`, `mileage_km`, `body_type`, `engine`, `fuel`, `transmission`, `steering`, `color`, `doors`, `plate_end`, `features`
- **Phones / electronics:** `brand`, `condition`, `storage`
- **Real estate:** `rooms`, `bathrooms`, `garage_spaces`, `area_sqm`, `condo_fee`, `property_type`
- **Condition / docs:** `single_owner`, `accepts_trade`, `gnv_kit`, `financial_status`, `documentation`, `conservation`, `festival`
- **Place / seller:** `location`, `city`, `neighbourhood`, `state`, `ddd`, `professional_ad`, `seller`, `seller_rating`
- **Flags / media:** `featured`, `inspected`, `vehicle_history`, `published_at`, `image_url`, `image_count`
- **Catch-all:** `attributes` — every name/value pair from the listing payload, so category-specific fields are never dropped

### 🚀 Quick start

**Option A — Input URL**

1. Open [OLX](https://www.olx.com.br/), apply filters, copy the URL — e.g. `https://www.olx.com.br/celulares/apple` or `https://www.olx.com.br/imoveis/venda/apartamentos`.
2. Paste it into `input_url`.
3. Set `max_results` and click **Start**.

**Option B — Structured filters (better for AI agents)**

1. Leave `input_url` empty.
2. Pick a category, then the filters that apply to that page.
3. Set `max_results` (up to 2000) and click **Start**.

***

#### Tech details for developers 🧑‍💻

**Input Example (cars):**

```json
{
  "category": "carros",
  "make": "toyota",
  "transmission": "automatico",
  "year_min": 2018,
  "state": "sp",
  "max_results": 100
}
```

**Input Example (apartments):**

```json
{
  "category": "imoveis-venda-apartamentos",
  "state": "sp",
  "rooms": "2",
  "price_max": 500000,
  "max_results": 100
}
```

**Input Example (phones):**

```json
{
  "category": "celulares",
  "phone_brand": "apple",
  "phone_condition": "usado-excelente",
  "max_results": 50
}
```

**Input Example (URL override):**

```json
{
  "input_url": "https://www.olx.com.br/autos-e-pecas/motos/honda",
  "max_results": 50
}
```

**Output Example:**

```json
{
  "id": "1527847223",
  "url": "https://pi.olx.com.br/regiao-de-teresina-e-parnaiba/autos-e-pecas/carros-vans-e-utilitarios/toyota-hilux-sw4-srx-plat-4x4-2-8-tb-die-aut-2024-1527847223",
  "title": "Toyota Hilux SW4 SRX Plat. 4X4 2.8 TB Die. Aut. 2024",
  "category": "Carros, vans e utilitários",
  "price": 349900,
  "currency": "BRL",
  "make": "Toyota",
  "year": 2024,
  "mileage_km": 30000,
  "fuel": "Diesel",
  "transmission": "Automático",
  "city": "Teresina",
  "state": "PI"
}
```

**Output fields:**

| Field | Description |
|-------|-------------|
| `id` | OLX listing id. |
| `url` | Public ad page. |
| `title` | Ad title. |
| `category` | Category label from the card. |
| `price` | Asking price when shown. |
| `old_price` | Previous price when OLX shows a drop. |
| `currency` | Always `BRL`. |
| `make` | Vehicle or electronics brand when shown. |
| `model` | Vehicle or electronics model when shown. |
| `year` | Vehicle year when shown. |
| `mileage_km` | Odometer in kilometres when shown. |
| `fuel` | Fuel type for cars. |
| `transmission` | Gearbox for cars. |
| `rooms` | Bedroom count for property ads. |
| `bathrooms` | Bathroom count for property ads. |
| `area_sqm` | Floor area for property ads. |
| `city` | City. |
| `state` | State abbreviation. |
| `neighbourhood` | Neighbourhood when shown. |
| `seller` | Seller name when shown. |
| `featured` | Whether OLX marked the ad as featured. |
| `published_at` | Published time. |
| `image_url` | First photo. |
| `image_count` | Number of photos. |

Category-specific extras (condition, storage, garage, financing, inspection, and similar) appear when that ad type has them.

### 📋 Input reference (detailed)

#### Common

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `input_url` | string | No | — | Any OLX listing URL; overrides filters when set. |
| `category` | string enum | No | `carros` | Live listing category (cars, motos, apartments, phones, jobs, …). |
| `query` | string | No | — | Search box (`?q=`). |
| `subcategory` | string | No | — | Extra path after the category (`apple`, `honda`). |
| `state` | string enum | No | all | All 27 UF slugs (`sp`, `rj`, …). |
| `price_min` / `price_max` | integer | No | — | `ps=` / `pe=` (BRL). |
| `advertiser` | string enum | No | any | `particular`, `profissional`. |
| `sort` | string enum | No | `relevance` | `relevance`, `date`, `price`, `biggest_price`. |
| `max_results` | integer | No | `50` | Maximum rows (`1`–`2000`). |

#### Cars and motos

| Parameter | Type | Description |
|-----------|------|-------------|
| `make` | string enum | Cars path slug, or `/motos/{make}`. |
| `model` / `version` | string | Modelo / versão. |
| `year_min` / `year_max` | integer | Ano (`rs=` / `re=`). |
| `mileage_min` / `mileage_max` | integer | Quilometragem. |
| `color` | string enum | Cor. |
| `accepts_trade` | string enum | Aceita trocas. |
| `financial_status` / `documentation` | string enum | Quitado/financiado, IPVA, leilão. |
| `inspected` / `below_fipe` | boolean | Vistoriado / abaixo da FIPE. |
| `transmission`, `fuel`, `body_type`, `doors`, `steering`, `engine`, `feature`, `gnv_kit`, `conservation`, `plate_end`, `festival`, `vehicle_history` | cars only | Same filters as the cars listing. |
| `moto_type` | string enum | Street, esportiva, custom, trail, … |

#### Real estate

| Parameter | Type | Description |
|-----------|------|-------------|
| `rooms` / `bathrooms` / `garage_spaces` | string enum | `0`–`5` (`5` = 5+). |
| `property_subtype` | string enum | Cobertura, kitnet, loft, … |
| `area_min` / `area_max` | integer | Área in m². |
| `iptu_min` / `iptu_max` | integer | IPTU in BRL. |
| `moving_festival` | boolean | Festival da Mudança. |

#### Phones

| Parameter | Type | Description |
|-----------|------|-------------|
| `phone_brand` | string enum | `/celulares/{brand}` (`apple`, `samsung`, …). |
| `phone_condition` | string enum | Novo, usado, recondicionado, … |
| `donate` | boolean | Para doação. |

#### Notes on filters

- Prefer exact enum strings from the Apify input dropdowns.
- `input_url` always wins over filters when provided.
- Chevrolet is `gm-chevrolet` and Volkswagen is `vw-volkswagen`.
- Hub pages such as `/imoveis` or `/servicos` do not list ads — pick a leaf category or paste a leaf `input_url`.
- State is appended as `/estado-{uf}` after the category path (not as a prefix).
- `www.olx.com.br`, `olx.com.br`, and UF hosts such as `sp.olx.com.br` are accepted.

# Actor input Schema

## `input_url` (type: `string`):

Paste any OLX listing URL (cars, motos, apartments, phones, …). Overrides filters when set.

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

Same listing category as olx.com.br. Ignored when input\_url is set.

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

Same as the OLX search box (`?q=`). Ignored when input\_url is set.

## `subcategory` (type: `string`):

Optional extra path after the category, same as OLX (apple, honda, corolla). Ignored when input\_url is set.

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

Same /estado-{uf}/ listing prefix as OLX Brasil. Ignored when input\_url is set.

## `price_min` (type: `integer`):

Same Preço Min. (`ps=`). Ignored when input\_url is set.

## `price_max` (type: `integer`):

Same Preço Máx. (`pe=`). Ignored when input\_url is set.

## `advertiser` (type: `string`):

Same Tipo de anunciante filter (`f=`). Ignored when input\_url is set.

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

Same Ordenar por filter (`sf=`). Ignored when input\_url is set.

## `make` (type: `string`):

Cars path slug (`toyota`, `gm-chevrolet`). For motos, used as /motos/{make}. Ignored when input\_url is set.

## `model` (type: `string`):

Cars path after make, or motos `vm=`. Ignored when input\_url is set.

## `version` (type: `string`):

Same Versão filter (`vv=`). Cars and motos. Ignored when input\_url is set.

## `year_min` (type: `integer`):

Same Ano (`rs=`). Cars and motos. Ignored when input\_url is set.

## `year_max` (type: `integer`):

Same Ano (`re=`). Cars and motos. Ignored when input\_url is set.

## `mileage_min` (type: `integer`):

Same Quilometragem (`ms=`). Cars and motos. Ignored when input\_url is set.

## `mileage_max` (type: `integer`):

Same Quilometragem (`me=`). Cars and motos. Ignored when input\_url is set.

## `transmission` (type: `string`):

Same Câmbio filter (`gb=`). Cars only. Ignored when input\_url is set.

## `fuel` (type: `string`):

Same Combustível filter (`fu=`). Cars only. Ignored when input\_url is set.

## `body_type` (type: `string`):

Same Tipo filter (`ctp=`). Cars only. Ignored when input\_url is set.

## `color` (type: `string`):

Same Cor filter (`cac=`). Cars and motos. Ignored when input\_url is set.

## `doors` (type: `string`):

Same Portas filter (`cad=`). Cars only. Ignored when input\_url is set.

## `steering` (type: `string`):

Same Direção filter (`ics=`). Cars only. Ignored when input\_url is set.

## `engine` (type: `string`):

Same Motor filter (`motp=`). Cars only. Ignored when input\_url is set.

## `accepts_trade` (type: `string`):

Same Aceita Trocas filter (`exc=`). Ignored when input\_url is set.

## `feature` (type: `string`):

Same Opcionais filter (`cf=`). Cars only. Ignored when input\_url is set.

## `gnv_kit` (type: `string`):

Same Kit GNV filter (`hgnv=`). Cars only. Ignored when input\_url is set.

## `financial_status` (type: `string`):

Same Estado financeiro filter (`fncs=`). Cars and motos. Ignored when input\_url is set.

## `documentation` (type: `string`):

Same Documentação e regularização filter (`doc=`). Cars and motos. Ignored when input\_url is set.

## `conservation` (type: `string`):

Same Conservação e garantia filter (`cnwa=`). Cars only. Ignored when input\_url is set.

## `plate_end` (type: `string`):

Same Final de placa filter (`et=`). Cars only. Ignored when input\_url is set.

## `moto_type` (type: `string`):

Same Tipo de moto filter (`mt=`). Motos only. Ignored when input\_url is set.

## `festival` (type: `boolean`):

Same Festival de Carros toggle (`vt=1`). Cars only. Ignored when input\_url is set.

## `vehicle_history` (type: `boolean`):

Same Histórico Veicular toggle (`vtvh=`). Cars only. Ignored when input\_url is set.

## `inspected` (type: `boolean`):

Same Vistoriado toggle (`crss=`). Cars and motos. Ignored when input\_url is set.

## `below_fipe` (type: `boolean`):

Same Ofertas abaixo da FIPE toggle (`fpdll=`). Cars and motos. Ignored when input\_url is set.

## `rooms` (type: `string`):

Same Número de quartos (`ros=`). Real estate only. Ignored when input\_url is set.

## `bathrooms` (type: `string`):

Same Número de banheiros (`bas=`). Real estate only. Ignored when input\_url is set.

## `garage_spaces` (type: `string`):

Same Vagas na garagem (`gsp=`). Real estate only. Ignored when input\_url is set.

## `property_subtype` (type: `string`):

Same Subtipo do imóvel (`rts=`). Real estate only. Ignored when input\_url is set.

## `area_min` (type: `integer`):

Same Área (`ss=`). Real estate only. Ignored when input\_url is set.

## `area_max` (type: `integer`):

Same Área (`se=`). Real estate only. Ignored when input\_url is set.

## `iptu_min` (type: `integer`):

Same IPTU (`ips=`). Real estate only. Ignored when input\_url is set.

## `iptu_max` (type: `integer`):

Same IPTU (`ipe=`). Real estate only. Ignored when input\_url is set.

## `moving_festival` (type: `boolean`):

Same Festival da Mudança toggle (`fma=1`). Real estate only. Ignored when input\_url is set.

## `phone_brand` (type: `string`):

Same /celulares/{brand} path (apple, samsung, …). Phones only. Ignored when input\_url is set.

## `phone_condition` (type: `string`):

Same Condição filter (`elcd=`). Phones only. Ignored when input\_url is set.

## `donate` (type: `boolean`):

Same Para Doação toggle (`de=1`). Phones only. Ignored when input\_url is set.

## `max_results` (type: `integer`):

How many rows to return (1–2000). OLX lists 50 ads per page and stops around page 100.

## Actor input object example

```json
{
  "category": "carros",
  "state": "",
  "advertiser": "",
  "sort": "relevance",
  "make": "",
  "transmission": "",
  "fuel": "",
  "body_type": "",
  "color": "",
  "doors": "",
  "steering": "",
  "engine": "",
  "accepts_trade": "",
  "feature": "",
  "gnv_kit": "",
  "financial_status": "",
  "documentation": "",
  "conservation": "",
  "plate_end": "",
  "moto_type": "",
  "festival": false,
  "vehicle_history": false,
  "inspected": false,
  "below_fipe": false,
  "rooms": "",
  "bathrooms": "",
  "garage_spaces": "",
  "property_subtype": "",
  "moving_festival": false,
  "phone_brand": "",
  "phone_condition": "",
  "donate": false,
  "max_results": 50
}
```

# Actor output Schema

## `overview` (type: `string`):

Table view of scraped ads using the dataset overview view.

## `results` (type: `string`):

All scraped ads from the default dataset without view transformation.

# 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("dadhalfdev/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 = {}

# Run the Actor and wait for it to finish
run = client.actor("dadhalfdev/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 '{}' |
apify call dadhalfdev/olx-brasil-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,dadhalfdev/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/0aZ5HqtFr2vxZ1pzy/builds/IyxUx1SgmEGoGe18J/openapi.json