# OLX Brazil Classifieds Scraper (`automation-lab/olx-brazil-classifieds-scraper`) Actor

Extract public OLX Brazil listings by keyword, state, category, search URL, or listing URL with prices, locations, images, attributes, and seller signals.

- **URL**: https://apify.com/automation-lab/olx-brazil-classifieds-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

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/platform/actors/running/actors-in-store#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 Brazil Classifieds Scraper

Collect structured public listings from **OLX Brasil (`olx.com.br`)** by keyword, Brazilian state, category path, search URL, or individual listing URL.

The Actor returns listing IDs and URLs, titles, current and old BRL prices, publication data, category, city, neighbourhood, state, images, attributes, professional-seller signals, and OLX Pay and delivery flags.

It is designed for recurring inventory monitoring without an OLX login. Search pages are processed from server-rendered structured data through Brazilian residential sessions. A full browser is not started for each page.

### What can you do with this OLX Brazil scraper?

Use the Actor to:

- monitor fresh classified inventory in one or more Brazilian states;
- compare prices for phones, cars, property, equipment, and other categories;
- identify ads with price reductions;
- build sourcing lists for resale and procurement teams;
- collect city and neighbourhood coverage for local market analysis;
- find professional ads and public seller signals;
- track OLX Pay, delivery, installment, and chat availability;
- fetch an individual listing URL with its public description and full images;
- export results to JSON, CSV, Excel, APIs, webhooks, or automation tools.

Each result is deduplicated by its stable OLX listing ID.

### Who is it for?

#### Resale sourcing teams

Refresh searches for in-demand products and send new inventory into a review queue.

#### Dealers and marketplace analysts

Compare price, location, attributes, seller type, and promotion signals across regions.

#### Automotive and property teams

Collect repeated state and category snapshots for local inventory and asking-price analysis.

#### Lead generation teams

Build responsible prospecting workflows from public professional ads and supported seller signals.

#### Data and automation teams

Feed normalized records into a warehouse, spreadsheet, webhook, Make, Zapier, or an internal API.

### Why use this Actor?

OLX Brazil applies anti-bot controls to ordinary HTTP traffic. This Actor uses browser-grade Chrome TLS impersonation with Brazilian residential geography while keeping extraction HTTP-first.

That architecture provides:

- useful structured SSR records without rendering every page in a browser;
- conservative retry and session rotation on transient challenges;
- stable ID-based deduplication across searches and pages;
- one-request search extraction and one-request direct listing extraction;
- no automatic per-result detail fan-out;
- explicit errors for challenge pages instead of false empty success.

The Actor does not require OLX credentials, cookies, CAPTCHA solving, or a paid target API.

### Supported input routes

You can use one route or combine routes in one run.

1. **Keyword search** with `searchQueries`.
2. **State filtering** with two-letter UF codes in `states`.
3. **Category filtering** with `categoryPath`.
4. **Public OLX search/category/state URLs** with `startUrls`.
5. **Individual OLX listing URLs** with `startUrls`.

Generated searches combine every query with every selected state. Explicit URLs are processed in addition to generated searches.

Only public HTTPS URLs on `olx.com.br` or its subdomains are accepted.

### Input parameters

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `searchQueries` | `string[]` | `["iphone"]` | Keywords to search. Up to 20. |
| `states` | `string[]` | `["SP"]` | Optional Brazilian UF codes such as `SP`, `RJ`, or `MG`. |
| `categoryPath` | `string` | empty | OLX path without domain or query string, for example `celulares`. |
| `startUrls` | URL array | empty | OLX Brazil search, state, category, or listing URLs. |
| `maxItems` | integer | `50` | Maximum unique listings across all inputs, from 1 to 5,000. |
| `maxPages` | integer | `20` | Pagination safety limit per search, from 1 to 100. |
| `maxRequestRetries` | integer | `2` | Fresh-session retries for transient network, server, rate-limit, or challenge failures. |

At least one query, state, category path, or start URL must remain after input validation.

### Getting started

