# OLX Brasil Carros Data Scraper (`w3crawler/olx-cars-scraper`) Actor Extracts public OLX Brasil vehicle listings with prices, FIPE references, vehicle attributes, photos, and descriptions. - **URL**: https://apify.com/w3crawler/olx-cars-scraper.md - **Developed by:** [w3crawler](https://apify.com/w3crawler) (community) - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $2.99 / 1,000 vehicle listings 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? 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 ### What does OLX Brasil Carros Data Scraper do? OLX Brasil Carros Data Scraper collects vehicle listings that are exposed on public [OLX Brasil](https://www.olx.com.br/) search pages. It applies state, brand, price, mileage, model-year, color, FIPE, and free-text filters, then emits normalized listing records with public URLs, visible vehicle attributes, and request provenance. The Actor uses ordinary bounded HTTP requests. It does not log in, solve CAPTCHA or JavaScript challenges, use private APIs, bypass access controls, or invent vehicle data. When OLX returns an access boundary, empty page, malformed response, or transport failure, the run emits a structured diagnostic row instead of treating the failure as a successful scrape. ### Why use OLX Brasil Carros Data Scraper? Use the Actor to compare asking prices, review supply by Brazilian state, monitor dealer inventory, and analyze advertised prices against FIPE references when those values are visible in the source page. `ads_limit`, `maxPages`, response-size limits, and the retry budget keep each run bounded. Dataset records include enough provenance to distinguish observed public listings from access or parsing diagnostics. ### What data can OLX Brasil Carros Data Scraper extract? Normal rows are emitted only when a public vehicle listing has an identifiable listing URL, title, and listing ID. Optional fields appear only when the source exposes them. | Field | Type | Meaning | | ------------------------------------- | ---------------- | ----------------------------------------------------------------------------------- | | `recordType` | string | `olx-vehicle-listing` for a listing or `run_diagnostic` for a non-business outcome. | | `targetType` | string | `olx-vehicle`. | | `id` / `listingId` | string | Stable row identity and public listing identifier. | | `source` | string | `olx-cars`. | | `dataAvailable` | boolean | Whether usable vehicle data is present. | | `verified` / `verificationStatus` | boolean / string | Whether the row came from a public listing (`public_listing`). | | `accessStatus` / `sourceBlocked` | string / boolean | Observed access state and whether a source boundary was hit. | | `transport` / `sourceTransport` | string | `http` for live requests or `fixture` for an explicitly supplied QA fixture. | | `proxyUsed` | boolean | Whether the row was obtained through Apify Proxy. | | `requestUrl` / `finalUrl` | URI | Public request and final response URLs. | | `httpStatus` | integer | Observed HTTP status, when available. | | `pageType` / `sourceType` | string | Page context; diagnostics use `sourceType: "diagnostic"`. | | `query` / `stateFilter` | string | Search context recorded on diagnostics when available. | | `title` / `url` | string / URI | Listing headline and public listing URL. | | `price` / `fipePrice` | number | Advertised and FIPE reference prices, in BRL, when visible. | | `brand` / `model` | string | Vehicle make and model. | | `year` / `mileage` | integer | Model year and odometer mileage in kilometres. | | `fuel` / `color` | string | Public vehicle attributes. | | `photos` | URI array | Public image URLs that passed the OLX image-host boundary. | | `description` / `location` | string | Visible description and locality. | | `publishedAt` | date-time | Publication timestamp when parseable. | | `isBusiness` / `isFeatured` | boolean | Seller or featured-ad indicators when exposed. | | `sourceUrl` / `searchUrl` / `pageUrl` | URI | Source search and page provenance. | | `pageNumber` / `itemPosition` | integer | One-based result page and position. | | `scrapedAt` | date-time | Time the Actor normalized the row. | | `error` / `errorCode` | string | Diagnostic explanation and stable machine-readable code. | ### How to scrape OLX Brasil vehicle listings 1. Open the Actor in Apify Console and select the **Input** tab. 2. Choose a Brazilian `state`, or leave the UI default `sp`, and add any vehicle filters. 3. Set `ads_limit` and `maxPages` so the run stays within the required result and page budget. 4. Click **Save & Run**. The Actor sends bounded public requests and stops when the requested limit, page limit, or a source boundary is reached. 5. Open the **Dataset** tab to inspect listing and diagnostic rows. Open the **Key-value store** tab and select `OUTPUT_SUMMARY` for the run summary. 6. Use the **API** tab or the links documented under [Apify API](https://docs.apify.com/api/v2) for programmatic access and scheduling. The Actor follows public search pagination when OLX exposes a safe next-page link; otherwise it derives bounded `o=` page URLs. It does not open listing detail pages, so it does not claim fields that are unavailable on the search response. ### How much will it cost to scrape OLX Brasil vehicle listings? Apify account billing for compute, network traffic, and any selected proxy service applies. This repository does not promise a fixed dollar-per-1,000-record price; check the current Apify pricing shown in your account before production use. Direct HTTP is the default and avoids proxy charges where direct access is available. A configured proxy can add account-specific proxy costs. The runtime bounds are: - At most 100 listing rows per run (`ads_limit`). - At most 10 result pages (`maxPages`). - A 5,000–60,000 ms timeout per request (`timeoutMs`). - A 1,000–10,000,000 byte response limit (`maxBytes`). - At most three retries per request (`maxRequestRetries`). Use smaller limits while developing and schedule only the frequency your use case needs. A diagnostic-only run is an operationally successful Actor run, but it is not evidence that listing data was collected. ### Input The input is a JSON object. Unknown keys, explicit `null` values, invalid types, and reversed ranges are rejected. The Console schema requires `state` and supplies `sp` as its default; the runtime also uses `sp` when the key is omitted and accepts uppercase state input by normalizing it to lowercase. | Input | Type and bounds | Default | Description | | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `state` | string; one of `ac`, `al`, `ap`, `am`, `ba`, `ce`, `df`, `es`, `go`, `ma`, `mt`, `ms`, `mg`, `pa`, `pb`, `pr`, `pe`, `pi`, `rj`, `rn`, `rs`, `ro`, `rr`, `sc`, `sp`, `se`, `to` | `sp` | Required Brazilian state filter. | | `brand` | string, maximum 80 characters | empty | Optional vehicle-brand path filter. | | `ps` / `pe` | integer, 0–100,000,000 | omitted | Minimum and maximum price in BRL; `ps` cannot exceed `pe`. | | `mileage_from` / `mileage_to` | integer, 0–2,000,000 | omitted | Minimum and maximum mileage in kilometres; the lower bound cannot exceed the upper bound. | | `year_from` / `year_to` | integer, 1900–2100 | omitted | Model-year range; the lower bound cannot exceed the upper bound. | | `colors` | array of at most 10 values | `[]` | Allowed labels: `Preto`, `Branco`, `Prata`, `Cinza`, `Azul`, `Vermelho`, `Verde`, `Amarelo`, `Laranja`, `Outra`. Duplicate labels are removed. | | `fpdll` | boolean | `false` | Requests OLX’s below-FIPE filter where the source supports it. | | `search` | string, maximum 200 characters | empty | Optional free-text query. | | `ads_limit` | integer, 1–100 | `10` | Maximum normal listing rows emitted. | | `maxPages` | integer, 1–10 | `5` | Maximum search pages visited. | | `deduplicate` | boolean | `true` | Removes repeated listing IDs across pages. | | `timeoutMs` | integer, 5,000–60,000 | `30,000` | Per-request timeout in milliseconds. | | `maxBytes` | integer, 1,000–10,000,000 | `5,000,000` | Maximum response size accepted for parsing. | | `requestDelayMs` | integer, 0–10,000 | `0` | Bounded delay between live requests. | | `maxRequestRetries` | integer, 0–3 | `1` | Retries transient request, timeout, and HTTP failures. Access boundaries and proxy-authentication failures are not retried. | | `proxyConfiguration` | object | omitted | Optional standard Apify Proxy configuration. Credentials stay inside the Apify SDK. | | `fixturePath` | relative `.html`, `.htm`, `.json`, or `.txt` path, maximum 260 characters | omitted | Explicit checked-in QA fixture; it is never an implicit live fallback. | #### Minimal search input ```json { "state": "sp", "ads_limit": 10 } ``` #### Filtered search input ```json { "state": "sp", "brand": "Honda", "ps": 50000, "pe": 180000, "mileage_from": 0, "mileage_to": 120000, "year_from": 2018, "year_to": 2024, "colors": ["Preto", "Branco"], "fpdll": true, "search": "Civic Touring", "ads_limit": 25, "maxPages": 3 } ``` #### Proxy input ```json { "state": "sp", "ads_limit": 10, "proxyConfiguration": { "useApifyProxy": true, "apifyProxyGroups": ["RESIDENTIAL"], "apifyProxyCountry": "BR" } } ``` #### Explicit local QA fixture input ```json { "state": "sp", "ads_limit": 3, "maxPages": 1, "fixturePath": "test/fixtures/list.html" } ``` `fixturePath` is for deterministic repository validation only. It must be supplied explicitly and is not a production data source. ### Output The Dataset contains normalized listing rows and, when needed, separate `run_diagnostic` rows. The Actor also writes the same JSON summary to `OUTPUT` and `OUTPUT_SUMMARY` in the default key-value store. #### Normal vehicle listing ```json { "recordType": "olx-vehicle-listing", "targetType": "olx-vehicle", "id": "1520801161", "source": "olx-cars", "dataAvailable": true, "verified": true, "verificationStatus": "public_listing", "accessStatus": "public_page", "sourceBlocked": false, "transport": "http", "sourceTransport": "http", "proxyUsed": false, "listingId": "1520801161", "title": "Honda Civic Touring 2020", "url": "https://sp.olx.com.br/sao-paulo-e-regiao/autos-e-pecas/carros/honda-civic-touring-1520801161", "price": 115000, "fipePrice": 121500, "brand": "Honda", "model": "Civic Touring", "year": 2020, "mileage": 45000, "fuel": "Flex", "color": "Preto", "photos": ["https://img.olx.com.br/images/car.jpg"], "location": "São Paulo - SP", "sourceUrl": "https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-sp", "searchUrl": "https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-sp", "pageUrl": "https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-sp", "pageNumber": 1, "itemPosition": 1, "scrapedAt": "2026-09-09T00:00:00.000Z" } ``` #### Fallback when no listing markup is available The Actor does not convert an empty or unparseable public page into a guessed vehicle. It emits a diagnostic row and preserves the observed access state: ```json { "recordType": "run_diagnostic", "targetType": "olx-vehicle", "id": "diagnostic:NO_RESULTS:https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-sp", "source": "olx-cars", "url": "https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-sp", "dataAvailable": false, "sourceBlocked": false, "transport": "http", "sourceTransport": "http", "proxyUsed": false, "pageType": "search", "sourceType": "diagnostic", "error": "OLX returned no parseable public vehicle listings.", "errorCode": "NO_RESULTS", "scrapedAt": "2026-09-09T00:00:00.000Z" } ``` If earlier pages produced normal rows and a later page is blocked, those normal rows remain in the Dataset and the blocked-page diagnostic is added separately. This Actor has no detail-page enrichment fallback. #### Access or transport diagnostic ```json { "recordType": "run_diagnostic", "targetType": "olx-vehicle", "id": "diagnostic:ACCESS_BOUNDARY:https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-sp", "source": "olx-cars", "url": "https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-sp", "requestUrl": "https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-sp", "finalUrl": "https://www.olx.com.br/autos-e-pecas/carros-vans-e-utilitarios/estado-sp", "httpStatus": 403, "accessStatus": "access_boundary", "sourceBlocked": true, "transport": "http", "sourceTransport": "http", "proxyUsed": false, "dataAvailable": false, "sourceType": "diagnostic", "pageType": "search", "error": "OLX returned an anti-automation or JavaScript challenge; no bypass was attempted.", "errorCode": "ACCESS_BOUNDARY", "scrapedAt": "2026-09-09T00:00:00.000Z" } ``` Other stable diagnostic codes include `RATE_LIMITED`, `PROXY_ERROR`, `REQUEST_TIMEOUT`, `REQUEST_FAILED`, `HTTP_ERROR`, `REDIRECT_OFF_HOST`, `NON_TEXT_RESPONSE`, `RESPONSE_TOO_LARGE`, `EMPTY_RESPONSE`, `PARSE_FAILED`, and `FIXTURE_READ_FAILED`. #### `OUTPUT_SUMMARY` `OUTPUT` and `OUTPUT_SUMMARY` contain the same summary object. Counts describe Dataset rows emitted by this run; `normalCount` and `listingCount` count normal listings, while `diagnosticCount` counts diagnostic rows. ```json { "recordType": "olx-cars-run-summary", "id": "run-summary", "status": "partial", "runState": "stopped", "diagnosticOnly": false, "dataAvailable": true, "itemCount": 3, "normalCount": 2, "recordCount": 2, "listingCount": 2, "resultCount": 2, "diagnosticCount": 1, "duplicateCount": 0, "filteredOutCount": 0, "failedPages": 1, "blockedCount": 1, "noResultCount": 0, "requests": 2, "pageCount": 2, "adsLimit": 10, "maxPages": 5, "fixtureUsed": false, "fixturePath": null, "sourceTransport": "http", "transportCounts": { "http": 2, "fixture": 0 }, "proxyRequested": false, "proxyUsed": false, "completedAt": "2026-09-09T00:00:00.000Z" } ``` Possible `status` values are `success`, `partial`, `diagnostic_only`, and `empty`. `runState: "stopped"` indicates that a source boundary or failed page ended traversal; it is not a claim that data was successfully collected. You can download the dataset in various formats such as JSON, HTML, CSV, or Excel. ### Tips and advanced options #### Keep production runs bounded Start with a small `ads_limit` and `maxPages`, then increase them only when the source responds normally. `deduplicate: true` is recommended for pagination. `requestDelayMs` and a small retry budget can reduce transient failures, but they cannot make a login or anti-automation boundary public. #### Direct and proxy transport Direct HTTP is the default. When `proxyConfiguration.useApifyProxy` is true, the Actor requests one consistent Apify Proxy session (`olx_cars_session`) for the run. Dataset rows and summaries expose only `proxyUsed: true/false`; proxy URLs and credentials are never written to output. A proxy authentication failure is reported as `PROXY_ERROR` rather than being mistaken for source data. #### Local validation From the Actor directory, run `npm ci`, then `npm run check`. The checked-in fixture at `test/fixtures/list.html` exercises the active entrypoint only when `fixturePath` is explicitly supplied. A fixture pass proves parser and contract behavior; it is not proof that OLX is currently accessible from Apify Cloud. ### FAQ, support, and responsible use #### Why did the run return only diagnostics? OLX may return a rate limit, login wall, JavaScript challenge, proxy-authentication failure, empty markup, or an HTTP error. Inspect the Dataset row’s `errorCode`, `httpStatus`, `accessStatus`, `sourceBlocked`, `transport`, and `proxyUsed`, then review the run log. Do not interpret a diagnostic-only run as a successful listing result. #### Does this Actor bypass login, CAPTCHA, or anti-bot controls? No. It uses public responses and fails closed at access boundaries. It does not use stealth browsing, CAPTCHA solving, credentialed sessions, private endpoints, or fabricated fallback records. #### API and Issues Use the Actor’s **API** tab or the [Apify API documentation](https://docs.apify.com/api/v2) for integrations. Report reproducible software problems through the Actor’s **Issues** tab and include the run ID, input shape, and diagnostic code. Do not include proxy credentials or private user data in an issue. #### Privacy, legal use, and non-affiliation This Actor is an independent community tool and is not affiliated with, endorsed by, or sponsored by OLX or its affiliates. Use only publicly exposed listing information, respect OLX’s terms and robots or access policies, and comply with applicable Brazilian privacy, consumer-protection, copyright, and data-protection requirements. Do not use the Actor to collect private information, evade access controls, harass people, or make decisions that require protected or sensitive personal data. You are responsible for confirming that your collection and downstream use are lawful. The repository’s source-oriented implementation and contract checks are available in the project files. Run `npm run check` before publishing a code change. # Changelog This Actor's version history is a separate document: https://apify.com/w3crawler/olx-cars-scraper/changelog.md # Actor input Schema ## `state` (type: `string`): Two-letter Brazilian state code. ## `brand` (type: `string`): Optional public vehicle brand filter. ## `ps` (type: `integer`): Optional lower price bound. ## `pe` (type: `integer`): Optional upper price bound. ## `mileage_from` (type: `integer`): Optional lower odometer bound. ## `mileage_to` (type: `integer`): Optional upper odometer bound. ## `year_from` (type: `integer`): Optional model year lower bound. ## `year_to` (type: `integer`): Optional model year upper bound. ## `colors` (type: `array`): Optional public color labels. ## `fpdll` (type: `boolean`): Ask OLX for listings below the FIPE reference where supported. ## `search` (type: `string`): Optional free-text vehicle query. ## `ads_limit` (type: `integer`): Upper bound on vehicle records. ## `maxPages` (type: `integer`): Upper bound on result pages followed. ## `deduplicate` (type: `boolean`): Remove repeated listings across pages. ## `timeoutMs` (type: `integer`): Maximum time to wait for each public response. ## `maxBytes` (type: `integer`): Safety limit for each public response. ## `requestDelayMs` (type: `integer`): Optional bounded delay between public requests. ## `maxRequestRetries` (type: `integer`): Retry budget for transient public-request failures. ## `proxyConfiguration` (type: `object`): Optional standard Apify Proxy configuration. Proxy credentials are resolved by the SDK and never written to logs or dataset records. ## `fixturePath` (type: `string`): Optional checked-in relative fixture for local validation; it never replaces a failed live request unless explicitly supplied. ## Actor input object example ```json { "state": "sp", "fpdll": false, "ads_limit": 10, "maxPages": 5, "deduplicate": true, "timeoutMs": 30000, "maxBytes": 5000000, "requestDelayMs": 0, "maxRequestRetries": 1 } ``` # Actor output Schema ## `dataset` (type: `string`): No description ## `summary` (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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("w3crawler/olx-cars-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("w3crawler/olx-cars-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 '{}' | apify call w3crawler/olx-cars-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,w3crawler/olx-cars-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 ` 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/bwJWhQdDCAQRnCdec/builds/8YOCxb7XJbLtdBwCP/openapi.json