Extracting web data from Latin America's largest classifieds marketplace—OLX Brazil (olx.com.br)—is one of the most common requirements for e-commerce arbitrage, real estate valuation models, and automotive market analysis. However, it is also notoriously difficult to automate reliably from scratch.

Modern OLX Brazil operates on a Next.js App Router architecture. It does not expose a clean, public REST API for search listings, strictly geo-fences search traffic, and deploys aggressive anti-bot defenses that serve instant HTTP 403 or ~5.8 KB challenge pages to standard HTTP clients, headless browsers, and datacenter proxy networks. Furthermore, OLX's search results feature dynamic, non-standard HTML structures and silent "phantom fallbacks" that cause brittle home-brewed scrapers to fail silently or corrupt datasets with wrong categories.

In this comprehensive guide, you will learn how to scrape OLX Brazil at scale using the production-ready OLX Brazil Scraper on Apify. We will cover the entire workflow: from configuring URL paths and filtering typed property/vehicle attributes to running automated batch jobs via the Apify Python SDK.

• Target Audience: Data engineers, Python developers, growth hackers, and market researchers.
• Prerequisites: A web browser and a free Apify account. Minimal Python knowledge if integrating via API.
• ⏱️ Estimated Time: 10–15 minutes to configure and complete your first production scrape.

2. TL;DR

• The Problem: Scraping olx.com.br directly fails due to Next.js App Router client rendering, hard 100-page pagination clamps, and strict bot mitigation that bans standard residential and datacenter proxies.
• The Solution: Use the OLX Brazil Scraper on Apify Store—a cloud Actor that uses Apify Unblocker, parses search cards directly into typed schemas (m², bedrooms, mileage, year), filters phantom ads, and exports clean CSV, JSON, or Excel.
• Cost Model: 100% pay-per-event at $0.001 per dataset row (\(1.00 per 1,000 items) + \)0.00005 per run start. No monthly subscriptions.

3. Prerequisites & Setup

Before running the Actor, ensure you have set up your Apify environment:

1. Create an Apify Account:
   • Navigate to Apify Sign Up.
   • Sign up using your GitHub or Google account. The free tier includes $5.00 in monthly platform usage credits, which is more than enough to scrape thousands of items during development.
2. What is the Apify Console?:
   • The Apify Console is the centralized cloud dashboard where you configure Actor inputs, monitor execution logs in real-time, view storage datasets, and manage scheduled cron jobs.
3. API Token (Optional for CLI/SDK):
   • If you plan to automate your runs with Python or Node.js, grab your personal API token from Console → Settings → Integrations → API tokens.

4. Understanding OLX Brazil Scraper

Technical Architecture

The OLX Brazil Scraper is built specifically around the quirks and limitations of the current olx.com.br platform:

• Generic Path Routing: Rather than relying on rigid, pre-defined category dropdowns that break whenever OLX reorganizes its taxonomy, the Actor accepts raw URL path segments (e.g., imoveis/aluguel/apartamentos/estado-sp). You copy the path directly from your browser, and the Actor walks the pagination tree.
• Typed Field Extraction: The Actor parses ad chips into typed properties instead of doing lossy free-text guessing:
  • Real Estate: areaM2, bedrooms, bathrooms, parkingSpaces.
  • Automotive: mileageKm, color, engineSize, bodyType, year.
  • Catch-All Attributes: Every remaining unstructured badge (e.g., fuel type, transmission, condo fee condominio, property tax IPTU) is normalized into an attributes dictionary.
• The "Phantom Fallback" Defense: When an OLX search keyword yields zero results, the website silently renders up to 8 unrelated "Mais recentes" (Most Recent) recommendations under the exact same CSS markup as genuine matches. Brittle scrapers ingest these as false positives. The OLX Brazil Scraper inspects the page's canonical 0 - 0 de 0 resultados indicator and terminates safely with a clean exit.
• Apify Unblocker Integration: Standard datacenter and residential proxy pools fail against OLX Brazil with 100% block rates. The Actor pre-configures Apify Unblocker to bypass Akamai and Cloudflare challenge screens seamlessly.
• Privacy by Design: The Actor extracts only public search card metadata. Private seller telephone numbers, email addresses, and personal IDs are never collected.

5. Step-by-Step Guide to Using the Actor

Step 1: Accessing the Actor

1. Navigate to the official store page: OLX Brazil Scraper — Any Category, Any Keyword.
2. Review the technical specification and pricing model ($1.00 / 1,000 items).
3. Click the blue Try for free button.
4. You will be redirected to the Apify Console with the Actor's input interface pre-loaded.

Step 2: Configuring Input Parameters

The input schema is designed to mirror native OLX navigation. Here are the core fields:

• categoryPath (string): The URL path segment from OLX.
  • Nationwide Cars: autos-e-pecas/carros-vans-e-utilitarios
  • São Paulo Real Estate: imoveis/venda/apartamentos/estado-sp/sao-paulo-e-regiao
  • Nationwide Browse: Leave completely blank to search all of Brazil.