1. Open the Actor input page.
2. Enter one or more real search terms.
3. Choose Brazilian state codes, or clear `states` for nationwide results.
4. Optionally enter an OLX category path.
5. Set `maxItems` to the amount of inventory you need.
6. Start the run.
7. Open the **Results** dataset view.
8. Download or integrate the dataset.
9. Use an individual listing URL in a separate run when its description is needed.

A practical first input is:

```json
{
  "searchQueries": ["iphone"],
  "states": ["SP"],
  "maxItems": 50,
  "maxPages": 2
}
```

### Output fields

| Field | Meaning |
| --- | --- |
| `listingId` | Stable OLX listing ID used for deduplication. |
| `url` | Canonical public listing URL. |
| `title` | Listing title. |
| `description` | Public description for direct listing URLs; search records normally return `null`. |
| `price`, `priceText` | Numeric and displayed current BRL price. |
| `oldPrice`, `oldPriceText` | Previous price when exposed. |
| `postedAt` | Publication timestamp exposed by OLX. |
| `lastBumpAgeSeconds` | Age of the latest listing bump at scrape time. |
| `category`, category IDs | Human-readable and source category values. |
| `city`, `neighbourhood`, `state`, `areaCode` | Structured Brazilian location data. |
| `imageUrls`, `imageCount`, `videoCount` | Public media metadata. |
| `attributes` | Category-specific values such as brand, model, condition, or storage. |
| `professionalAd` | Whether OLX labels the ad as professional. |
| `sellerName`, `sellerRating` | Public transactional seller signals when exposed. |
| `olxPayEnabled`, `deliveryEnabled` | Payment and delivery availability. |
| `installmentsAvailable`, `chatEnabled` | Transaction and contact flags. |
| promotion/report flags | Featured, fixed-on-top, price reduction, and vehicle-report signals. |
| `sourceUrl`, `page`, `scrapedAt` | Extraction provenance. |

Source fields may be `null` when OLX does not expose them for a listing type.

### Output example

This shape is based on a current public search result; identifying seller text is generalized here.

```json
{
  "listingId": "1510471346",
  "url": "https://sp.olx.com.br/grande-campinas/celulares/apple-iphone-12-128gb-branco-impecavel-1510471346",
  "title": "Apple iPhone 12 128gb Branco Impecável",
  "description": null,
  "price": 1300,
  "priceText": "R$ 1.300",
  "oldPrice": 1400,
  "oldPriceText": "R$ 1.400",
  "currency": "BRL",
  "postedAt": "2026-07-27T01:02:57.000Z",
  "category": "Celulares e Smartphones",
  "city": "Campinas",
  "neighbourhood": "Alphaville Dom Pedro 2",
  "state": "SP",
  "imageCount": 5,
  "attributes": {
    "electronics_brand": "APPLE",
    "electronics_model": "IPHONE 12",
    "cellphone_storage": "128GB"
  },
  "professionalAd": false,
  "sellerName": "Example Seller",
  "sellerRating": 5,
  "olxPayEnabled": true,
  "deliveryEnabled": true,
  "installmentsAvailable": true,
  "chatEnabled": true,
  "sourceUrl": "https://www.olx.com.br/estado-sp?q=iphone",
  "page": 1,
  "scrapedAt": "2026-07-28T05:17:39.943Z"
}
```

### How much does it cost to scrape OLX Brazil listings?

The Actor uses pay-per-event pricing:

- **Actor start:** $0.00115 per run.
- **Item extracted:** $0.00094276 per unique dataset listing on the FREE tier, with lower per-item prices on higher platform tiers.

Search records and direct listing records use the same item event. The Actor does not automatically fetch every discovered listing page.

FREE-tier examples using active event prices:

| Workflow | Event calculation |
| --- | --- |
| 50 search listings | One $0.00115 start event plus 50 × $0.00094276 item events |
| 1,000 search listings | One $0.00115 start event plus 1,000 × $0.00094276 item events |
| One direct listing detail | One $0.00115 start event plus one $0.00094276 item event |
| 100 search listings | One $0.00115 start event plus 100 × $0.00094276 item events |

Your platform tier and the number of saved listings affect the final charge. Compute, storage, and Brazilian residential proxy costs are covered by these Actor events rather than billed as a separate Actor event.

### Search records versus direct listing details

