# OLX Brasil Classifieds & Real Estate Scraper (`automatic/olx-brasil-scraper`) Actor

Collect OLX Brazil general classifieds and real estate listings, with pagination, duplicate suppression, optional detail pages and a maximum result count.

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

## Pricing

from $1.00 / 1,000 listings

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?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

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

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## OLX Brasil Scraper

Collect OLX Brazil general classifieds and real estate listings, with pagination, duplicate suppression, optional detail pages and a maximum result count.

Each row carries the listing ID, URL, title, BRL price, category, state, city, neighbourhood, posted date, a professional-seller flag and image URLs. Real estate rows add property type, rent or sale, bedrooms, bathrooms, area, condominium fee, IPTU, parking spaces and features where OLX shows them. Seller names and contact fields are never collected. Missing source values are null.

### Usage

```json
{"keyword":"bicicleta","maxResults":20,"includeDetails":false}
```

An input with no keyword, the `all` category, no state and no `searchUrl` uses the example search `bicicleta`. With a category, a state or a search URL, an empty keyword browses that scope without a term.

Structured inputs support `category` (`all`, `imoveis`, `imoveis-rent`, `imoveis-sale`), state UF, city and BRL `priceMin`/`priceMax`. `city` takes an OLX location name under the state, spelled as OLX spells it, for example the region `São Paulo e Região` (search path `/imoveis/aluguel/estado-sp/sao-paulo-e-regiao`); plain city names resolve to their own location path. Because OLX region pages legitimately cover several municipalities, rows are filtered by state and price but not by city name.

Provide `searchUrl` for an exact OLX search including category, location and source filters. An explicit URL replaces the generated path and query; state and price constraints still apply to output.

### Output

Results contain `listingId`, `url`, `title`, `price`, `currency`, `category`, `state`, `city`, `neighborhood`, public `postalCode`, `postedDate`, `professionalSeller`, `description` and `images`. Property fields are `propertyType`, `businessType`, `bedrooms`, `bathrooms`, `usableAreaM2`, `condoFee`, `iptu`, `parkingSpaces` and `amenities`. Overlapping field names match the VivaReal/ZAP actor, so the two datasets can be joined.

```json
{
  "listingId": "1511090340",
  "url": "https://df.olx.com.br/distrito-federal-e-regiao/ciclismo/vendo-bike-scott-speedster-s60-quadro-aluminio-super-leve-garfo-carbono-aro-700-1511090340",
  "title": "Vendo bike Scott Speedster S60 | Quadro Alumínio Super Leve + Garfo Carbono | Aro 700",
  "price": 2500.0,
  "currency": "BRL",
  "category": "Ciclismo",
  "state": "DF",
  "city": "Brasília",
  "neighborhood": "Vila Planalto",
  "postalCode": null,
  "postedDate": "2026-10-31T17:59:53+00:00",
  "professionalSeller": false,
  "description": null,
  "images": ["https://img.olx.com.br/images/37/377655535290488.jpg"],
  "propertyType": null,
  "businessType": null,
  "bedrooms": null,
  "bathrooms": null,
  "usableAreaM2": null,
  "condoFee": null,
  "iptu": null,
  "parkingSpaces": null,
  "amenities": []
}
```

Real-estate cards carry bedrooms, bathrooms, area, condominium fee, IPTU, garage spaces and feature lists directly; `postalCode` and full `description` appear only with `includeDetails`, and fields a card does not state stay null. Prices and fees are BRL; dates are UTC ISO timestamps from the public card date (which may reflect a refresh). Descriptions are excerpts of up to 500 characters, with email and Brazilian phone patterns redacted. Images and amenities are arrays.

### Detail pages

`includeDetails` defaults to false. Enabling it makes one additional request per listing; the detail page's embedded listing state and schema.org block add the public postal code, description, place fields and any card attributes, and may refresh price and posted date. An unrecognized detail page keeps the card fields; the run status and the `OUTPUT` record report incomplete extraction. No property attributes are inferred from titles or keyword inputs.

### Proxy route

The default route is Apify **UNBLOCKER**, without a country or session. Direct, datacenter and Brazilian residential requests were blocked during platform probes. `proxyConfiguration` can override the default; other groups may fail. TLS certificate verification is disabled only for a route that is exactly the Apify UNBLOCKER group, whose proxy re-signs certificates; it stays on for every other group and for custom proxy URLs. Requests use a generic desktop browser user agent and no identity or contact headers. Redirects are not followed.

### Pagination and limits

The observed search exposes 100 pages; actual result counts and caps vary by query. A repeat page stops pagination and reports incomplete coverage. Empty pages require a second successful request. After 5 consecutive pages with no listing matching the state or price filters, the run stops and says so in its status message and `OUTPUT` issues. Requests and retry delays share the actor deadline, reserving 20 seconds for final delivery. Full Retry-After delays are honored; a delay that cannot fit ends collection. Partial output remains available with a status message when blocked or time-limited.

### Pricing

Pay-per-event pricing uses the platform start event once per run plus the default dataset item event per delivered unique row, like the rest of this fleet. With `includeDetails`, each row whose detail page actually added data is also charged one `listing-details` event; a failed or unrecognized detail page is not charged. Check the current listing for the applicable prices. The customer's maximum charge is respected: a row, and its detail page, is only fetched when both can still be paid for. Duplicate, malformed, blocked and empty rows create no listing events.

### Run size

The default memory is 512 MB. When a per-event plan applies, the start event is counted per GB of memory, rounded up; the default 512 MB run is one start event.

### Test fixtures

Offline fixtures come from successful platform captures (search page 1, search page 2 with its next-page link, an `/imoveis/aluguel/estado-sp/sao-paulo-e-regiao` search and one apartment detail page) with seller payloads and phone area codes removed. They prove parsing shapes, not live availability; platform canaries are still required before publication.

# Actor input Schema

## `keyword` (type: `string`):

Search term. Leave empty to browse a category, state or search URL without a term; a fully empty input uses the example search bicicleta.

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

General classifieds or real estate rent/sale. URL overrides structured search routing.

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

Optional Brazilian state. Shapes the search path and also filters returned rows.

## `city` (type: `string`):

Optional OLX location name under the state: a region such as 'São Paulo e Região' or a city, spelled as OLX spells it. Requires state and narrows the search path; rows are not filtered by municipality because region pages cover several cities.

## `priceMin` (type: `number`):

Inclusive price constraint in BRL; also filters returned rows.

## `priceMax` (type: `number`):

Inclusive price constraint in BRL; also filters returned rows.

## `searchUrl` (type: `string`):

OLX Brazil HTTPS search URL. Overrides the generated search path and query; state and price constraints still filter returned rows.

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

Maximum unique listings to deliver.

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

Request each detail page for extra public attributes such as postal code and description. Slower, uses one extra proxy request per row and adds a listing-details charge per row that got detail data.

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

Defaults to UNBLOCKER with no country or session. Other Apify groups were blocked in probes.

## Actor input object example

```json
{
  "keyword": "bicicleta",
  "category": "all",
  "maxResults": 20,
  "includeDetails": false,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "UNBLOCKER"
    ]
  }
}
```

# Actor output Schema

## `dataset` (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 = {
    "keyword": "bicicleta",
    "maxResults": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automatic/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 = {
    "keyword": "bicicleta",
    "maxResults": 20,
}

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

```

## MCP server setup

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