• searchQueries (array of strings): Optional keywords. Each keyword narrows results within your specified categoryPath without overriding it.
• minPrice / maxPrice (integer): Price boundaries in Brazilian Real (BRL). When left unset, free listings (R$ 0) and unpriced items are safely preserved.
• sortBy (enum): relevance (default), newest, priceAsc, or priceDesc.

Example Configuration A: Used SUVs in São Paulo

{
  "categoryPath": "autos-e-pecas/carros-vans-e-utilitarios/estado-sp",
  "searchQueries": ["renegade", "compass"],
  "minPrice": 70000,
  "maxPrice": 120000,
  "sortBy": "priceAsc",
  "maxItems": 150
}

Example Configuration B: Rental Apartments in Brasília

{
  "categoryPath": "imoveis/aluguel/apartamentos/estado-df/distrito-federal-e-regiao/brasilia",
  "searchQueries": ["asa sul"],
  "minPrice": 2000,
  "maxPrice": 4500,
  "sortBy": "newest",
  "maxItems": 100
}

Step 3: Advanced Configuration & Optimization

Under the configuration form, click Advanced options to customize execution constraints:

• minMileageKm / maxMileageKm (integer): Bounded vehicle odometer limits (validated on the autos vertical).
• acceptsTradeOnly (boolean): Filters exclusively for sellers open to vehicle trades ("Aceita trocas").
• requireKeywordMatch (boolean, default: true): Applies a defensive tokenization filter after extraction to ensure every word in your query appears in the ad title.
• maxPages (integer, default: 100): Hard ceiling per query.

  ⚠️ Platform Constraint: olx.com.br clamps every search at page 100 (~5,000 listings). Pages 101+ serve byte-identical duplicates of page 100. The Actor enforces this clamp automatically.

• maxItems (integer, default: 300): Governs maximum records returned. 300 rows finish in ~50 seconds, fitting well within Apify's platform auto-test limits.

Step 4: Proxy Configuration

OLX Brazil uses sophisticated browser profiling and TLS fingerprinting.

• By default, the Actor sets proxyConfiguration to use Apify Unblocker (apifyProxyGroups: ["UNBLOCKER"]).
• Do not disable this setting: Standard datacenter and residential IPs receive an immediate access denial.

Step 5: Running the Actor

1. In the bottom-right corner of the Console, click Save & Run (or Start).
2. The runtime status updates to Running 🟡.
3. The live log terminal will output:
   • Initialization with Apify Unblocker.
   • Target URL construction: https://www.olx.com.br/autos-e-pecas/...&q=renegade.
   • Page-by-page progress indicators showing rows extracted per batch.
4. Once completed, the badge switches to SUCCEEDED 🟢.

💡 Background Execution: Runs execute in isolated cloud containers. You can safely close your browser or disconnect from your network; the job will continue until completion.

Step 6: Examining the Results

Click the Storage tab (or scroll down to Dataset) to inspect your extracted data:

{
  "id": "1532323306",
  "title": "Toyota Corolla Cross XRE 2.0 16V Flex AUT 2023",
  "url": "https://df.olx.com.br/distrito-federal-e-regiao/autos-e-pecas/carros-vans-e-utilitarios/toyota-corolla-cross-xre-2-0-16v-flex-aut-2023-1532323306",
  "imageUrl": "https://img.olx.com.br/images/43/430647444372585.jpg",
  "price": 114900,
  "currency": "BRL",
  "location": "Brasília - DF",
  "city": "Brasília",
  "neighbourhood": "Setor Residencial Leste (Planaltina)",
  "state": "DF",
  "postedAt": "2026-09-04T02:09:41Z",
  "category": "Carros, vans e utilitários",
  "mileageKm": 82000,
  "color": "Preto",
  "engineSize": "2.0 - 2.9",
  "bodyType": "SUV",
  "year": 2023,
  "acceptsTrade": false,
  "attributes": {
    "vehicle_brand": "Toyota",
    "vehicle_model": "Corolla Cross XRE 2.0 16V Flex",
    "fuel": "Flex",
    "gearbox": "Automático",
    "doors": "4 portas"
  }
}

Step 7: Downloading and Exporting Data

Apify provides one-click export formats:

• CSV / Excel: Best for importing into pandas, Google Sheets, or business dashboards.
• JSON / JSONL: Best for feeding downstream microservices, Elasticsearch, or vector databases.
• Field Selection: Click Select fields to omit raw columns (such as imageUrl or attributes) if you only need price and location data.

6. Working with the API (Python SDK)

To integrate the scraper into your data engineering pipelines, use the official apify-client Python package.

Installation

pip install apify-client

Production Python Script with Error Handling

import os
import sys
from itertools import islice
from apify_client import ApifyClient
from apify_client.errors import ApifyApiError

# Load your token from environment variables
APIFY_TOKEN = os.getenv("APIFY_TOKEN")
if not APIFY_TOKEN:
    sys.exit("Error: APIFY_TOKEN environment variable not set.")

client = ApifyClient(APIFY_TOKEN)

