# OLX Brazil Scraper (`tortuga/olx-brazil-scraper`) Actor

Scrape OLX Brazil (olx.com.br) listings from any search URL: price, location, rooms, area, condo fee, mileage, photos, listing date, seller type. Real estate, cars and all categories.

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

## Pricing

from $2.00 / 1,000 listing scrapeds

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

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

Scrape OLX Brazil (olx.com.br) classified listings from any search or category URL: price, old price, title, city, neighbourhood and state, category-specific attributes (rooms, bathrooms, area, condo fee, IPTU for real estate; brand, model, year, mileage, fuel, gearbox for vehicles), photos, listing date and seller type. Works for imóveis, autos e peças, eletrônicos e celulares and every other OLX category.

Paste any olx.com.br search page (with whatever filters and sort you picked in the browser) or just pick a category, a state and a keyword, and get every ad as clean JSON, CSV or Excel, or straight into your app through the API. Built for reliability: it reads the structured data OLX embeds in every page instead of scraping the visual layout, uses browser-grade TLS fingerprints, throttles itself and retries on a fresh proxy session, so runs finish instead of failing halfway. You pay only for the listings you get.

### What data does OLX Brazil Scraper extract?

Every ad from the search results gives you:

| Field | Description |
|---|---|
| `id`, `url` | OLX listing id and the ad URL |
| `title` | Ad title |
| `price`, `priceCurrency`, `priceText` | Numeric price in BRL (sale price or monthly rent) and the text as shown ("R$ 1.490.000") |
| `oldPrice`, `hasPriceReduction` | Previous price when OLX shows a price drop |
| `category`, `categoryId` | Top-level category: Imóveis, Autos e peças, Eletrônicos e celulares, ... |
| `subcategory`, `subcategoryId`, `adCategory` | e.g. "Venda - casas e apartamentos" / "Apartamentos", "Carros, vans e utilitários", "Celulares e Smartphones" |
| `location` | `{city, neighbourhood, state, ddd}` (plus `zipcode`, `zipcodePrefix`, `street`, `region`, `zone` with details) |
| `dealType` | Real estate: `sale`, `rent` or `vacation` |
| `propertyType`, `rooms`, `bathrooms`, `parkingSpaces`, `areaSqm`, `condoFee`, `iptu`, `features`, `complexFeatures` | Real-estate columns parsed from the ad attributes |
| `brand`, `model`, `year`, `mileageKm`, `fuel`, `gearbox`, `color`, `doors`, `vehicleType`, `enginePower`, `features` | Vehicle columns parsed from the ad attributes |
| `attributes` | Every category attribute OLX shows, as `{name: value}` (e.g. `electronics_model`, `cellphone_storage`, `end_tag`, `re_types`, `exchange`) |
| `images`, `imageCount`, `videoCount` | Full-size photo URLs |
| `publishedAt` | When the ad was listed (ISO 8601, UTC) |
| `sellerType`, `sellerBusinessName` | `professional` or `private`; the business name for professional accounts (agencies, dealerships, stores). Private sellers' names are never exported. |
| `isFeatured`, `olxPayEnabled`, `olxDeliveryEnabled`, `hasInspectionReport`, `has360View` | Ad flags |
| `sourceUrl`, `scrapedAt` | The search URL the ad came from and the scrape timestamp |

Turn on **Include listing details** to also open each ad page and add:

| Field | Description |
|---|---|
| `description` | Full ad text (plain text) |
| `attributes` | The complete attribute list from the ad page (more fields than the search card) |
| `location.zipcode`, `location.zipcodePrefix`, `location.street`, `location.region`, `location.zone` | CEP, street (when the seller shows it), OLX region and zone |
| `latitude`, `longitude` | Map coordinates (real-estate ads; OLX sends none for other categories) |
| `condoFee`, `iptu`, `iptuPeriod`, `priceLabel` | Condo fee and IPTU as shown in the price box ("Venda" / "Aluguel") |
| `financing` | `{isFinanceable, installment, upfrontPayment, acceptsConsortium, acceptsLoan}` |
| `fipePrice`, `marketPriceReference` | Vehicles: FIPE table price and OLX's market reference `{min, p25, median, p75, max, sampleSize, monthRef}` |
| `highlights`, `tags` | "Único dono", "IPVA pago", "Aceita troca", ... |
| `videos`, `images` | Video URLs and the full photo set |
| `sellerId`, `phoneAvailable`, `chatEnabled` | Professional account id; whether the ad shows a phone button / chat (the number itself is never collected) |