Search mode already returns the fields needed for many inventory and price workflows:

- title and canonical URL;
- current and old price;
- location and category;
- images and attributes;
- seller/professional signals;
- OLX Pay, delivery, installment, chat, and promotion flags.

Search inputs return broad inventory efficiently from OLX's structured result payload. They do not fan out into one request per discovered listing.

When a public description is important, provide that individual listing URL in `startUrls`. The Actor fetches the listing detail directly.

Each saved record uses one extracted-item charge event.

### Pagination, limits, and deduplication

The Actor paginates each search with OLX's public page parameter.

It stops when:

- `maxItems` unique results have been saved;
- `maxPages` is reached;
- OLX returns an empty result payload;
- the source is exhausted.

Duplicate listings across terms, states, URLs, and pages are saved once per run by `listingId`.

`maxItems` is a run-wide limit, not a per-query limit.

### Reliability and failure behavior

The Actor validates status, HTML shape, challenge signatures, and embedded data.

Transient network failures, 429 responses, server errors, and challenge responses are retried with bounded exponential backoff and a fresh Brazilian residential session.

The run fails clearly when:

- an input URL is outside OLX Brazil;
- a state code is invalid;
- no usable input is provided;
- all retries are exhausted;
- a search page lacks the expected structured payload;
- a direct listing URL lacks a recognizable public Product record.

### Integration workflow ideas

#### Daily resale sourcing

Schedule a keyword/state input, compare `listingId` values with the previous run, and send new items to Slack or email.

#### Price intelligence

Load `price`, `oldPrice`, category attributes, and location into a warehouse. Group by model, city, and condition.

#### Dealer inventory monitoring

Run several vehicle searches across states, then enable details only for shortlisted records.

#### Property market snapshots

Use category/state URLs on a schedule and track asking-price and neighbourhood coverage over time.

#### Spreadsheet review

Export the default dataset to CSV or Excel and filter by seller type, OLX Pay, delivery, or price reduction.

### Run through the Apify API

Replace `APIFY_TOKEN` with your token.

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~olx-brazil-classifieds-scraper/runs?token=APIFY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"searchQueries":["iphone"],"states":["SP"],"maxItems":50}'
```

#### JavaScript

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

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/olx-brazil-classifieds-scraper').call({
    searchQueries: ['Toyota Corolla'],
    states: ['SP', 'RJ'],
    maxItems: 100,
});

const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient
import os

client = ApifyClient(os.environ["APIFY_TOKEN"])
run = client.actor("automation-lab/olx-brazil-classifieds-scraper").call(run_input={
    "searchQueries": ["apartamento"],
    "states": ["RJ"],
    "maxItems": 100,
})

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

### Use with Apify MCP

Add the Actor to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/olx-brazil-classifieds-scraper"
```

#### Claude Desktop

