# CustoJusto Scraper | Portugal Classified Ads & Prices (`plum_spear/aztec-custojusto`) Actor

Scrape CustoJusto classified ads across Portugal by keyword and region. Returns title, price in EUR, category, district, county, parish, images, publication date and the ad URL as clean structured data.

- **URL**: https://apify.com/plum\_spear/aztec-custojusto.md
- **Developed by:** [Roberto Kerber](https://apify.com/plum_spear) (community)
- **Categories:** E-commerce, Lead generation, Real estate
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.15 / 1,000 results

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?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.
Actors are written with capital "A".

## 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.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## CustoJusto Scraper - Portugal Classified Ads, Prices & Listings

> Built and maintained by **Az Digital Consulting LU**.

**Scrape CustoJusto at scale.** This scraper turns [CustoJusto](https://www.custojusto.pt/) - one of Portugal's largest classified ad marketplaces - into a clean, structured data feed. Search by keyword and region and get flat JSON for every ad: **title, price in EUR, category, district, county, parish, image, publication date** and a direct URL to the listing.

No proxy setup, no HTML parsing, no account. Run it once for a market snapshot, or **schedule it daily** to track how prices and supply move over time.

***

### What does CustoJusto Scraper do?

You give it a keyword - `iphone`, `bicicleta`, `sofá`, `bmw` - and it returns every matching ad as clean, flat JSON.

Prices arrive as **numbers** (`30`, not `"30 €"`), so you can sort, filter and run calculations the moment the run finishes. Location arrives split into **district, county and parish**, so grouping by region is trivial. Category comes both as a readable name and as the portal's own ID.

It is the fastest way to **scrape CustoJusto listings** for any product or segment - whether you are tracking second-hand prices, sourcing stock to resell, doing Portuguese market research, or building a price index.

***

### Why use CustoJusto Scraper?

- **Price monitoring** - follow second-hand prices for any product across Portugal.
- **Reselling and arbitrage** - spot underpriced listings the moment they appear.
- **Market research** - measure supply by category, district and price band.
- **Competitor tracking** - watch what business sellers are listing and at what price.
- **Price indexes** - schedule daily runs and build a real price history.

***

### How to use it

1. Click **Try for free**.
2. Type a **search term** (e.g. `iphone`).
3. Optionally set a **region** (`portugal` for the whole country, or `lisboa`, `porto`, `braga`, `faro`...) and a price range.
4. Set **Max ads**.
5. Click **Start** and download the results as JSON, CSV, Excel or HTML.

***

### Input

| Field | Description |
|---|---|
| `term` | Keyword to search. Blank lists the newest ads |
| `region` | `portugal` or a district slug such as `lisboa`, `porto` |
| `priceMin` / `priceMax` | Price range in EUR (optional) |
| `maxAds` | How many ads to collect |

```json
{
  "term": "iphone",
  "region": "portugal",
  "priceMin": 100,
  "priceMax": 600,
  "maxAds": 100
}
```

***

### Output

You can download the dataset in various formats such as JSON, HTML, CSV, or Excel.

```json
{
  "id": "15864412",
  "title": "Camera IP vigilancia exterior wireless nova",
  "description": "camera IP visão nocturna IR 30LED sem fios WIFI nova em caixa...",
  "price": 30,
  "currency": "EUR",
  "adType": "sell",
  "category": "TV, Áudio e Fotografia",
  "categoryId": "3060",
  "district": "Lisboa",
  "county": "Loures",
  "parish": "Santa Iria de Azoia",
  "businessAd": false,
  "imageUrl": "https://prod-images.custojusto.pt/gallery/...jpg",
  "imageCount": 2,
  "hasVideo": false,
  "publishedAt": "2026-08-28T15:46:32Z",
  "url": "https://www.custojusto.pt/lisboa/informatica/tv-audio-fotografia/camera-ip-vigilancia-exterior--15864412"
}
```

#### Data fields

| Field | Type | Description |
|---|---|---|
| `id` | string | CustoJusto ad ID |
| `title` | string | Ad headline |
| `description` | string | Ad body text |
| `price` | number | Price in EUR |
| `currency` | string | Always `EUR` |
| `adType` | string | `sell`, `buy`, etc. |
| `category` / `categoryId` | string | Category name and portal ID |
| `district` / `county` / `parish` | string | Location breakdown |
| `businessAd` | boolean | `true` when posted by a business |
| `imageUrl` / `imageCount` | string / number | Main image and photo count |
| `hasVideo` | boolean | Whether the ad has a video |
| `publishedAt` | string | Publication timestamp (ISO 8601) |
| `url` | string | Direct link to the ad |

***

### Pricing

**Pay per event: $0.15 per 1,000 ads returned, plus a minimal actor-start event.**

No subscription, no monthly minimums - you only pay for the data you actually extract. New Apify users get free monthly platform credits to test at no cost before scaling.

***

### Tips

- Narrow searches run faster and cost less. A keyword plus a district is the sweet spot.
- Leave `term` blank to pull the newest ads across a region - useful for a daily "what's new" feed.
- Schedule a daily run on the same term to build a price history you can chart.

***

### FAQ

**Is scraping CustoJusto legal?**
This Actor collects only **publicly available listing data** - the same information any visitor sees without logging in. It deliberately collects **no personal data**: seller names, phone numbers and emails are never returned, even though some appear on the page. You remain responsible for how you use the data; review the target site's terms and applicable law (including GDPR) for your use case.

**Do I need a proxy?**
No. The Actor reads the portal's public page data directly.

**Why did I get fewer ads than I asked for?**
The search simply matched fewer ads, or your price filter excluded the rest. Try a broader term or a wider price range.

**Can I get another Portuguese marketplace?**
Yes - open an issue on the **Issues** tab. We also publish an **OLX Europe** scraper covering Portugal, Poland, Romania, Bulgaria, Ukraine and Kazakhstan.

***

### Support

Found a bug or need a field that is not here? Open an issue on the **Issues** tab of this Actor. Issues are answered.

# Actor input Schema

## `term` (type: `string`):

Keyword to search on CustoJusto, e.g. 'iphone', 'bicicleta', 'sofa', 'bmw'. Leave blank to list the newest ads.

## `region` (type: `string`):

Region slug. Use 'portugal' for the whole country, or a district such as 'lisboa', 'porto', 'braga', 'faro', 'coimbra'.

## `priceMin` (type: `integer`):

Only return ads at or above this price. Optional.

## `priceMax` (type: `integer`):

Only return ads at or below this price. Optional.

## `maxAds` (type: `integer`):

Maximum number of ads to scrape.

## Actor input object example

```json
{
  "term": "iphone",
  "region": "portugal",
  "maxAds": 100
}
```

# Actor output Schema

## `dataset` (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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "term": "iphone"
};

// Run the Actor and wait for it to finish
const run = await client.actor("plum_spear/aztec-custojusto").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 = { "term": "iphone" }

# Run the Actor and wait for it to finish
run = client.actor("plum_spear/aztec-custojusto").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 '{
  "term": "iphone"
}' |
apify call plum_spear/aztec-custojusto --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,plum_spear/aztec-custojusto"
        }
    }
}

```

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/FbL1AfQKfvkph4gNs/builds/7vGeLRVtzrSeSNGQL/openapi.json