run_input = {
    "categoryPath": "autos-e-pecas/carros-vans-e-utilitarios",
    "searchQueries": ["Toyota Hilux"],
    "minPrice": 120000,
    "maxPrice": 220000,
    "maxItems": 100,
    "sortBy": "newest"
}

def format_price(value):
    if value is None:
        return "Sob consulta"
    return f"R$ {value:,.0f}".replace(",", ".")

try:
    print("🚀 Triggering OLX Brazil Scraper on Apify...")
    run = client.actor("reventadata/olx-scraper").call(run_input=run_input)

    status = run.get("status")
    dataset_id = run.get("defaultDatasetId")

    # Defensive check: verify run actually succeeded before reading
    if status != "SUCCEEDED":
        print(f"⚠️ Actor finished with status: {status} (Dataset ID: {dataset_id})")
        sys.exit(1)

    print(f"✅ Run completed successfully! Dataset ID: {dataset_id}")

    # Paginate through extracted dataset items defensively
    dataset = client.dataset(dataset_id)
    items = list(islice(dataset.iterate_items(), 5))

    if not items:
        print("ℹ️ Query returned 0 results matching criteria.")
    else:
        print(f"📦 Showing first {len(items)} listings:")
        for ad in items:
            price_tag = format_price(ad.get("price"))
            location = ", ".join(filter(None, [ad.get("city"), ad.get("state")])) or "Localização não informada"
            year_tag = f" ({ad.get('year')})" if ad.get("year") else ""
            print(f"• [{price_tag}] {ad.get('title', 'Sem título')} | {location}{year_tag}")

except ApifyApiError as e:
    print(f"❌ Apify API Exception: {e}")
except Exception as e:
    print(f"❌ Unexpected Error: {e}")

7. Advanced Usage Patterns & Automation

1. Daily Price Tracking via Scheduled Runs

Set up a daily cron trigger inside Apify Console → Schedules:

• Schedule: 0 8 * * * (Runs every day at 8:00 AM UTC).
• Connect the output to a Webhook pointing to your Slack channel, Discord, or backend endpoint to receive automated alerts whenever a listing price drops below market value.

2. High-Volume Partitioning (Breaking the 5,000 Item Limit)

Because OLX hard-clamps every search query to 100 pages (~5,000 listings), you cannot extract 50,000 ads with a single nationwide keyword. Instead, partition your jobs:

• Partition by Brazilian State (UF): Run concurrent jobs across estado-sp, estado-rj, estado-mg, and estado-pr.
• Partition by Price Brackets: Split searches into minPrice: 50000, maxPrice: 75000, minPrice: 75001, maxPrice: 100000, etc.

8. Understanding Your Data Schema

9. Troubleshooting & Common Gotchas

• Issue: Run finished with status FAILED (0 rows found):
  • Reason: The Actor intentionally raises an error if zero rows match your parameters instead of outputting an empty dataset. This prevents silent failures in production pipelines.
  • Fix: Verify your categoryPath segment on olx.com.br directly in your browser. Ensure your price or mileage boundaries are not conflicting.
• Issue: 403 Forbidden or Proxy Errors:
  • Reason: Custom proxy settings were applied that bypassed Apify Unblocker.
  • Fix: Always leave proxyConfiguration on default (apifyProxyGroups: ["UNBLOCKER"]).
• Issue: Missing values in property or vehicle fields:
  • Reason: A car ad does not have bedrooms, and land plots do not have bathrooms. Unstated fields return null, never 0, to preserve mathematical integrity for machine learning models.

10. Best Practices

1. Keep Prefills Lightweight in CI/CD: When running smoke tests or automated validations, set maxItems: 10 to avoid unnecessary compute charges.
2. Handle Currency Normalization: All prices are returned in integer Brazilian Real (BRL). Do not divide by 100.
3. Respect Upstream Limits: Avoid launching 50 parallel runs against the same narrow city category simultaneously. Spread requests across regions to maintain optimal unblocking speeds.

11. Conclusion & Next Steps

Extracting data from dynamic classifieds platforms like OLX Brazil no longer requires writing custom Playwright scripts, reverse-engineering Next.js payload bundles, or maintaining expensive proxy fleets. With the OLX Brazil Scraper, you can spin up production-grade data feeds with clean, typed schemas in minutes.

• 🚀 Try the Actor: OLX Brazil Scraper on Apify Store
• 📖 Pricing: $1.00 per 1,000 items (Pay-per-event).
• 💬 Feedback & Discussion: What market trends are you analyzing on OLX Brazil? Drop a comment below if you have questions or want to see a guide for a specific marketplace!

Cross-Platform Guides & Community Formats

• ⚡ Developer Quickstart (DEV Community): How to Scrape Real Estate & Car Listings from OLX Brazil
• ☕ No-Code Beginner Story (Medium): How I Extracted Thousands of Real Estate & Car Deals from OLX Brazil in Minutes

About the Author

ReventaData builds production-grade web scrapers, automated data pipelines, and pay-per-event Apify Actors specializing in European and Latin American second-hand marketplaces, EV charging infrastructure, and public web data extraction. Follow our publications for deep dives into web scraping architecture and reverse-engineering.