# OLX Brazil Scraper | Listings, Prices & Seller Data (`solidcode/olx-brazil-scraper`) Actor

\[💰 $1.0 / 1K] Scrape OLX Brazil listings at scale. Extract titles, prices, descriptions, photos, seller details, location, and category data from Brazil's largest classifieds marketplace by keyword or URL.

- **URL**: https://apify.com/solidcode/olx-brazil-scraper.md
- **Developed by:** [SolidCode](https://apify.com/solidcode) (community)
- **Categories:** Developer tools, E-commerce, Lead generation
- **Stats:** 167 total users, 53 monthly users, 100.0% runs succeeded, 4 bookmarks
- **User rating**: 5.00 out of 5 stars

## 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

## OLX Brazil Scraper

Pull classifieds from OLX Brazil at scale — every title, price in Brazilian Reais, photos, seller details, neighbourhood, CEP postal code, and listing timestamp from Brazil's largest classifieds marketplace. Built for real-estate aggregators, price-arbitrage resellers, lead-generation teams, and Brazilian-market analysts who need fresh OLX data without juggling regional subdomains or building their own pipeline.

### Why This Scraper?

- **All 27 Brazilian states, strict-validated** — every official UF code (AC through TO) is supported as a path-segment filter; invalid codes get an actionable error instead of silent all-Brazil results.
- **Four sort orders applied at the source** — Most Relevant, Newest First, Price: Low to High, and Price: High to Low — encoded into the OLX query itself so paging order is consistent.
- **Native min/max price filter in Brazilian Reais** — clamps results at OLX's own query layer; no wasted rows on out-of-budget ads.
- **Business-only toggle for B2B prospecting** — isolate professional sellers (lojas e profissionais) and exclude private individuals in one click.
- **Opt-in deep records: full description, seller name and CEP postal code** — the three fields OLX publishes only on a listing's own page. Off by default and priced separately, so browse-only runs never pay for them.
- **URL passthrough plus plain-text queries in one run** — paste any olx.com.br URL (search, category, or state path like `/imoveis/venda/estado-sp`) and mix it with keyword searches; results are combined and de-duplicated by listing ID.
- **High-fidelity records straight from OLX's own data layer** — every field matches what the OLX product page shows, with prices parsed to integers + currency code and timestamps emitted as ISO 8601 plus epoch seconds.
- **Up to 5,000 listings per search URL** — the actor walks OLX's paging ceiling, detects the server-side clamp, and surfaces a friendly "split by state or category" hint when you hit it.
- **Actionable zero-result hint** — when a filter combo returns nothing, the run reports the exact keyword, state, and price range you used so you can adjust without guessing.

### Use Cases

**Real Estate Market Research**

- Track apartment and house inventory across São Paulo, Rio de Janeiro, and Minas Gerais
- Compare median asking prices by state, city, and neighbourhood
- Spot new construction launches by sorting "Newest First"
- Map regional price compression by combining `imoveis` URLs across UF codes

**Property & Auto Lead Generation**

- Build prospect lists of business sellers (`includeBusinessOnly: true`) — auto dealerships, real-estate agencies, and electronics resellers
- Capture seller name and phone-availability flag for every active listing
- Target one state at a time with `state: "SP"` for regional sales teams

**Price Intelligence for Resale**

- Monitor iPhone, PlayStation, and laptop pricing in BRL across the country
- Identify under-priced listings with a tight `maxPrice` cap
- Compare private-seller vs. business-seller pricing on the same model

**Cross-Border Investment Scouting**

- Surface vacation rentals and second homes in Florianópolis, Búzios, or Trancoso
- Quantify entry prices for foreign buyers exploring the Brazilian market
- Track price-history shifts week-over-week by re-running the same URL

**Demand & Category Trend Tracking**

- Map listing volume by category across `imoveis`, `autos-e-pecas`, `eletronicos-e-celulares`, and more
- Detect seasonal spikes in regional categories (air conditioners in summer, heaters in winter)
- Feed time-series dashboards with `postedAt` ISO timestamps

**Data Enrichment & Aggregation**

- Augment internal CRMs with current OLX prices and photos
- Power classifieds aggregators that compete with OLX-only feeds
- Build alerting systems for new listings under a price threshold

### Getting Started

#### Search by URL

The simplest possible run — paste any olx.com.br URL with your filters already applied:

```json
{
    "searchUrls": ["https://www.olx.com.br/imoveis/venda/estado-sp"],
    "maxResults": 100
}
```

#### Plain-Text Search with State Filter

Run a keyword across one Brazilian state and sort by newest first:

```json
{
    "searchQueries": ["iPhone 13"],
    "state": "RJ",
    "sortBy": "newest",
    "maxResults": 200
}
```

#### Price-Filtered Business Listings

Find apartments under R$500,000 from business sellers only, sorted cheapest first:

```json
{
    "searchUrls": ["https://www.olx.com.br/imoveis/venda/estado-mg"],
    "minPrice": 100000,
    "maxPrice": 500000,
    "sortBy": "price_asc",
    "includeBusinessOnly": true,
    "maxResults": 500
}
```

#### Combined Multi-Source Run with Full Enrichment

Mix multiple URLs and keyword queries, pull descriptions, seller names, and CEPs:

```json
{
    "searchUrls": [
        "https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-sp",
        "https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-rj"
    ],
    "searchQueries": ["Honda Civic", "Toyota Corolla"],
    "state": "SP",
    "minPrice": 30000,
    "maxPrice": 80000,
    "sortBy": "price_asc",
    "enrichDetails": true,
    "maxResults": 1000
}
```

### Input Reference

#### What to Scrape

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `searchUrls` | string\[] | `["https://www.olx.com.br/imoveis/venda/estado-sp"]` | Paste one or more OLX Brazil URLs. Search pages, category pages, and state path URLs (`/imoveis/venda/estado-sp`) are all supported. |
| `searchQueries` | string\[] | `[]` | Plain-text search terms — for example `iPhone 13`, `Gol G5`, or `Apartamento`. Each query runs on OLX Brazil and returns matching listings. |

#### Options

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `maxResults` | integer | `100` | Maximum number of listings to collect across all URLs and queries. Set to `0` for unlimited (capped internally at 50,000). OLX itself limits results to roughly 5,000 listings per search URL — split larger queries by state or category to scale beyond that. |
| `sortBy` | select | `Most Relevant` | Order in which listings are collected. Options: Most Relevant, Newest First, Price: Low to High, Price: High to Low. If a Search URL already specifies a sort order, that URL's sort wins and this setting is ignored for it. |

#### Filters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `state` | select | (any) | Restrict plain-text Search Queries to one of the 27 Brazilian states by UF code (e.g. `SP`, `RJ`, `MG`). Search URLs already carry their own state and take precedence. |
| `minPrice` | integer | (none) | Only include listings priced at or above this amount in Brazilian Reais. Applied at OLX's native query layer. |
| `maxPrice` | integer | (none) | Only include listings priced at or below this amount in Brazilian Reais. Applied at OLX's native query layer. |
| `includeBusinessOnly` | boolean | `false` | When enabled, only include ads posted by business sellers (lojas / profissionais) and exclude private individuals. |
| `enrichDetails` | boolean | `false` | Turn on to also collect each listing's full description, seller name and CEP postal code. These listings are billed at the higher enriched rate (see Pricing), and only when the details are actually found. |

### Output

Every row is a single OLX listing with prices in BRL, photos, seller details, and posting timestamps. Here is a representative result with `enrichDetails` turned on:

```json
{
    "listingId": "1419837622",
    "title": "Apartamento 2 quartos no Centro de São Paulo",
    "description": "Apartamento mobiliado, 2 quartos, 1 vaga de garagem, próximo ao metrô.\n\nÁrea: 65m². Sol da manhã. Aceita financiamento.",
    "url": "https://sp.olx.com.br/sao-paulo-e-regiao/imoveis/apartamento-2-quartos-centro-sp-1419837622",
    "price": 420000,
    "priceDisplay": "R$ 420.000",
    "currency": "BRL",
    "city": "São Paulo",
    "state": "SP",
    "neighborhood": "Centro",
    "locationDisplay": "São Paulo, SP",
    "zipcode": "01001000",
    "categoryId": "1020",
    "categoryName": "Apartamentos",
    "parentCategoryName": "Imóveis",
    "photos": [
        "https://img.olx.com.br/images/01/example1.jpg",
        "https://img.olx.com.br/images/02/example2.jpg"
    ],
    "thumbnailUrl": "https://img.olx.com.br/images/01/example1.jpg",
    "imageCount": 12,
    "videoCount": 0,
    "properties": [
        { "name": "Quartos", "value": "2" },
        { "name": "Área útil", "value": "65" }
    ],
    "seller": {
        "name": "Imobiliária Central",
        "type": "business",
        "id": "8472193",
        "phoneAvailable": true
    },
    "isBusiness": true,
    "isFeatured": false,
    "postedAt": "2026-05-12T14:22:00+00:00",
    "postedAtTimestamp": 1747059720,
    "lastBumpAgeSecs": 86400,
    "ddd": "11",
    "searchUrl": "https://www.olx.com.br/imoveis/venda/estado-sp",
    "searchQuery": null,
    "scrapedAt": "2026-05-16T10:30:00+00:00"
}
```

#### Core Fields

| Field | Type | Description |
|-------|------|-------------|
| `listingId` | string | Unique OLX listing identifier |
| `title` | string | Listing headline as shown on OLX |
| `description` | string | Full description text (populated when `enrichDetails: true`) |
| `url` | string | Direct OLX listing URL on the regional subdomain |
| `categoryId` | string | OLX category ID |
| `categoryName` | string | Category label (e.g. `Apartamentos`, `Carros`) |
| `parentCategoryName` | string | Top-level category (e.g. `Imóveis`, `Autos e peças`) |
| `properties` | object\[] | Category-specific attributes (bedrooms, area, mileage, year, etc.) |
| `isFeatured` | boolean | Whether the ad was promoted to a featured slot |
| `postedAt` | string | ISO 8601 timestamp of when the ad was first listed |
| `postedAtTimestamp` | number | Epoch seconds of the post time |
| `lastBumpAgeSecs` | number | Seconds since the seller last bumped the listing |
| `scrapedAt` | string | ISO 8601 timestamp of data collection |
| `searchUrl` | string | The OLX URL this row came from |
| `searchQuery` | string | The plain-text query that produced this row, when applicable |

#### Price

| Field | Type | Description |
|-------|------|-------------|
| `price` | number | Numeric price in Brazilian Reais (integer) |
| `priceDisplay` | string | Price as shown on OLX (e.g. `R$ 420.000`, `À combinar`) |
| `currency` | string | Always `BRL` |

#### Location

| Field | Type | Description |
|-------|------|-------------|
| `city` | string | City name |
| `state` | string | Two-letter UF code (e.g. `SP`, `RJ`) |
| `neighborhood` | string | Neighbourhood name |
| `locationDisplay` | string | OLX's combined location string |
| `zipcode` | string | CEP postal code (populated when `enrichDetails: true`) |
| `ddd` | string | Brazilian area code for the listing region |

#### Seller

| Field | Type | Description |
|-------|------|-------------|
| `seller.name` | string | Seller name (populated when `enrichDetails: true`) |
| `seller.type` | string | `business` for professional sellers, `private` for individuals |
| `seller.id` | string | OLX seller identifier |
| `seller.phoneAvailable` | boolean | Whether OLX exposes a contact method on the ad |
| `seller.imageUrl` | string | Seller avatar URL when available |
| `isBusiness` | boolean | Convenience flag mirroring `seller.type == "business"` |

#### Photos

| Field | Type | Description |
|-------|------|-------------|
| `photos` | string\[] | Every image URL on the listing in original resolution |
| `thumbnailUrl` | string | First image, suitable for previews |
| `imageCount` | number | Total number of listing photos |
| `videoCount` | number | Total number of attached videos |

### Tips for Best Results

- **Start small.** Set `maxResults` to 30–100 on your first run to verify the data matches your needs, then scale up.
- **Use UF codes for state filtering.** The `state` field accepts the 27 official two-letter codes — combine with broad keywords like `apartamento` or `casa` rather than long-tail terms; OLX matches fuzzily and tight phrases drop too many real ads.
- **Native price filters are free.** Setting `minPrice` and `maxPrice` filters at the OLX query layer, so you never pay for listings outside your budget. Prefer this over post-filtering in your own pipeline.
- **Leave `enrichDetails` off unless you need the description text.** Title, price, photos, location, category and seller type all come from the search results at the standard rate. Only switch it on when full descriptions, seller names or postal codes are genuinely part of your workflow — those runs are billed at the higher enriched rate and take longer.
- **Pageable ceiling is ~5,000 per URL.** If you need every apartment in São Paulo state, split the run by city URLs or category sub-paths instead of one mega query — the actor will surface a friendly message when it hits the cap.
- **Mix URLs and keyword queries in one run.** You can paste category URLs from olx.com.br and add free-text queries together; results are de-duplicated by listing ID so there are no double-counts.
- **Many sources are processed sequentially.** Adding many URLs queues them one after another with a short pause between each — useful if you want predictable ordering, but for very large batches consider grouping by category instead of pasting dozens of individual URLs.
- **For listings under a tight budget, set `maxPrice` rather than trusting sort.** OLX's "Price: Low to High" order is not strictly ascending — combine `sortBy: "price_asc"` with `maxPrice` for the cleanest cheap-end sweep.

### Pricing

**$1.00 per 1,000 listings** — pay per result. You only pay for listings actually returned to your dataset.

| Listings | Estimated Cost |
|----------|----------------|
| 100 | $0.10 |
| 1,000 | $1.00 |
| 10,000 | $10.00 |
| 100,000 | $100.00 |

#### Optional: full descriptions, seller names and postal codes

Descriptions, seller names and CEP postal codes are the one thing OLX keeps off its search pages — each listing has to be opened individually to read them. That extra work is priced separately, so you never subsidise it when you don't need it:

| What you collect | Price per 1,000 |
|---|---|
| Standard listing (title, price, photos, location, category, seller type) | $1.00 |
| Listing **plus** full description, seller name and postal code | $2.80 |

Turn it on with **Add Full Description, Seller Name & Postal Code** in the input. It's off by default, and you're only charged the higher rate for listings that actually come back with those details — if OLX doesn't serve them for a listing, you pay the standard rate.

No compute or time-based charges. A "result" is any listing row in the output dataset. Platform fees (storage, optional bandwidth) are additional and depend on your Apify plan.

### Integrations

Export data in JSON, CSV, Excel, XML, or RSS. Connect to 1,500+ apps via:

- **Zapier** / **Make** / **n8n** — Workflow automation
- **Google Sheets** — Direct spreadsheet export
- **Slack** / **Email** — Notifications on new results
- **Webhooks** — Trigger custom APIs on run completion
- **Apify API** — Full programmatic access via SDK or REST

### Legal & Ethical Use

This actor is designed for legitimate market research, price intelligence, lead generation, and data aggregation. Users are responsible for complying with applicable Brazilian and international laws and OLX Brazil's terms of service, including making reasonable-rate requests and only collecting publicly accessible classified-ad data. Do not use extracted data for spam, harassment, fraud, or any illegal purpose. Be mindful of the LGPD (Lei Geral de Proteção de Dados) when handling any personal information that appears in seller profiles.

# Actor input Schema

## `searchUrls` (type: `array`):

Paste one or more OLX Brazil URLs. For example: https://www.olx.com.br/imoveis/venda/estado-sp or any URL you copied from olx.com.br after applying filters in their site.

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

Plain-text search terms — for example 'iPhone 13', 'Gol G5', or 'Apartamento'. The scraper will run each query on OLX Brazil and return matching listings.

## `maxResults` (type: `integer`):

Maximum number of listings to collect across all URLs and queries. Set to 0 for unlimited (capped internally at 50,000 for safety). Note: OLX itself limits results to roughly 5,000 listings per search URL; split larger queries by state or category to scale beyond that.

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

Choose the order in which listings are collected from OLX Brazil. If a Search URL already specifies a sort order (an OLX URL containing sf= or sp=), that URL's sort wins for that URL and this setting is ignored for it.

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

Restrict to listings in one Brazilian state. Applied only to plain-text Search Queries — Search URLs already carry their own state from olx.com.br and take precedence.

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

Only include listings priced at or above this amount in Brazilian Reais. Native OLX filter — does not cost extra. Leave empty for no minimum.

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

Only include listings priced at or below this amount in Brazilian Reais. Native OLX filter — does not cost extra. Leave empty for no maximum.

## `includeBusinessOnly` (type: `boolean`):

When enabled, only include ads posted by business sellers (lojas / profissionais) and exclude private individuals.

## `enrichDetails` (type: `boolean`):

Off by default. Turn this on to also collect each listing's full description, seller name, and CEP (postal code) — details OLX only publishes on the listing's own page. Because each listing then needs its own page visit, these enriched listings are charged at a higher rate than standard results (see Pricing). You are only charged for listings that come back with the extra details.

## Actor input object example

```json
{
  "searchUrls": [
    "https://www.olx.com.br/imoveis/venda/estado-sp"
  ],
  "searchQueries": [],
  "maxResults": 100,
  "sortBy": "relevance",
  "includeBusinessOnly": false,
  "enrichDetails": false
}
```

# Actor output Schema

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

Table of scraped listings with key fields.

## `details` (type: `string`):

All fields including seller, category, photos, and location.

# 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 = {
    "searchUrls": [
        "https://www.olx.com.br/imoveis/venda/estado-sp"
    ],
    "searchQueries": [],
    "maxResults": 100,
    "sortBy": "relevance",
    "includeBusinessOnly": false,
    "enrichDetails": false
};

// Run the Actor and wait for it to finish
const run = await client.actor("solidcode/olx-brazil-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 = {
    "searchUrls": ["https://www.olx.com.br/imoveis/venda/estado-sp"],
    "searchQueries": [],
    "maxResults": 100,
    "sortBy": "relevance",
    "includeBusinessOnly": False,
    "enrichDetails": False,
}

# Run the Actor and wait for it to finish
run = client.actor("solidcode/olx-brazil-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 '{
  "searchUrls": [
    "https://www.olx.com.br/imoveis/venda/estado-sp"
  ],
  "searchQueries": [],
  "maxResults": 100,
  "sortBy": "relevance",
  "includeBusinessOnly": false,
  "enrichDetails": false
}' |
apify call solidcode/olx-brazil-scraper --silent --output-dataset

```

## MCP server setup

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