Use this equivalent JSON configuration in Claude Desktop:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/olx-brazil-classifieds-scraper"
    }
  }
}
```

#### Cursor

Add the same `mcpServers.apify.url` value to Cursor's MCP settings.

#### VS Code

Add the same HTTP endpoint to your VS Code MCP server configuration.

Example prompts:

- “Find 50 current iPhone listings on OLX Brazil in São Paulo.”
- “Collect Toyota Corolla listings in SP, RJ, and MG across three pages.”
- “Fetch this OLX Brazil listing URL and return its public description and images.”
- “Export Rio property ads and summarize median asking price by neighbourhood.”

### Tips for efficient runs

- Start with one state and a moderate `maxItems` while refining a query.
- Use exact category paths when you need narrower inventory.
- Prefer several scheduled focused runs over one very broad multi-state run.
- Use `listingId` as the durable key in downstream systems.
- Store `scrapedAt` with snapshots so price and availability changes remain interpretable.
- Increase retries only when transient challenges justify the extra delay.

### Limitations

- OLX may change its public SSR or JSON-LD structures.
- Public fields vary by category and seller, so nullable values are expected.
- Search ordering and inventory can change between requests.
- The Actor does not log in, send messages, reveal private contact data, or bypass a CAPTCHA with human solving.
- It does not guarantee that a listing remains active after collection.
- It does not determine fair market value or verify seller claims.
- A naturally empty search returns zero records successfully; a challenge shape fails instead.

### Responsible use and legality

Only collect public data you have a lawful reason to process.

You are responsible for complying with OLX terms, applicable privacy and database rules, consumer-protection law, and restrictions on marketing or automated outreach.

Do not use the Actor to harass sellers, create spam, discriminate, infer sensitive traits, republish copyrighted content without permission, or overwhelm the source.

Minimize stored personal data, apply retention controls, and respect deletion or opt-out requests in downstream systems.

### Frequently asked questions

#### Does it require an OLX login?

No. It processes anonymous public search and listing surfaces.

#### Why are some fields null?

OLX exposes different fields by category, listing type, and seller. Descriptions are normally null in search-only mode.

#### Why did my run return zero records?

First verify the same query/state/category on the public OLX site. A genuine empty structured payload is treated as an empty result. A challenge or parser failure produces an error instead.

#### Why is the description null on search results?

OLX search payloads do not include the full public description. Submit an individual listing URL when you need that field.

#### Can I provide an individual listing URL?

Yes. Put a public OLX Brazil listing URL in `startUrls`. The Actor returns one detail-backed record when the listing remains public.

#### Can I search several states?

Yes. Every query is combined with every state code. The run-wide `maxItems` limit still applies.

#### Does it download images?

No. It returns public image URLs and counts, avoiding unnecessary media transfer and storage.

### Related Actors

Build country-specific classified-market workflows with other automation-lab Actors:

- [OLX Poland Classifieds Scraper](https://apify.com/automation-lab/olx-poland-classifieds-scraper)
- [OLX Portugal Classifieds Scraper](https://apify.com/automation-lab/olx-portugal-classifieds-scraper)
- [OLX Romania Classifieds Scraper](https://apify.com/automation-lab/olx-romania-classifieds-scraper)
- [OLX Ukraine Classifieds Scraper](https://apify.com/automation-lab/olx-ukraine-classifieds-scraper)

These are separate country inventories with different public surfaces and locale-specific extraction paths.

# Actor input Schema

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

Keywords to search on OLX Brazil. Each query is combined with each selected state.

## `states` (type: `array`):

Optional two-letter UF codes, for example SP, RJ, or MG. Leave empty to search nationwide.

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

Optional OLX URL category path without leading slash, query parameters, or domain, for example celulares.

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

Optional public olx.com.br search, category, state, or individual listing URLs. Explicit URLs are processed in addition to generated searches.

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

Stop after saving this many unique listings across all inputs.

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

Safety limit for search pagination. Individual listing URLs use one request.

## `maxRequestRetries` (type: `integer`):

Retries for transient blocks, rate limits, server failures, and network errors. Each retry uses a fresh Brazilian residential session.

## Actor input object example

```json
{
  "searchQueries": [
    "iphone"
  ],
  "states": [
    "SP"
  ],
  "categoryPath": "",
  "startUrls": [
    {
      "url": "https://www.olx.com.br/estado-sp?q=iphone"
    }
  ],
  "maxItems": 20,
  "maxPages": 20,
  "maxRequestRetries": 2
}
```

# Actor output Schema

## `dataset` (type: `string`):

Default dataset containing all scraped OLX Brazil listing records.

# 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"
    ],
    "states": [
        "SP"
    ],
    "categoryPath": "",
    "startUrls": [
        {
            "url": "https://www.olx.com.br/estado-sp?q=iphone"
        }
    ],
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/olx-brazil-classifieds-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"],
    "states": ["SP"],
    "categoryPath": "",
    "startUrls": [{ "url": "https://www.olx.com.br/estado-sp?q=iphone" }],
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/olx-brazil-classifieds-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).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"
  ],
  "states": [
    "SP"
  ],
  "categoryPath": "",
  "startUrls": [
    {
      "url": "https://www.olx.com.br/estado-sp?q=iphone"
    }
  ],
  "maxItems": 20
}' |
apify call automation-lab/olx-brazil-classifieds-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/olx-brazil-classifieds-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/s7oeAlKmBPrcwX13P/builds/j7rwOWgr78xW38ym9/openapi.json