# PagineGialle.it Business Directory Scraper (`ayrtondavoli97/paginegialle-it-business-directory-scraper`) Actor

Scrape public business listings from PagineGialle.it. Search by Italian city and business category, collect names, phone numbers, addresses, profile URLs, websites and contact links when available, then export to JSON, CSV or Excel.

- **URL**: https://apify.com/ayrtondavoli97/paginegialle-it-business-directory-scraper.md
- **Developed by:** [Francesco Ayrton Davoli](https://apify.com/ayrtondavoli97) (community)
- **Categories:** AI, Other, E-commerce
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet

## Pricing

from $1.50 / 1,000 results

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/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
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.

In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):

```bash
npm install apify-client
```

In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):

```bash
pip install apify-client
```

In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):

````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash

In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).

If your project is in a different language, use 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

## PagineGialle.it Business Directory Scraper

Extract structured public business listings from PagineGialle.it, one of Italy's main online directories for companies, professionals, local shops, restaurants, services, and public-facing business profiles.

This Apify Actor lets you search Italian businesses by category and city, collect directory listing data, and export the results as JSON, CSV, or Excel.

It is designed for market research, local business mapping, sales preparation, competitor analysis, CRM preparation, and structured directory data collection.

### What this Actor does

The Actor searches PagineGialle.it using business categories and Italian cities, then extracts structured data from public directory result pages.

Typical searches include:

- construction companies in Bari
- accountants in Milan
- notaries in Turin
- pastry shops in Rome
- Japanese restaurants in Naples
- doctors in Bologna
- wine shops in Florence

You can run a single category and city, or combine multiple categories and multiple cities in one run.

Example:

