# CustoJusto Scraper - Portugal Classifieds, Any Category (`rastriq/custojusto-scraper`) Actor

Scrape any custojusto.pt search or category URL: cars, real estate, phones, furniture and more. Price in EUR, category, attributes, location, private or professional seller, photo. No login.

- **URL**: https://apify.com/rastriq/custojusto-scraper.md
- **Developed by:** [Rastriq — Structured data from the world](https://apify.com/rastriq) (community)
- **Categories:** E-commerce, Real estate
- **Features:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 ad returneds

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

## CustoJusto Scraper

**CustoJusto Scraper** extracts classified ads of **any category** from custojusto.pt, Portugal's general classifieds site: cars and motorbikes, apartments and houses, phones, computers, furniture, animals, sports gear and more. Paste the URL of any search you made on the site, with your filters, and get a clean, de-duplicated dataset: price in EUR, category, category-specific attributes, location, private or professional seller and photo. Export to JSON, CSV or Excel; no browser, no login.

> Part of the Rastriq marketplace family: the car fields (`make`, `model`, `year`, `km`, `price`, `fuel_type`, `gearbox`, `city`, `url`, `source`...) use the same names as the other Rastriq car scrapers, so datasets from several countries stack without re-mapping.

### How to use CustoJusto Scraper

1. Go to custojusto.pt, pick a category and/or type a keyword, and apply the filters you need (location, price, sorting...).
2. Copy the URL from your browser's address bar.
3. Open **CustoJusto Scraper** on Apify, paste the URL in **CustoJusto search URLs** (add as many as you like).
4. Set **Max pages per URL** (40 ads per page) and **Max items**. The prefill (1 page, 20 items) is a cheap first test.
5. Click **Start** and download the dataset from the **Output** tab or the API.

URLs that work:

| What you want | Example URL |
|---|---|
| Keyword, all Portugal | `https://www.custojusto.pt/portugal/q/iphone` |
| Keyword in a district | `https://www.custojusto.pt/lisboa/q/bicicleta` |
| A category | `https://www.custojusto.pt/portugal/imobiliario` |
| A sub-category in a district | `https://www.custojusto.pt/lisboa/imobiliario/apartamentos` |
| Category + price filter | `https://www.custojusto.pt/portugal/informatica/telefones-acessorios?ps=100&pe=300` |
| Keyword inside a category | `https://www.custojusto.pt/portugal/veiculos/carros-usados/q/golf` |
| Start on a later page | add `o=5` to the URL |

No URL at hand? Leave **CustoJusto search URLs** empty and use the **Keyword** shortcut, or the **Used-car shortcut** (make, fuel, year, price). With everything empty the Actor returns the newest ads of the whole site.

Typical uses:

- Track asking prices of second-hand phones, consoles, bikes and tools
- Monitor rental and sale listings in a district or municipality
- Find private-seller cars that dealer marketplaces such as StandVirtual do not list
- Compare professional and private supply with `is_professional` and `seller_name`

### Input example

```json
{
  "startUrls": [
    { "url": "https://www.custojusto.pt/portugal/q/iphone" },
    { "url": "https://www.custojusto.pt/lisboa/imobiliario/apartamentos" }
  ],
  "maxPages": 5,
  "maxItems": 300,
  "proxyConfiguration": { "useApifyProxy": true }
}
```

| Parameter | Type | Default | Description |
|---|---|---|---|
| `startUrls` | array | — | CustoJusto search or category URLs, with any filters. Single ad pages are rejected. When set, the shortcut fields are ignored. |
| `searchQuery` | string | — | Shortcut when no URL is given: keyword search across Portugal. |
| `minPrice` / `maxPrice` | integer | — | Shortcut price range (EUR), applied to the keyword or car shortcut. |
| `make`, `fuel`, `minYear`, `maxYear` | string / integer | — | Used-car shortcut. Any of them limits the run to the used-car category. |
| `maxPages` | integer | `3` | Result pages to read **per URL** (40 ads per page). |
| `maxItems` | integer | `50` | Maximum unique ads in the whole run. |
| `proxyConfiguration` | object | Apify Proxy | Datacenter proxy is enough. On HTTP 403 the Actor rotates proxy sessions; if still blocked, use RESIDENTIAL with country `PT`. |

### What data you get

One flat record per ad. Fields the source does not provide are `null`; nothing is guessed.

| Field | Type | Description |
|---|---|---|
| `id` | string | CustoJusto ad ID. |
| `title` | string | Ad title as shown in the results list. |
| `description` | string | First ~200 characters of the ad text. In private sellers' ads, phone numbers and emails are replaced by `[phone]` / `[email]`. |
| `price` | integer | Asking price in whole EUR; `null` when the ad has no price. |
| `currency` | string | Always `EUR`. |
| `category_id`, `category_name`, `category_path` | string | Category of the ad (for cars `category_name` is the body type). |
| `ad_type` | string | Ad type reported by the site (`sell`, ...). |
| `attributes` | object | Category-specific attributes from the site, e.g. `{"rooms": "T2", "size": "55m²"}`. |
| `make`, `model`, `version` | string | Cars only, parsed from the title with the site brand list. |
| `year`, `fuel_type`, `gearbox` | | Vehicles: registration year, fuel, transmission. |
| `km`, `hp`, `origin` | | Always `null` (only on the ad page). Kept for compatibility with the Rastriq car family. |
| `typology`, `area_m2` | string / integer | Real estate: typology (T0–T5+) and area. |
| `city`, `region`, `parish` | string | Municipality, district and parish. |
| `is_professional` | boolean | `true` for company ads, `false` for private sellers. |
| `seller_name`, `seller_shop_url` | string | Business name and shop page, **professional ads only**; private sellers are never named. |
| `img_url`, `image_count`, `has_video` | | Main photo, number of photos, video flag. |
| `url` | string | Direct link to the ad. |
| `search_url` | string | The start URL that returned the ad. |
| `quality_flags` | array | Warnings, rows are never dropped: `price_missing`, `title_truncated`, `make_unrecognised`. |
| `source`, `scraped_at`, `ext_listed_at` | string | Always `custojusto`; extraction time; publication/refresh time from the site. |

The **Output** tab offers four views: Ads, Vehicles, Real estate and Full details.

### Output example

```json
{
  "id": "45104051",
  "title": "Duplex T2 Duplex Mafra",
  "description": "Moradia T1+1 com vista campo, no centro de aldeia, a 15 km da Ericeira...",
  "price": 350000,
  "currency": "EUR",
  "category_id": "1020",
  "category_name": "Apartamentos",
  "category_path": "imobiliario/apartamentos",
  "ad_type": "sell",
  "attributes": { "rooms": "T2", "size": "55m²" },
  "make": null, "model": null, "version": null, "year": null,
  "km": null, "hp": null, "fuel_type": null, "gearbox": null, "origin": null,
  "typology": "T2",
  "area_m2": 55,
  "city": "Mafra",
  "region": "Lisboa",
  "parish": "Encarnação",
  "is_professional": true,
  "seller_name": "A Casa das Casas",
  "seller_shop_url": "https://www.custojusto.pt/loja/a-casa-das-casas",
  "img_url": "https://prod-images.custojusto.pt/gallery/3485331720-duplex-t2-duplex-mafra.jpg",
  "image_count": 5,
  "has_video": false,
  "url": "https://www.custojusto.pt/lisboa/imobiliario/apartamentos/duplex-t2-duplex-mafra-45104051",
  "search_url": "https://www.custojusto.pt/lisboa/imobiliario/apartamentos",
  "quality_flags": [],
  "source": "custojusto",
  "scraped_at": "2026-10-25T09:00:00+00:00",
  "ext_listed_at": "2026-10-25T01:00:01Z"
}
```

A `SUMMARY` record in the key-value store reports, for each URL, the pages read, ads delivered, the number of ads the site announced and why scraping stopped (last page, maxPages, maxItems, blocked...).

### Pricing

Pay-per-event: **$0.002 per run start** plus **$0.0015 per ad** ($1.50 per 1,000). You only pay for unique ads delivered to the dataset; an ad found by two of your URLs is delivered and charged once.

| Run | Cost |
|---|---|
| 20 ads (prefill) | $0.032 |
| 50 ads (default) | $0.077 |
| 1,000 ads | $1.502 |
| 10,000 ads | $15.002 |

### Limitations

- Data comes from the results list; `km`, `hp`, `origin` and the full description are only on the ad page, which this Actor does not open to keep runs fast and cheap.
- Long titles are cut by the site in the results list; those rows carry `title_truncated`.
- `make` / `model` / `version` are parsed from free-text titles and can be imperfect; unknown brands stay `null` and get `make_unrecognised`.
- If a pasted category path does not exist, CustoJusto silently turns it into a text search. The Actor detects this, skips that URL (so you are not charged for unrelated ads) and explains it in the log and `SUMMARY`.
- Results are sorted newest first, so on long runs a few ads can shift between pages; duplicates are removed.
- Promoted gallery ads are not included.

### FAQ

**Is it legal to scrape custojusto.pt?** The Actor reads publicly visible result pages at a low request rate, without logging in or bypassing access controls. It never exports private sellers' names, and phone numbers or emails that private sellers type into the ad text are masked. Check the website terms and make sure your use of the data complies with the law that applies to you, including data protection rules.

**Does it need a proxy?** The default Apify datacenter proxy is enough in normal runs. On HTTP 403 the Actor rotates proxy sessions automatically; if it is still blocked, choose Apify Proxy RESIDENTIAL with country `PT`.

**Can I scrape a whole category?** Yes: set `maxPages` high enough (the log shows how many pages the site announces) and raise `maxItems`. The default run timeout is one hour.

**Can I schedule it or call it from my code?** Yes: Apify schedules, the API, or integrations such as Make, Zapier or Google Sheets.

**Something broke or a field is missing?** custojusto.pt changes its pages from time to time. Open an issue on the Actor page and include the run link.

### Related Actors

| Country | Actor | Notes |
|---|---|---|
| Portugal | [StandVirtual Scraper](https://apify.com/rastriq/standvirtual-scraper) | dealer-heavy car marketplace |
| Spain | [Coches.net Scraper](https://apify.com/rastriq/cochesnet-spain) | Spain's top car marketplace |
| Turkey | [Arabam.com Scraper](https://apify.com/rastriq/arabam-scraper) | used cars |
| Switzerland | [Comparis.ch Scraper](https://apify.com/rastriq/comparis-scraper) | with comparis market price |
| Poland | [OtoMoto Scraper](https://apify.com/rastriq/otomoto-scraper) | largest Polish car marketplace |
| Romania | [Autovit Scraper](https://apify.com/rastriq/autovit-scraper) | Romanian car marketplace |

# Changelog

This Actor's version history is a separate document: https://apify.com/rastriq/custojusto-scraper/changelog.md

# Actor input Schema

## `startUrls` (type: `array`):

Any search or category page of custojusto.pt, with the filters you applied on the site (price, location, category, keyword, sorting). Examples:<br><code>https://www.custojusto.pt/portugal/q/iphone</code><br><code>https://www.custojusto.pt/lisboa/imobiliario/apartamentos</code><br><code>https://www.custojusto.pt/portugal/veiculos/carros-usados?ps=5000\&pe=20000</code><br>Single ad pages are not accepted. When set, the shortcut fields below are ignored.

## `searchQuery` (type: `string`):

Used only when no start URL is given: searches the whole of Portugal for this keyword, for example <code>bicicleta</code> or <code>iphone 13</code>.

## `minPrice` (type: `integer`):

Used only when no start URL is given. Lowest asking price in euros.

## `maxPrice` (type: `integer`):

Used only when no start URL is given. Highest asking price in euros.

## `make` (type: `string`):

Used only when no start URL is given. Restricts the search to used cars of this brand. Slug as in the CustoJusto URL, lowercase: <code>bmw</code>, <code>renault</code>, <code>mercedes-benz</code>.

## `fuel` (type: `string`):

Only used cars with this fuel type.

## `minYear` (type: `integer`):

Oldest registration year, for example <code>2018</code>.

## `maxYear` (type: `integer`):

Newest registration year, for example <code>2024</code>.

## `maxPages` (type: `integer`):

Result pages to read for each search URL (40 ads per page). Big categories have hundreds of pages; use 1 for a quick test.

## `maxItems` (type: `integer`):

Maximum number of unique ads to return in the whole run. Example: <code>20</code> costs about $0.032.

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

Apify datacenter proxy is enough for normal runs. On HTTP 403 the Actor rotates proxy sessions automatically; if it is still blocked, select <b>RESIDENTIAL</b> with country <code>PT</code>.

## Actor input object example

```json
{
  "startUrls": [
    {
      "url": "https://www.custojusto.pt/portugal/q/iphone"
    }
  ],
  "fuel": "",
  "maxPages": 1,
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `listings` (type: `string`):

Ads extracted from custojusto.pt.

## `summary` (type: `string`):

Per-URL pages read, ads pushed, source totals and stop reason.

# 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 = {
    "startUrls": [
        {
            "url": "https://www.custojusto.pt/portugal/q/iphone"
        }
    ],
    "maxPages": 1,
    "maxItems": 20,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("rastriq/custojusto-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 = {
    "startUrls": [{ "url": "https://www.custojusto.pt/portugal/q/iphone" }],
    "maxPages": 1,
    "maxItems": 20,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("rastriq/custojusto-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 '{
  "startUrls": [
    {
      "url": "https://www.custojusto.pt/portugal/q/iphone"
    }
  ],
  "maxPages": 1,
  "maxItems": 20,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call rastriq/custojusto-scraper --silent --output-dataset

```

## MCP server setup

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