### How to scrape OLX listings

1. Open olx.com.br, run the search you want (category, state, city, price range, rooms, brand, sort) and copy the URL from the address bar into **Start URLs**. Or fill **Category** (`imoveis/venda`, `autos-e-pecas/carros-vans-e-utilitarios`, `celulares`, ...), **State** (`sp`, `rj`, `mg`, ...) and an optional **Search query**, price range and sort.
2. Set **Max items** (cost cap). Optionally turn on **Include listing details**.
3. Click **Start**. Results appear in the **Dataset** tab; export as JSON, CSV or Excel, or read them through the API.

Use `www.olx.com.br` URLs for searches. Regional sub-domains (`sp.olx.com.br/...`) are fine for single ad URLs, which return one fully detailed listing.

### Input example

```json
{
  "startUrls": [{ "url": "https://www.olx.com.br/imoveis/venda/apartamentos/estado-rj?ps=200000&pe=600000&sf=1" }],
  "maxItems": 500,
  "includeDetails": false
}
```

or, by category:

```json
{
  "category": "autos-e-pecas/carros-vans-e-utilitarios",
  "state": "sp",
  "searchQuery": "honda civic",
  "minPrice": 40000,
  "maxPrice": 120000,
  "sort": "newest",
  "maxItems": 200,
  "includeDetails": true
}
```

### Output example

```json
{
  "id": "1533858908",
  "url": "https://sp.olx.com.br/grande-campinas/imoveis/vendo-apartamento-1533858908",
  "title": "Vendo apartamento",
  "price": 190000,
  "priceCurrency": "BRL",
  "priceText": "R$ 190.000",
  "oldPrice": null,
  "category": "Imóveis",
  "subcategory": "Venda - casas e apartamentos",
  "adCategory": "Apartamentos",
  "location": { "city": "Sumaré", "neighbourhood": "Jardim Santa Maria (Nova Veneza)", "state": "SP", "ddd": "19" },
  "dealType": "sale",
  "propertyType": "Padrão",
  "rooms": 2,
  "bathrooms": 1,
  "parkingSpaces": 1,
  "areaSqm": 48,
  "condoFee": 377,
  "iptu": null,
  "features": ["Academia", "Armários na cozinha", "Armários no quarto", "Piscina"],
  "complexFeatures": ["Academia", "Condomínio fechado", "Permitido animais", "Piscina", "Portaria", "Salão de festas", "Segurança 24h"],
  "attributes": { "real_estate_type": "Venda - apartamento padrão", "condominio": "R$ 377", "size": "48m²", "rooms": "2", "bathrooms": "1", "garage_spaces": "1", "re_types": "Padrão" },
  "images": ["https://img.olx.com.br/images/12/126668798559786.jpg"],
  "imageCount": 9,
  "publishedAt": "2026-09-09T16:25:47+00:00",
  "sellerType": "private",
  "sellerBusinessName": null,
  "isFeatured": true,
  "hasPriceReduction": false,
  "sourceUrl": "https://www.olx.com.br/imoveis/estado-sp",
  "scrapedAt": "2026-09-09T16:43:35+00:00"
}
```

A vehicle ad has `brand`, `model`, `year`, `mileageKm`, `fuel`, `gearbox`, `color`, `doors`, `vehicleType` instead of the real-estate columns; with details it also carries `fipePrice`, `marketPriceReference`, `financing.installment` and `highlights`.

### How many listings can I get per search?

OLX shows 50 ads per page and serves at most 100 pages, so one search URL yields up to 5,000 listings. To go beyond that, split the search: by state (`estado-sp`, `estado-rj`), by region or city path (`/imoveis/venda/estado-sp/sao-paulo-e-regiao/zona-sul`), by subcategory (`/imoveis/venda/apartamentos`, `/autos-e-pecas/motos`) or by price band (`ps=` / `pe=`). Run several URLs in one run; results are de-duplicated by listing id. Sorting by newest (`sf=1`, or **Sort: Newest first**) is the best way to collect fresh ads on a schedule.

### Does it work for cars, phones and other categories, not just real estate?

