# Complete Guide: How to Scrape Webmotors Car Listings Using Python

This complete guide to Webmotors Brazil Scraper shows how to run a [webmotors.com.br](http://webmotors.com.br) scraper from Python through the Apify API and get back typed listing rows: asking price in Brazilian reais, fabrication and model year, mileage in kilometres, transmission, body type, colour, engine, horsepower, city, state, seller type and the dealership's trade name.

Webmotors is a Brazilian vehicle classifieds site. Its listings come from the site's search.

You will automate the extraction with the **Webmotors Brazil Scraper** Apify Actor (`reventadata/webmotors-scraper`). Prerequisites are minimal: Python 3.11+, the official `apify-client` package, and an Apify API token. Estimated time to complete: about 30 minutes. The sample row in this guide is a sample from a capture dated 2026-10-17, parsed with the Actor's own code; this guide quotes no run.

---

## TL;DR

In this tutorial, you'll learn to start the Webmotors Brazil Scraper Apify Actor from Python, wait for the run, and read its dataset. Key steps: install `apify-client`, export `APIFY_API_TOKEN`, put make and model searches in `searchQueries` plus optional filters (`condition`, year, price and mileage ranges, `state`, `transmission`, `sortBy`), call the Actor, then read the items from `run.default_dataset_id`.

Expected outcome: a JSON list of Webmotors car listings with price, years, kilometres and seller, ready for a spreadsheet, database or analysis script.

The Actor is at [apify.com/reventadata/webmotors-scraper](https://apify.com/reventadata/webmotors-scraper).

---

## Prerequisites and setup

To follow this tutorial, you will need:

1. Python 3.11+ installed locally (`apify-client` 3.x requires it).
2. The Apify API client for Python.
3. An Apify account and API token.

Sign up for an Apify account first. Apify Console is the web interface where runs, datasets and tokens are managed; your token is under the **Integrations** tab. Keep the token out of any file you commit: the snippets below read it from the environment, so the same script runs on a laptop, a server or in CI. The platform documentation starts at [docs.apify.com](https://docs.apify.com/).

Install the client:

```bash
pip install "apify-client~=3.0"
```

Set your API token in your environment:

```bash
export APIFY_API_TOKEN="your_apify_token_here"
```

---

## Understanding Webmotors Brazil Scraper

### How it works behind the scenes

1. **A search path per query.** Each entry in `searchQueries` becomes a Webmotors search path: the first word is the make, the rest is the model (`"porsche 911"` becomes `/carros/estoque/porsche/911`). `condition` picks the used-only or new-only section, and the ranges, `state` and `transmission` become query parameters on that URL.
2. **The site's search.** The Actor searches the site with that URL, 24 cars per page, with the sort order you chose.
3. **Proxy by default.** The default `proxyConfiguration` is already set.
4. **Rows, checked twice.** Each car becomes one row. The Actor checks every row against your filters again, skips listing ids it already saved, and stops a query at `maxItems` or at a page with fewer than 24 cars.

### Limitations to be aware of

- Cars only: every search path targets the site's car section.
- No detail pages: the row holds what the search result carries, no description or full photo gallery.
- Private sellers get no name in the row; the dealer name is filled only for dealerships.

---

## Step-by-step walkthrough

### Step 1: Initialize the client and define inputs

Create the client from your environment token and describe the search. This example asks for Porsche 911 listings:

```python
import os
from apify_client import ApifyClient

# 1. Initialize ApifyClient with token from environment
client = ApifyClient(os.environ["APIFY_API_TOKEN"])

# 2. Define the search: Porsche 911 listings, up to 20 rows
run_input = {
    "searchQueries": ["porsche 911"],
    "maxItems": 20,
}
```

*(Note: the sample row in this guide is one Porsche 911 listing captured from Webmotors on 2026-10-17 and parsed with the Actor's code. It is not the output of a run of this input.)*

Two more configurations that use the same fields:

- Used automatic Toyota Corolla in São Paulo state, 2020 to 2024, under 60,000 km: `{"searchQueries": ["toyota corolla"], "condition": "used", "minYear": 2020, "maxYear": 2024, "maxMileageKm": 60000, "state": "SP", "transmission": "automatic", "maxItems": 100}`.
- Several models, cheapest first: `{"searchQueries": ["honda civic", "toyota corolla"], "sortBy": "lowest_price", "maxItems": 200}`.

The first one becomes this search URL, built by the Actor's own code: `https://www.webmotors.com.br/carros-usados/estoque/toyota/corolla?tipoveiculo=carros&anode=2020&anoate=2024&kmate=60000&estadocidade=sp&cambio=autom%C3%A1tica`.

### Step 2: Trigger execution on Apify

`.call(run_input=run_input)` starts the run and waits for it to finish:

```python
# 3. Start the Actor run and wait for it to complete
print("Starting Webmotors extraction...")
run = client.actor("reventadata/webmotors-scraper").call(run_input=run_input)
if run is None or run.status != "SUCCEEDED":
    status = run.status if run else "unknown"
    raise SystemExit(f"Run did not succeed (status: {status}).")

# 4. Fetch the resulting dataset items
dataset = client.dataset(run.default_dataset_id).list_items().items

print(f"Extraction complete! Retrieved {len(dataset)} listings.\n")
```

### Step 3: Iterate and process dataset items

```python
for item in dataset:
    price = item.get("price")
    km = item.get("odometerKm")
    mileage = f"{km:,} km" if km is not None else "not stated"

    print(f"Listing: {item.get('title')}")
    if not price:
        print("  Price: not listed")
    else:
        print(f"  Price: R$ {price:,.0f}")
    print(f"  Year: {item.get('yearFabrication')}/{item.get('yearModel')}")
    print(f"  Mileage: {mileage}")
    print(f"  Seller: {item.get('sellerType')} ({item.get('dealerName') or 'no dealer name'})")
    print(f"  Location: {item.get('city')}, {item.get('state')}")
    print("-" * 50)
```

### Step 4: Inspect a real row

Here is one row, a sample from a capture dated 2026-10-17, parsed with the Actor's own code. A saved row also carries `scrapedAt`, added at save time:

```json
{
  "itemId": "78266189",
  "title": "PORSCHE 911 4.0 24V H6 GASOLINA GT3 MANUAL",
  "url": "https://www.webmotors.com.br/comprar/porsche/911/porsche-911-40-24v-h6-gasolina-gt3-manual/78266189",
  "price": 2399000.0,
  "make": "PORSCHE",
  "model": "911",
  "version": "4.0 24V H6 GASOLINA GT3 MANUAL",
  "yearFabrication": 2025,
  "yearModel": 2026,
  "odometerKm": 1563,
  "condition": "used",
  "transmission": "Manual",
  "color": "Prata",
  "doors": "2",
  "bodyType": "Cupê",
  "engineSize": "4.0",
  "horsePower": "510 cv",
  "sellerType": "dealership",
  "dealerName": "STUTTGART PORSCHE - BLUMENAU",
  "city": "Blumenau",
  "state": "Santa Catarina (SC)",
  "imageUrl": "https://image.webmotors.com.br/_fotos/AnuncioUsados/div/2026/202609/20260924/porsche-911-4-0-24v-h6-gasolina-gt3-manual-wmimagem15471201988.webp",
  "attributes": [
    "Aceita troca",
    "Único dono",
    "IPVA pago",
    "Licenciado"
  ],
  "matchedKeyword": "porsche 911"
}
```

### Step 5: Export the data

Apify datasets export as JSON, CSV, XML, Excel, HTML table, RSS or JSONL, from Apify Console or through the API.

---

## Understanding your data

Field by field:

- `itemId`, `url`: the Webmotors listing id, and a link the Actor builds from make, model, title and id.
- `title`, `make`, `model`, `version`: as the site writes them (in capitals, in the sample).
- `yearFabrication`, `yearModel`: Webmotors gives both. The sample was built in 2025 as a 2026 model.
- `price`: asking price in reais, a number; `0.0` when the listing has no numeric price, so treat 0 as "not listed".
- `odometerKm`: kilometres; the sample, listed `used`, shows 1,563 km.
- `condition`: `used` or `new`, from the listing type.
- `transmission`, `color`, `doors`, `bodyType`, `engineSize`, `horsePower`: as the site writes them, in Portuguese (`Prata` is silver, `Cupê` coupé).
- `sellerType`, `dealerName`: `dealership` or `private`, and the trade name for dealerships only.
- `city`, `state`: where the seller is; in the sample, `state` is `Santa Catarina (SC)`, name plus two-letter code.
- `imageUrl`, `attributes`: one photo URL, and feature tags such as "Único dono" (single owner) or "IPVA pago" (annual vehicle tax paid).
- `matchedKeyword`, `scrapedAt`: the query that found the row and when it was built.

---

## Working with the API

`call()` holds the connection until the run ends and returns the `Run` object. For longer runs or a job queue, `client.actor("reventadata/webmotors-scraper").start(run_input=run_input)` returns as soon as the run is created; keep its id and read the run later. Either way, the dataset id is the run's `default_dataset_id`, and `client.dataset(...).list_items().items` returns the rows. `list_items()` makes one API call and may not return every item of a large dataset; `iterate_items()` makes as many calls as it needs to return them all.

Authentication is the API token from the **Integrations** tab in Apify Console. Keep it in an environment variable, as the snippet does, and never in the code you commit.

For event-driven pipelines, add a webhook on the `ACTOR.RUN.SUCCEEDED` event. Apify then POSTs to your endpoint, and the payload's `resource` is the run details, which carries `defaultDatasetId`. Your handler reads the rows from that dataset without polling.

Error handling: the Actor ends a run that saves no rows as FAILED when a page is blocked or cannot be read, so check `run.status` before reading the dataset, as the snippet does. A value outside a fixed list (`condition`, `transmission`, `sortBy`) is refused before the run starts: the call returns an API error and the Actor is not started. `state` is free text and is not checked that way.

Scheduling: save an input as a task and attach an Apify schedule. Schedules run Actors and tasks at times set by a cron expression.

---

## Advanced usage patterns

### 1\. Several models in one run

`searchQueries` takes a list, and the Actor walks it in order. `maxItems` is a total across all queries, not a per-query limit, so the first search can fill the whole budget. For an even split, start one run per model with `start()`, keep a map from run id to model, then read each dataset.

### 2\. Make and model only, no version words

The first word is the make and the rest is the model, so `"honda civic hybrid"` asks for the model path `honda/civic-hybrid`. Webmotors does not recognise it and answers with every Honda; the Actor skips that query with a warning instead of pushing those rows. `requireKeywordMatch: true` still keeps only rows whose title holds every word of the query, ignoring case and accents.

### 3\. Same listing, two queries

The Actor keeps one row per listing id across the run. When two queries overlap, the row carries the `matchedKeyword` of the first query that found it.

### 4\. Regional comparisons

Run the same query once per `state` (`SP`, `RJ`, `MG`, ...) and compare the datasets. The code goes into the search URL, lowercased, as `estadocidade`.

### 5\. Monitoring

Pair a schedule with a webhook on `ACTOR.RUN.SUCCEEDED` to load new rows, and one on `ACTOR.RUN.FAILED` to alert you. The failure webhook catches runs that saved no rows because a page was blocked or unreadable; a search that loads normally but matches nothing ends `SUCCEEDED` with an empty dataset and a status message, so it does not fire it (check the dataset item count or status message).

---

## Troubleshooting guide

- **Run FAILED, "0 results for queries ...":** the run was blocked or could not read a page. If the filters were too narrow or a query did not match a make and model, pages that load normally end `SUCCEEDED` with an empty dataset and a status message instead.
- **Run not started:** `condition`, `transmission` and `sortBy` take fixed values; anything else is refused before the run starts.
- **A two-word make:** the first query word is always the make, so `"land rover discovery"` puts "land" in the make slot. Check the first rows of such a query.
- **Rows missing under a filter:** with `maxMileageKm` set, rows without an odometer reading are dropped; with a year range, rows without a year are dropped.
- **A query stopped early:** a page that keeps failing ends that query; the log line `Aborting query` names it and the error.
- **Reading the log:** the run's summary line reads `Webmotors run finished: pushed N rows. Rejections summary: {...}`, a count of dropped rows per reason (a filter, a duplicate id, or a listing it could not parse). From Python: `client.log(run.id).get()`. For help, use the Actor's Store page.

---

## Best practices

1. **Filter on the site.** Use `condition`, the ranges, `state` and `transmission`; they go into the search URL, so you read fewer pages.
2. **Set** `maxItems` **to what you need.** The default is 100; use 20 while you test.
3. **Pick a fixed sort for repeat runs**, such as `lowest_price` or `newest_year`, so two datasets are sorted the same way.
4. **Treat a price of 0 as missing**, not as a free car.
5. **Schedule, don't loop.** A schedule reruns a saved task on a cron expression.
6. **Start with the default proxy.** Change `proxyConfiguration` only if you have measured another one yourself.

---

## Pricing

For current pricing and details, see the [Store page](https://apify.com/reventadata/webmotors-scraper).

---

## Conclusion and next steps

With Webmotors Brazil Scraper and the Apify Python client, a [webmotors.com.br](http://webmotors.com.br) search becomes a list of typed rows: price in reais, both years, kilometres, specs, location and seller. Start with a small `maxItems`, check the fields, then schedule the search and compare datasets over time.

Try Webmotors Brazil Scraper yourself and let me know what you build!

*About the author: reventadata builds and maintains marketplace scrapers on the Apify Store.*

---

## Resources

- [Webmotors Brazil Scraper on Apify Store](https://apify.com/reventadata/webmotors-scraper)
- [Apify Python Client Documentation](https://docs.apify.com/api/client/python/docs)
- [Apify schedules](https://docs.apify.com/actors/running/schedules)
- [Apify webhook actions](https://docs.apify.com/integrations/webhooks/actions)
