OLX Brasil Carros Data Scraper

What does OLX Brasil Carros Data Scraper do?

OLX Brasil Carros Data Scraper collects vehicle listings that are exposed on public OLX Brasil 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 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

{
  "state": "sp",
  "ads_limit": 10
}

Filtered search input

{
  "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

{
  "state": "sp",
  "ads_limit": 10,
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": ["RESIDENTIAL"],
    "apifyProxyCountry": "BR"
  }
}

Explicit local QA fixture input

{
  "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

{
  "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:

{
  "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

{
  "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.

{
  "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 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.