Yes. Every OLX category is supported: paste the category or search URL, or set **Category** to its path. The `attributes` object always carries every attribute OLX shows for that category; the real-estate and vehicle columns are filled in whenever the attributes exist.

### Does it collect seller phone numbers or names?

No. This Actor collects public listing data only. Business names of professional accounts (imobiliárias, concessionárias, lojas) are exported as `sellerBusinessName`; names of private sellers and all phone numbers are never collected. `phoneAvailable` only tells you whether the ad shows a phone button.

### Do I need a proxy?

Apify Proxy is enabled by default. OLX sits behind Cloudflare; datacenter proxies worked in testing, and the Actor retries on a fresh proxy session when it sees 403/429. If a run logs many retries, switch the proxy to the RESIDENTIAL group.

### Pricing

Pay per result: a small fee for every listing saved from a search page, plus a small fee per ad page opened when **Include listing details** is on (see the Pricing tab). There is no subscription and no start fee; Apify's free plan is enough to try it.

### Integrations and API

Use the run in Zapier, Make, n8n, Google Sheets, or call it from Python/Node with the Apify client. See the **API** tab for ready-made snippets.

### Is it legal to scrape OLX Brasil?

This Actor collects only publicly available, non-personal listing data (no phone numbers, no names of private sellers). You are responsible for how you use the data and for complying with OLX's terms, the LGPD and other applicable law.

### Support

Found a bug or need a field added? Open an issue in the **Issues** tab; it is usually answered within a day.

# Actor input Schema

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

OLX Brazil search or category pages, with any filters and sort applied in the browser, e.g. https://www.olx.com.br/imoveis/venda/estado-sp, https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-rj?ps=30000\&pe=80000, https://www.olx.com.br/brasil?q=iphone+15. Use www.olx.com.br URLs (regional sub-domains like sp.olx.com.br only work for single ad pages). A single ad URL (…/<slug>-<id>) is also accepted and returns that one listing with full details. Leave empty if you use Category / State / Search query instead.

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

Alternative to Start URLs: an OLX category path, e.g. imoveis, imoveis/venda, imoveis/aluguel, imoveis/terrenos, autos-e-pecas/carros-vans-e-utilitarios, autos-e-pecas/motos, eletronicos-e-celulares, celulares, para-a-sua-casa, esportes-e-lazer, moda-e-beleza. Leave empty to search all categories.

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

Used with Category / Search query: two-letter Brazilian state, e.g. sp, rj, mg, rs, pr, ba. Leave empty for the whole country.

## `searchQuery` (type: `string`):

Keyword search within the category and state, e.g. "apartamento 2 quartos", "honda civic", "iphone 15".

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

Used with Category / State / Search query. Sale price, or monthly rent for rentals.

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

Used with Category / State / Search query. Sale price, or monthly rent for rentals.

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

Used with Category / State / Search query. OLX's default is relevance.

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

Stop after this many listings in total (across all start URLs). Keeps cost predictable. OLX shows 50 ads per page and serves at most 100 pages (5,000 ads) per search, so split large searches by state, city, category or price band to get more.

## `includeDetails` (type: `boolean`):

Also open every ad page to get the full description, the complete attribute list, CEP (postal code), street (when the seller shows it), map coordinates (real estate), condo fee and IPTU details, financing / installment info, FIPE and market price reference (vehicles), highlights, videos and the seller's business name. One extra request per listing; charged extra per listing (see pricing).

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

Apify Proxy is recommended. OLX sits behind Cloudflare; datacenter IPs worked in testing, but if you see 403/429 in the run log switch to the RESIDENTIAL group.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.olx.com.br/imoveis/venda/estado-sp"
    }
  ],
  "sort": "",
  "maxItems": 100,
  "includeDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

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

No description

# 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 = {
    "startUrls": [
        {
            "url": "https://www.olx.com.br/imoveis/venda/estado-sp"
        }
    ],
    "category": "",
    "state": "",
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("tortuga/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 = {
    "startUrls": [{ "url": "https://www.olx.com.br/imoveis/venda/estado-sp" }],
    "category": "",
    "state": "",
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("tortuga/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 '{
  "startUrls": [
    {
      "url": "https://www.olx.com.br/imoveis/venda/estado-sp"
    }
  ],
  "category": "",
  "state": "",
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call tortuga/olx-brazil-scraper --silent --output-dataset

```

## MCP server setup

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