```text
7 categories x 3 cities = 21 automatic searches
````

### Main use cases

#### Italian business directory data collection

Collect structured information from PagineGialle.it listings and turn public directory pages into usable datasets.

Useful for:

- business directories
- local datasets
- regional company lists
- category-based company research
- Italian market databases

#### Local market research

Analyze which businesses are present in specific cities and sectors.

Examples:

- how many accountants are listed in Bari
- how many pastry shops are listed in Milan
- how many medical practices are listed in Turin
- which local areas contain more construction companies
- which business categories are more visible in a city

#### Competitor and territory mapping

Map local competitors, business density, and local service coverage by category and city.

Useful for agencies, consultants, franchising research, local sales teams, and companies planning expansion in Italy.

#### Sales and CRM preparation

Create structured business lists before starting manual verification, CRM imports, phone-based workflows, or local business research.

The Actor can collect public business names, phone numbers, addresses, profile URLs, available websites, and available contact links when present in the directory listing.

#### Local SEO and digital presence research

Analyze local business visibility and compare listings across industries and cities.

Useful for:

- SEO agencies
- local marketing agencies
- web agencies
- consultants selling websites or digital services
- local visibility analysis

#### Data analysis and BI workflows

Export the dataset and analyze it in spreadsheets, SQL databases, Python scripts, CRM systems, or BI tools.

Possible analysis:

- businesses by city
- businesses by category
- phone availability
- website availability
- contact link availability
- business profile coverage
- local competitor density

### Extracted data

The Actor extracts structured fields from public PagineGialle.it search result listings.

| Field | Description |
|---|---|
| `id` | Listing identifier when available |
| `name` | Business or professional name |
| `category` | Category associated with the listing/search |
| `phone` | Public phone number when available |
| `email` | Email field, if publicly available in the listing data; often empty |
| `website` | Business website when available and detected as a real external website |
| `contactUrl` | Best available external contact link, such as website or WhatsApp |
| `whatsappUrl` | WhatsApp contact link when available |
| `address` | Business address or location text |
| `city` | Search city |
| `province` | Province field when available |
| `postalCode` | Postal code field when available |
| `latitude` | Latitude when available |
| `longitude` | Longitude when available |
| `rating` | Public rating when available |
| `reviewCount` | Review count when available |
| `imageUrl` | Listing image URL when available |
| `facebook` | Facebook URL when available |
| `instagram` | Instagram URL when available |
| `profileUrl` | Public PagineGialle.it profile URL |
| `searchCategory` | Category used for the search |
| `searchCity` | City used for the search |
| `searchUrl` | Search URL used by the Actor |
| `source` | Source website name |
| `scrapedAt` | ISO timestamp of the extraction |

Data availability depends on what is publicly visible in PagineGialle.it result pages. Phone numbers are often available. Websites, WhatsApp links, ratings, images, and other fields depend on the individual listing.

### Product positioning

This is a PagineGialle.it business directory scraper.

It is not positioned as a guaranteed email extraction tool or as a full company intelligence provider. The main value is collecting structured public business directory listings by category and city.

### Input options

#### Categories

Select one or more business categories from the input dropdown, or provide custom categories manually.

Examples:

- `impresa-edile`
- `commercialista`
- `notaio`
- `trattoria`
- `pasticceria`
- `sushi`
- `medico`
- `gelateria`
- `enoteca`

#### Cities

Select one or more Italian cities from the dropdown, or provide custom cities manually.

Examples:

- `bari`
- `milano`
- `torino`
- `roma`
- `napoli`
- `bologna`
- `firenze`

#### Max results

Set the maximum number of records to collect for each category and city combination.

Examples:

- `100` for a quick test
- `500` for medium runs
- `2000` for larger category/city runs

#### Filters

Optional filters are available:

- only listings with phone number
- only listings with website
- only listings with email

Use filters carefully. If a strict filter is enabled and the selected field is not commonly available for that category, the run can return fewer results.

#### Proxy

Apify Proxy is recommended for larger runs, multiple cities, and multiple categories.

#### Advanced search input

Advanced users can provide raw search combinations:

```json
[
  { "what": "commercialista", "where": "bari" },
  { "what": "notaio", "where": "milano" },
  { "what": "impresa-edile", "where": "torino" }
]
```

When advanced searches are provided, they override the standard category/city dropdown combinations.

### Output formats

Results are saved to the default Apify dataset and can be exported as:

- JSON
- CSV
- Excel
- XML
- RSS
- HTML

The most common formats for business workflows are CSV and Excel.

### Example input

```json
{
  "categories": [
    "commercialista",
    "notaio",
    "impresa-edile"
  ],
  "cities": [
    "bari",
    "milano",
    "torino"
  ],
  "maxResults": 500,
  "onlyWithEmail": false,
  "onlyWithPhone": false,
  "onlyWithWebsite": false,
  "useApifyProxy": true,
  "customCategories": [],
  "customCities": [],
  "searches": []
}
```

### Example output

```json
{
  "id": "dfb3328c-2b7f-4715-a79f-ca2f52c3806a",
  "name": "Example Business Name",
  "category": "commercialista",
  "phone": "080 0000000",
  "email": "",
  "website": "https://www.example-business.it",
  "contactUrl": "https://www.example-business.it",
  "whatsappUrl": "",
  "address": "Via Example, 10 - 70100 Bari (BA)",
  "city": "bari",
  "rating": 4.5,
  "profileUrl": "https://www.paginegialle.it/example-business",
  "searchCategory": "commercialista",
  "searchCity": "bari",
  "searchUrl": "https://www.paginegialle.it/ricerca/commercialisti/bari",
  "source": "paginegialle.it",
  "scrapedAt": "2026-06-09T17:12:06.240Z"
}
```

### Category examples: Italian to English

| Italian category | English meaning |
|---|---|
| `impresa-edile` | Construction company |
| `commercialista` | Accountant / tax consultant |
| `notaio` | Notary |
| `trattoria` | Trattoria / restaurant |
| `pasticceria` | Pastry shop |
| `sushi` | Sushi / Japanese restaurant |
| `medico` | Doctor / medical practice |
| `gelateria` | Ice cream shop |
| `enoteca` | Wine shop / wine bar |
| `ristorante` | Restaurant |
| `pizzeria` | Pizzeria |
| `bar` | Bar / cafe |
| `dentista` | Dentist |
| `farmacia` | Pharmacy |
| `parrucchiere` | Hair salon |
| `estetista` | Beauty salon |
| `fisioterapista` | Physiotherapist |
| `psicologo` | Psychologist |
| `ottico` | Optician |
| `veterinario` | Veterinarian |
| `avvocato` | Lawyer |
| `architetto` | Architect |
| `geometra` | Surveyor |
| `agenzia-immobiliare` | Real estate agency |
| `agenzia-assicurativa` | Insurance agency |
| `idraulico` | Plumber |
| `elettricista` | Electrician |
| `falegname` | Carpenter |
| `muratore` | Builder / mason |
| `officina-meccanica` | Auto repair shop |
| `carrozzeria` | Body shop |
| `hotel` | Hotel |
| `bed-and-breakfast` | Bed & Breakfast |
| `agriturismo` | Farm stay / agriturismo |
| `palestra` | Gym / fitness center |
| `piscina` | Swimming pool |
| `scuola-guida` | Driving school |
| `supermercato` | Supermarket |
| `ferramenta` | Hardware store |
| `fiorista` | Florist |
| `panificio` | Bakery |

### Supported cities

The Actor includes many predefined Italian cities, including:

- Rome
- Milan
- Naples
- Turin
- Bologna
- Florence
- Palermo
- Genoa
- Venice
- Bari
- Catania
- Verona
- Padua
- Trieste
- Brescia
- Taranto
- Lecce
- Rimini
- Reggio Calabria

Custom cities can also be added manually.

### Technical details

The Actor is built with:

- Node.js
- Apify SDK
- Crawlee
- HTTP crawling
- Cheerio HTML parsing
- Apify Dataset export

Technical workflow:

1. Builds PagineGialle.it search URLs from category and city inputs.
2. Normalizes category and city slugs.
3. Handles known Italian category aliases and public directory slugs.
4. Crawls the first result pages.
5. Detects district-level result pages when available.
6. Crawls district result pages to collect more listings.
7. Extracts structured listing cards.
8. Separates real websites from WhatsApp contact links.
9. Deduplicates records within each category/city run.
10. Saves results to the Apify dataset.

### Performance notes

For small tests, use:

- 1 category
- 1 city
- 50 to 100 max results

For medium runs, use:

- 3 to 10 categories
- 1 to 5 cities
- 100 to 1000 max results
- Apify Proxy enabled

For larger runs:

- split jobs by region or city group
- keep max results reasonable
- export and deduplicate after the run if needed
- validate important records manually before operational use

### Data quality notes

PagineGialle.it listings vary by category, city, and individual business profile.

Some records may have complete phone and address data. Others may contain only partial information. Website and WhatsApp contact links are only available when visible in the public listing data.

A business can appear in more than one category or district result page. The Actor deduplicates records within each search run, but external post-processing can still be useful for large multi-category exports.

### Responsible use

This Actor extracts publicly available business directory listing information.

Users are responsible for using the extracted data in compliance with applicable laws, regulations, privacy rules, and platform terms.

### Best for

- PagineGialle.it scraping
- Italian business directory datasets
- Local business data collection
- Market research in Italy
- Business category mapping
- City-level competitor analysis
- CRM preparation
- Local SEO research
- Sales list preparation
- Public directory data extraction

### Not designed for

- guaranteed email extraction
- private data extraction
- full company intelligence enrichment
- operational decision-making without manual validation

### Summary

PagineGialle.it Business Directory Scraper is a practical Actor for collecting structured public Italian business listings by category and city.

It helps transform PagineGialle.it search results into clean datasets that can be exported, filtered, analyzed, and used in business research workflows.

# Actor input Schema

## `categories` (type: `array`):

Select one or more business categories to search for.

## `cities` (type: `array`):

Select one or more Italian cities to search in.

## `customCategories` (type: `array`):

Add any category not listed above, one per line (e.g. 'tatuaggi', 'pompe-funebri', 'erboristeria'). Combined with all selected cities.

## `customCities` (type: `array`):

Add any Italian city not listed above, one per line (e.g. 'barletta', 'cosenza', 'agrigento'). Combined with all selected categories.

## `maxResults` (type: `integer`):

Maximum listings per category+city combination. Large cities (Rome/Milan) can yield 500–2500+ results per category.

## `onlyWithPhone` (type: `boolean`):

Skip listings that don't have a phone number.

## `onlyWithWebsite` (type: `boolean`):

Skip listings that don't have a website URL.

## `onlyWithEmail` (type: `boolean`):

Skip listings that don't have an email address.

## `useApifyProxy` (type: `boolean`):

Use Apify datacenter proxies for IP rotation. Strongly recommended for multi-city/multi-category runs.

## `searches` (type: `array`):

Expert mode: provide a custom JSON array of {"what": "...", "where": "..."} objects. When set, this overrides all dropdown selections above.

## Actor input object example

```json
{
  "categories": [
    "ristorante"
  ],
  "cities": [
    "roma"
  ],
  "customCategories": [],
  "customCities": [],
  "maxResults": 200,
  "onlyWithPhone": false,
  "onlyWithWebsite": false,
  "onlyWithEmail": false,
  "useApifyProxy": true,
  "searches": []
}
```

# Actor output Schema

## `results` (type: `string`):

Default dataset containing extracted Italian business listings. Use the Apify dataset export buttons to download JSON, CSV, Excel, XML, RSS or HTML.

# 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 = {
    "categories": [
        "ristorante"
    ],
    "cities": [
        "roma"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("ayrtondavoli97/paginegialle-it-business-directory-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 = {
    "categories": ["ristorante"],
    "cities": ["roma"],
}

# Run the Actor and wait for it to finish
run = client.actor("ayrtondavoli97/paginegialle-it-business-directory-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "categories": [
    "ristorante"
  ],
  "cities": [
    "roma"
  ]
}' |
apify call ayrtondavoli97/paginegialle-it-business-directory-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=ayrtondavoli97/paginegialle-it-business-directory-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

```json
{
    "openapi": "3.0.1",
    "info": {
        "title": "PagineGialle.it Business Directory Scraper",
        "description": "Scrape public business listings from PagineGialle.it. Search by Italian city and business category, collect names, phone numbers, addresses, profile URLs, websites and contact links when available, then export to JSON, CSV or Excel.",
        "version": "0.0",
        "x-build-id": "lywYsrXKP9TD9m3tD"
    },
    "servers": [
        {
            "url": "https://api.apify.com/v2"
        }
    ],
    "paths": {
        "/acts/ayrtondavoli97~paginegialle-it-business-directory-scraper/run-sync-get-dataset-items": {
            "post": {
                "operationId": "run-sync-get-dataset-items-ayrtondavoli97-paginegialle-it-business-directory-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        },
        "/acts/ayrtondavoli97~paginegialle-it-business-directory-scraper/runs": {
            "post": {
                "operationId": "runs-sync-ayrtondavoli97-paginegialle-it-business-directory-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor and returns information about the initiated run in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/runsResponseSchema"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/acts/ayrtondavoli97~paginegialle-it-business-directory-scraper/run-sync": {
            "post": {
                "operationId": "run-sync-ayrtondavoli97-paginegialle-it-business-directory-scraper",
                "x-openai-isConsequential": false,
                "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
                "tags": [
                    "Run Actor"
                ],
                "requestBody": {
                    "required": true,
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/inputSchema"
                            }
                        }
                    }
                },
                "parameters": [
                    {
                        "name": "token",
                        "in": "query",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "description": "Enter your Apify token here"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "OK"
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "inputSchema": {
                "type": "object",
                "properties": {
                    "categories": {
                        "title": "Business Categories",
                        "type": "array",
                        "description": "Select one or more business categories to search for.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "ristorante",
                                "pizzeria",
                                "bar",
                                "pasticceria",
                                "gelateria",
                                "trattoria",
                                "enoteca",
                                "sushi",
                                "dentista",
                                "medico",
                                "farmacia",
                                "parrucchiere",
                                "estetista",
                                "fisioterapista",
                                "psicologo",
                                "ottico",
                                "veterinario",
                                "avvocato",
                                "commercialista",
                                "notaio",
                                "architetto",
                                "geometra",
                                "agenzia-immobiliare",
                                "agenzia-assicurativa",
                                "idraulico",
                                "elettricista",
                                "falegname",
                                "muratore",
                                "impresa-edile",
                                "officina-meccanica",
                                "carrozzeria",
                                "hotel",
                                "bed-and-breakfast",
                                "agriturismo",
                                "palestra",
                                "piscina",
                                "scuola-guida",
                                "supermercato",
                                "ferramenta",
                                "fiorista",
                                "panificio"
                            ],
                            "enumTitles": [
                                "🍽️ Restaurant",
                                "🍕 Pizzeria",
                                "☕ Bar / Café",
                                "🎂 Pastry Shop",
                                "🍦 Ice Cream Shop",
                                "🍷 Trattoria",
                                "🍾 Wine Bar",
                                "🍱 Sushi",
                                "🦷 Dentist",
                                "👨‍⚕️ Doctor / GP",
                                "💊 Pharmacy",
                                "💇 Hair Salon",
                                "💅 Beauty Salon",
                                "🏃 Physiotherapist",
                                "🧠 Psychologist",
                                "👓 Optician",
                                "🐾 Veterinarian",
                                "⚖️ Lawyer",
                                "📊 Accountant",
                                "📜 Notary",
                                "📐 Architect",
                                "📏 Surveyor",
                                "🏠 Real Estate Agency",
                                "🛡️ Insurance Agency",
                                "🔧 Plumber",
                                "⚡ Electrician",
                                "🪵 Carpenter",
                                "🧱 Builder / Mason",
                                "🏗️ Construction Company",
                                "🔩 Auto Repair Shop",
                                "🚗 Body Shop",
                                "🏨 Hotel",
                                "🛏️ Bed & Breakfast",
                                "🌾 Farm Stay (Agriturismo)",
                                "💪 Gym / Fitness",
                                "🏊 Swimming Pool",
                                "🚦 Driving School",
                                "🛒 Supermarket",
                                "🔨 Hardware Store",
                                "🌸 Florist",
                                "🥖 Bakery"
                            ]
                        },
                        "default": [
                            "ristorante"
                        ]
                    },
                    "cities": {
                        "title": "Cities",
                        "type": "array",
                        "description": "Select one or more Italian cities to search in.",
                        "items": {
                            "type": "string",
                            "enum": [
                                "roma",
                                "milano",
                                "napoli",
                                "torino",
                                "bologna",
                                "firenze",
                                "palermo",
                                "genova",
                                "venezia",
                                "bari",
                                "catania",
                                "verona",
                                "messina",
                                "padova",
                                "trieste",
                                "brescia",
                                "taranto",
                                "prato",
                                "modena",
                                "parma",
                                "livorno",
                                "cagliari",
                                "perugia",
                                "foggia",
                                "salerno",
                                "reggio-emilia",
                                "ravenna",
                                "ferrara",
                                "monza",
                                "trento",
                                "vicenza",
                                "bergamo",
                                "ancona",
                                "siena",
                                "pescara",
                                "arezzo",
                                "lecce",
                                "rimini",
                                "reggio-calabria",
                                "cesena"
                            ],
                            "enumTitles": [
                                "Rome",
                                "Milan",
                                "Naples",
                                "Turin",
                                "Bologna",
                                "Florence",
                                "Palermo",
                                "Genoa",
                                "Venice",
                                "Bari",
                                "Catania",
                                "Verona",
                                "Messina",
                                "Padua",
                                "Trieste",
                                "Brescia",
                                "Taranto",
                                "Prato",
                                "Modena",
                                "Parma",
                                "Livorno",
                                "Cagliari",
                                "Perugia",
                                "Foggia",
                                "Salerno",
                                "Reggio Emilia",
                                "Ravenna",
                                "Ferrara",
                                "Monza",
                                "Trento",
                                "Vicenza",
                                "Bergamo",
                                "Ancona",
                                "Siena",
                                "Pescara",
                                "Arezzo",
                                "Lecce",
                                "Rimini",
                                "Reggio Calabria",
                                "Cesena"
                            ]
                        },
                        "default": [
                            "roma"
                        ]
                    },
                    "customCategories": {
                        "title": "Custom Categories (not in dropdown)",
                        "type": "array",
                        "description": "Add any category not listed above, one per line (e.g. 'tatuaggi', 'pompe-funebri', 'erboristeria'). Combined with all selected cities.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "customCities": {
                        "title": "Custom Cities (not in dropdown)",
                        "type": "array",
                        "description": "Add any Italian city not listed above, one per line (e.g. 'barletta', 'cosenza', 'agrigento'). Combined with all selected categories.",
                        "default": [],
                        "items": {
                            "type": "string"
                        }
                    },
                    "maxResults": {
                        "title": "Max Results per Search",
                        "minimum": 1,
                        "maximum": 5000,
                        "type": "integer",
                        "description": "Maximum listings per category+city combination. Large cities (Rome/Milan) can yield 500–2500+ results per category.",
                        "default": 200
                    },
                    "onlyWithPhone": {
                        "title": "Only listings with phone number",
                        "type": "boolean",
                        "description": "Skip listings that don't have a phone number.",
                        "default": false
                    },
                    "onlyWithWebsite": {
                        "title": "Only listings with website",
                        "type": "boolean",
                        "description": "Skip listings that don't have a website URL.",
                        "default": false
                    },
                    "onlyWithEmail": {
                        "title": "Only listings with email",
                        "type": "boolean",
                        "description": "Skip listings that don't have an email address.",
                        "default": false
                    },
                    "useApifyProxy": {
                        "title": "Use Apify Proxy (recommended)",
                        "type": "boolean",
                        "description": "Use Apify datacenter proxies for IP rotation. Strongly recommended for multi-city/multi-category runs.",
                        "default": true
                    },
                    "searches": {
                        "title": "Advanced: Raw Search Queries",
                        "type": "array",
                        "description": "Expert mode: provide a custom JSON array of {\"what\": \"...\", \"where\": \"...\"} objects. When set, this overrides all dropdown selections above.",
                        "default": []
                    }
                }
            },
            "runsResponseSchema": {
                "type": "object",
                "properties": {
                    "data": {
                        "type": "object",
                        "properties": {
                            "id": {
                                "type": "string"
                            },
                            "actId": {
                                "type": "string"
                            },
                            "userId": {
                                "type": "string"
                            },
                            "startedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "finishedAt": {
                                "type": "string",
                                "format": "date-time",
                                "example": "2025-01-08T00:00:00.000Z"
                            },
                            "status": {
                                "type": "string",
                                "example": "READY"
                            },
                            "meta": {
                                "type": "object",
                                "properties": {
                                    "origin": {
                                        "type": "string",
                                        "example": "API"
                                    },
                                    "userAgent": {
                                        "type": "string"
                                    }
                                }
                            },
                            "stats": {
                                "type": "object",
                                "properties": {
                                    "inputBodyLen": {
                                        "type": "integer",
                                        "example": 2000
                                    },
                                    "rebootCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "restartCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "resurrectCount": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "computeUnits": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "options": {
                                "type": "object",
                                "properties": {
                                    "build": {
                                        "type": "string",
                                        "example": "latest"
                                    },
                                    "timeoutSecs": {
                                        "type": "integer",
                                        "example": 300
                                    },
                                    "memoryMbytes": {
                                        "type": "integer",
                                        "example": 1024
                                    },
                                    "diskMbytes": {
                                        "type": "integer",
                                        "example": 2048
                                    }
                                }
                            },
                            "buildId": {
                                "type": "string"
                            },
                            "defaultKeyValueStoreId": {
                                "type": "string"
                            },
                            "defaultDatasetId": {
                                "type": "string"
                            },
                            "defaultRequestQueueId": {
                                "type": "string"
                            },
                            "buildNumber": {
                                "type": "string",
                                "example": "1.0.0"
                            },
                            "containerUrl": {
                                "type": "string"
                            },
                            "usage": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "integer",
                                        "example": 1
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            },
                            "usageTotalUsd": {
                                "type": "number",
                                "example": 0.00005
                            },
                            "usageUsd": {
                                "type": "object",
                                "properties": {
                                    "ACTOR_COMPUTE_UNITS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATASET_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "KEY_VALUE_STORE_WRITES": {
                                        "type": "number",
                                        "example": 0.00005
                                    },
                                    "KEY_VALUE_STORE_LISTS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_READS": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "REQUEST_QUEUE_WRITES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_INTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "DATA_TRANSFER_EXTERNAL_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                                        "type": "integer",
                                        "example": 0
                                    },
                                    "PROXY_SERPS": {
                                        "type": "integer",
                                        "example": 0
                                    }
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}
```
