# OLX Brazil Scraper — Any Category, Any Keyword (`reventadata/olx-scraper`) Actor

Searches any category on olx.com.br - real estate, cars, electronics, anything - and returns priced listings with structured attributes (area, bedrooms, mileage, color, engine) parsed from the site's own detail chips. No seller identity is ever collected.

- **URL**: https://apify.com/reventadata/olx-scraper.md
- **Developed by:** [reventadata](https://apify.com/reventadata) (community)
- **Categories:** E-commerce, Real estate, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

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

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

> **Unofficial.** This Actor is not affiliated with, authorised by, endorsed by, or in any
> way officially connected to OLX. "OLX" is a trademark of its respective owner and is used
> here only to describe what this tool reads. It reads the same public pages a browser does.

OLX Brazil Scraper searches **any category** on [olx.com.br](https://www.olx.com.br) — real
estate, cars, electronics, anything the site lists — and returns priced listings with the
structured attributes OLX itself publishes on the search card (area, bedrooms, bathrooms,
mileage, color, engine size), plus a raw catch-all for any category-specific attribute this
Actor's recon pass did not name.

### What data can you extract from OLX Brazil (olx.com.br)?

olx.com.br is a Next.js App Router site with no clean embedded JSON on its search-results
page, so this Actor reads the rendered HTML tiles directly, the same way a browser paints
them. You point it at any OLX BR category path — copied straight from the site's own address
bar — with an optional keyword to narrow inside it, and it walks pages until the results run
out, the 100-page site ceiling is hit, or your row cap is reached.

### Why scrape OLX Brazil (olx.com.br)?

- **Truly generic — one Actor, any category.** `categoryPath` is free text: paste in
  `imoveis`, `autos-e-pecas/carros-vans-e-utilitarios`, a specific city/UF path, or a category
  this Actor was never specifically tested against. Chips it doesn't recognise are still
  returned raw in `attributes`, not dropped.
- **No category enum to fall out of date.** OLX BR's full slug list was never independently
  enumerated (a lot of it is regional and dynamic); a free-text path avoids inventing one and
  breaking when the site adds a category.
- **Real estate and autos get typed fields.** `areaM2`/`bedrooms`/`bathrooms`/`parkingSpaces`
  for imóveis, `mileageKm`/`color`/`engineSize`/`bodyType` for autos, parsed from the site's
  own `aria-label` detail chips — not free-text mining, so there is nothing to hallucinate.
- **The phantom-results trap is handled.** A keyword with zero real matches still renders up
  to 8 unrelated "Mais recentes" fallback cards under the exact same markup as a genuine
  result. This Actor keys off the page's own "0 - 0 de 0 resultados" text, never off how many
  cards are on the page, so a bad search reports zero rows instead of eight wrong ones.
- **No seller identity, ever.** OLX BR's search tiles carry no seller name, phone, e-mail or
  profile link anywhere in the markup — that data exists only on individual listing pages,
  which this Actor never fetches. There is nothing to redact because nothing is collected.

### How to scrape OLX Brazil (olx.com.br)

1. Paste a category path from OLX BR's own address bar into `categoryPath` — or leave it
   empty to search all of olx.com.br nationwide.
2. Optionally add `searchQueries` to narrow inside that category, a price range, and (for
   autos) a mileage range or "accepts trade-ins" filter.
3. Run it. Results land in the dataset.

#### Input

| Field | Type | Meaning |
|---|---|---|
| `categoryPath` | string | OLX BR's own URL path segments — category, transaction type, location, and (autos) registration year all live here. E.g. `imoveis/aluguel/apartamentos/estado-df/distrito-federal-e-regiao/brasilia` or `autos-e-pecas/carros-vans-e-utilitarios/2019`. Empty = nationwide. |
| `searchQueries` | array | Optional keywords. Each narrows *within* `categoryPath` — confirmed not to replace it. Empty is a valid, fully generic "browse this category" run. |
| `sortBy` | string | `relevance` | `newest` | `priceAsc` | `priceDesc`. |
| `minPrice` / `maxPrice` | integer | Optional, in R$. Omitted from the request entirely when empty — never defaulted to 0. |
| `minMileageKm` / `maxMileageKm` | integer | Autos category only; confirmed genuinely bounded there. |
| `acceptsTradeOnly` | boolean | Autos category only ("Aceita trocas" badge). Confirmed genuinely filtered. |
| `requireKeywordMatch` | boolean | A defensive second pass after OLX's own `q` narrowing. Default on. |
| `maxItems` | integer | Hard cap on rows pushed. Default 300 (lowered from 1000 on 2026-08-22 — see below). |
| `maxPages` | integer | Clamped to OLX's own confirmed ceiling of 100. |
| `proxyConfiguration` | object | Apify Unblocker by default. olx.com.br blocks plain HTTP and the Apify datacenter/residential proxy groups outright. |

```json
{
    "categoryPath": "autos-e-pecas/carros-vans-e-utilitarios",
    "searchQueries": ["civic"],
    "minPrice": 60000,
    "maxPrice": 120000,
    "maxItems": 200
}
```

#### Output

```json
{
    "id": "1516661625",
    "title": "Honda Civic Sedan EXL 2019",
    "url": "https://sp.olx.com.br/sp/autos-e-pecas/honda-civic-sedan-exl-2019-1516661625",
    "imageUrl": "https://img.olx.com.br/thumbs700x500/99/991595642999302.webp",
    "price": 89900,
    "currency": "BRL",
    "location": "São Luís - MA",
    "postedAt": "Hoje, 15:30",
    "areaM2": null,
    "bedrooms": null,
    "bathrooms": null,
    "parkingSpaces": null,
    "mileageKm": 133,
    "color": "Vermelho",
    "engineSize": "1.3",
    "bodyType": "Sedã",
    "year": 2019,
    "acceptsTrade": true,
    "isSellerOnline": true,
    "attributes": [],
    "matchedKeyword": "civic"
}
```

For a real-estate search, `areaM2`/`bedrooms`/`bathrooms`/`parkingSpaces` are filled from the
site's own chips and the autos-only fields come back null. A land listing carries only
`areaM2`; the other property fields are `null`, never `0` — absence of a chip is not zero.

### Notes and limits

- **The default `maxItems` is 300, not 1000.** A category-less, keyword-less nationwide
  browse (this Actor's own daily auto-test input) measured 244s at 991 rows against
  Apify's 5-minute auto-test window — too little headroom. The same run at 300 rows
  finished in 50s. Raise `maxItems` explicitly if you need more and can accept a longer run.
- **Page 100 is a hard clamp.** Pages 101 through at least 1000 serve byte-identical content
  to page 100 — confirmed by comparing the first AND last listing on each. At 50 rows/page
  that is roughly 5,000 listings per distinct filter combination. Narrow with `categoryPath`
  or a price range to get past it, the same mitigation the Gumtree sibling recommends.
- **Only Apify Unblocker and Bright Data reach this site.** Plain HTTP, Apify datacenter and
  Apify residential all return the identical ~5.8 KB block page — measured 25/25 failures on
  two separate verticals. There is no "cheap, no-proxy" mode here.
- **`year` is a best-effort guess, not a published field.** OLX BR never puts registration
  year in a chip — it is read from the trailing token of the title, and only on tiles a real
  vehicle chip (mileage/color/engine/body type) already confirms as an auto, to avoid
  mistaking a real-estate street number for a year.
- **`attributes` is a catch-all.** Any detail chip that doesn't match one of the eight
  recognised patterns (area, bedrooms, bathrooms, parking, mileage, color, engine, body type)
  is kept here as raw text instead of being silently dropped — useful for a category this
  Actor's recon pass never specifically covered.
- **A run that returns zero rows fails rather than succeeding empty.** If every page came back
  empty or every row was filtered out, the Actor raises instead of writing an empty dataset,
  so a silent misconfiguration cannot look like "no stock today".
- **`minMileageKm`/`maxMileageKm`/`acceptsTradeOnly` were only verified on the autos
  category.** Setting them elsewhere is unlikely to error, but whether OLX BR honours them
  outside autos was not tested.
- **`categoryPath` is not validated against a slug list.** An invalid path segment was not
  confirmed to redirect anywhere (no Milanuncios-style silent-redirect trap was found in
  testing), but this Actor sets `follow_redirects=False` defensively regardless, so any
  redirect surfaces as a visible failure rather than silently returning an unfiltered page.
- Reads the same public page a browser does. See the disclaimer at the top.

### How much does it cost to scrape OLX Brazil (olx.com.br)?

Pricing is pay-per-event: **$0.001 per result** written to the dataset (**$1.00 per 1,000
results**), plus **$0.00005** charged once when the run starts. There is no subscription —
you pay only for what you get.

### FAQ

**Is a proxy required to scrape OLX Brazil?** Yes. Plain HTTP, Apify's datacenter proxy and
Apify's residential proxy all returned the identical block page — measured 25/25 failures
on two separate verticals. Only Apify Unblocker and Bright Data reach this site, and this
Actor defaults to Unblocker.

**Is seller identity collected?** No. OLX BR's search tiles carry no seller name, phone,
e-mail or profile link anywhere in the markup, and this Actor never fetches individual
listing pages.

**How many listings can one search return?** Up to page 100, roughly 5,000 listings per
distinct filter combination — OLX BR's own hard clamp. Pages beyond 100 re-serve page 100's
content rather than erroring.

### More second-hand marketplace scrapers

| Actor | What it scrapes |
|---|---|
| [Wallapop Scraper](https://apify.com/reventadata/wallapop-scraper) | Wallapop, Spain — any keyword, phone mode with battery-health parsing |
| [Wallapop + Vinted + Milanuncios Scraper — Spain](https://apify.com/reventadata/wallapop-vinted-milanuncios-scraper) | Wallapop, Vinted and Milanuncios in Spain — one keyword, one merged table |
| [Cash Converters Spain Scraper](https://apify.com/reventadata/cashconverters-scraper) | Cash Converters Spain — graded second-hand stock with price when new |
| [Milanuncios Scraper](https://apify.com/reventadata/milanuncios-scraper) | Milanuncios — 17 categories, condition, storage and battery-health filters |
| [Gumtree UK Scraper](https://apify.com/reventadata/gumtree-scraper) | Gumtree UK — any category, vehicle and phone details parsed from the ad's own text |
| [OLX Romania Scraper](https://apify.com/reventadata/olx-ro-scraper) | OLX Romania (olx.ro) — any keyword, no proxy required |
| [Vinted Spain Scraper](https://apify.com/reventadata/vinted-scraper) | Vinted Spain (vinted.es) — any keyword or category, no proxy required |
| [Todocolección Scraper](https://apify.com/reventadata/todocoleccion-scraper) | Todocolección — collectibles, antiques and auctions, fixed-price and bidding modelled apart |
| [Back Market Spain Scraper](https://apify.com/reventadata/backmarket-scraper) | Back Market Spain — refurbished phones, laptops and tablets, priced against new |
| [eBay Spain Scraper](https://apify.com/reventadata/ebay-scraper) | eBay Spain (ebay.es) — active listings with seller type |

# Actor input Schema

## `categoryPath` (type: `string`):

The URL path segment(s) OLX BR itself uses for a category, transaction type, location and (for autos) registration year - copy them straight from the site's address bar. Examples: "imoveis" (all real estate nationwide), "imoveis/aluguel/apartamentos/estado-df/distrito-federal-e-regiao/brasilia" (apartments for rent in Brasília), "autos-e-pecas/carros-vans-e-utilitarios" (all cars/vans), "autos-e-pecas/carros-vans-e-utilitarios/2019" (cars registered 2019). Leave empty to search all of olx.com.br nationwide.

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

Optional keywords. Each one narrows WITHIN the category path above - it does not replace it (confirmed: "autos-e-pecas/carros-vans-e-utilitarios" + q=civic returns only Civics, still inside the cars category). Leave empty to browse the category path unfiltered, which is a fully valid run on its own.

## `sortBy` (type: `string`):

Order only; changes nothing about which listings exist.

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

Optional. Omitted from the request entirely when empty - never defaulted to 0, which would drop every free listing.

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

Optional. Omitted from the request entirely when empty.

## `minMileageKm` (type: `integer`):

Autos category only. Verified genuinely bounded on the autos vertical; not confirmed whether other categories honour it at all (likely ignored there).

## `maxMileageKm` (type: `integer`):

Autos category only. Same caveat as the minimum.

## `acceptsTradeOnly` (type: `boolean`):

Autos category only ("Aceita trocas" badge). Verified genuinely filtered, not a silently-ignored parameter, on the autos vertical.

## `requireKeywordMatch` (type: `boolean`):

A defensive second pass after OLX's own `q` narrowing - drops a row whose title is missing a word of the search term. Has no effect when searchQueries is empty.

## `maxItems` (type: `integer`):

Hard cap on rows pushed across all search terms (or the single category browse, if searchQueries is empty). Default lowered to 300 (from 1000) on 2026-08-22 - a 1000-row nationwide browse measured 244s against Apify's 5-minute daily auto-test window, too little headroom; 300 rows measured well inside it.

## `maxPages` (type: `integer`):

olx.com.br clamps every search at page 100 (confirmed: pages 101 through at least 1000 serve byte-identical content to page 100), about 5,000 listings. This is clamped to that ceiling regardless of what is entered.

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

olx.com.br blocks plain HTTP, Apify datacenter and Apify residential proxies outright (identical ~5.8 KB block page in every case, measured 25/25). Only Apify Unblocker and Bright Data reach the site; Unblocker is the default and needs no vendor account.

## Actor input object example

```json
{
  "categoryPath": "",
  "searchQueries": [],
  "sortBy": "relevance",
  "acceptsTradeOnly": false,
  "requireKeywordMatch": true,
  "maxItems": 300,
  "maxPages": 100,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "UNBLOCKER"
    ]
  }
}
```

# Actor output Schema

## `matches` (type: `string`):

Matching listings: price, location, structured attributes, and a link to the ad.

# 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("reventadata/olx-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("reventadata/olx-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 reventadata/olx-scraper --silent --output-dataset

```

## MCP server setup

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