# PagineGialle Scraper - Italian Business Directory (`crawlerbros/paginegialle-scraper`) Actor Scrape PagineGialle.it (Italy's leading business directory). Search by category and city/comune, or fetch full business profiles by URL. Get names, addresses, phone numbers, categories, ratings, opening hours, and websites. - **URL**: https://apify.com/crawlerbros/paginegialle-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** Automation, Lead generation, Developer tools - **Stats:** 1 total users, 0 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 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. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. 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/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.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/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 Scraper - Italian Business Directory (Yellow Pages) Scrape **PagineGialle.it** — Italy's leading business directory ("Pagine Gialle" = Yellow Pages). Search any business category in any Italian city, comune, or postal code (CAP) and get names, addresses, phone numbers, categories, ratings, opening hours, and websites. Optionally fetch each business's full profile for its precise rating, structured weekly opening hours, VAT number, and social media links. No login, no cookies, no API key required. ### What this actor does - **Two modes:** `search` (category + city) and `detail` (direct business profile URLs) - **60+ curated categories** to pick from, or type any custom category slug - **Filter by** minimum star rating (1-5), "has at least one rating", "open right now" (computed live from published hours), or "has a website" - **Full Italian character support** — à, è, ì, ò, ù, apostrophes (e.g. "Sant'Angelo") are handled correctly in both input and output - **Rich business profiles** — precise rating, structured weekly opening hours, VAT number (Partita IVA), social media links, all with `fetchDetails: true` (on by default) - **Search by postal code (CAP)** as well as city/comune name - **Sort by relevance, distance, or popularity** — same ordering options as the site's own "Ordina per" dropdown - **Empty fields are omitted** — you only ever see fields that were actually found for a business ### Output per business - `name` — business name - `category` — the business's listed category - `rating`, `reviewCount` — average star rating (1-5) and number of reviews - `street`, `zipCode`, `city`, `province`, `region`, `address` (combined address text from the listing) - `phone`, `phoneNumbers[]` — primary phone number, plus any additional numbers - `website` — business website - `vatNumber` — Italian VAT number (Partita IVA), when profile fetched - `socialLinks` — object with `facebook`/`instagram`/`twitter`/`linkedin`/`youtube`/`tiktok` URLs, when profile fetched and published - `openingHours` — structured weekly schedule (day name → list of `"HH:MM - HH:MM"` slots), when profile fetched - `isOpenNow` — live open/closed status computed from published hours at scrape time (search-listing pages only) - `services[]` — listed services/amenities (e.g. "Da asporto", "Ambiente climatizzato") - `description` — the business's own listing/profile description text - `searchCategory`, `searchCity` — the category/city you searched for (mode=search) - `sourceUrl` — canonical PagineGialle profile URL for the business - `recordType: "business"`, `scrapedAt` ### Input | Field | Type | Default | Description | |---|---|---|---| | `mode` | string | `search` | `search` (category + city) or `detail` (fetch by URL) | | `category` | string (select) | `ristoranti` | Pick a common category, or `custom` to use `customCategory` (mode=search) | | `customCategory` | string | – | Any free-text category slug, overrides `category` (mode=search) | | `city` | string | `Roma` | Italian city/comune name or 5-digit postal code (CAP) to search in (mode=search) | | `fetchDetails` | boolean | `true` | Also visit each business's profile page for precise rating, structured hours, VAT number, and social links (slower but richer) | | `sortBy` | string (select) | `relevance` | Result order: `relevance` (default), `distance`, or `popularity` — mirrors PagineGialle's own "Ordina per" dropdown (mode=search) | | `openNowOnly` | boolean | `false` | Only return businesses currently open, computed from their published hours | | `ratedOnly` | boolean | `false` | Only return businesses that have at least one rating | | `minRating` | string (select) | – (no minimum) | Only return businesses rated at least `1`-`5` stars | | `websiteOnly` | boolean | `false` | Only return businesses that have a website listed | | `businessUrls` | array | – | PagineGialle profile URLs to fetch directly (mode=detail) | | `maxItems` | int | `50` | Hard cap on returned records (1-1000) | #### Example: search restaurants in Rome ```json { "mode": "search", "category": "ristoranti", "city": "Roma", "maxItems": 50 } ```` #### Example: 4+ star lawyers in Milan, with full profiles ```json { "mode": "search", "category": "avvocati", "city": "Milano", "minRating": "4", "fetchDetails": true, "maxItems": 30 } ``` #### Example: plumbers open right now near a postal code ```json { "mode": "search", "category": "idraulici", "city": "00100", "openNowOnly": true, "maxItems": 40 } ``` #### Example: rated dentists with a website, fast (listing-only fields) ```json { "mode": "search", "category": "dentisti", "city": "Napoli", "ratedOnly": true, "websiteOnly": true, "fetchDetails": false, "maxItems": 100 } ``` #### Example: fetch specific business profiles ```json { "mode": "detail", "businessUrls": [ { "url": "https://www.paginegialle.it/ristorante-la-favola-rm" } ] } ``` ### Use cases - **Local lead generation** — build a prospect list of Italian businesses by trade and city for B2B outreach - **Market research** — measure business density and average ratings for a category across Italian cities - **Directory aggregation** — feed structured Italian business data into your own local-search product - **Competitor mapping** — see who else operates in a category and area, with ratings and contact info - **Franchise & site-selection analysis** — evaluate service-business coverage across Italian regions and comuni ### FAQ **What data source does this actor use?** It reads the publicly available search and business-profile pages on paginegialle.it, Italy's leading business directory (Italiaonline S.p.A.). No account or API key is needed. **Is this affiliated with PagineGialle or Italiaonline?** No. This is an independent, third-party actor that reads publicly accessible pages. **Why do some businesses have no rating, phone, or website?** PagineGialle only shows a rating once a business has received at least one review, and only shows contact details a business itself provided. Fields with no data are simply omitted from the record rather than shown as empty or null. **Can I search by postal code instead of a city name?** Yes — the `city` field accepts Italian postal codes (CAP, 5 digits) as well as city/comune names. **Why is `fetchDetails` on by default?** The search-listing page already includes name, address, phone, category, rating and description, but the precise 1-decimal rating, structured weekly opening hours, VAT number, and social links only appear on the business's own profile page. `fetchDetails: true` fetches that page for each result. Turn it off for a faster run when you only need the core listing fields. **How is the rating computed?** When `fetchDetails` is on (default), the rating is read directly from the business profile's published "X.X è la valutazione degli utenti" text — the exact value PagineGialle itself displays. In listing-only mode (`fetchDetails: false`), the rating is derived from the same visual star-fill percentage the listing page uses, truncated to one decimal. **Does this actor return email addresses?** No. PagineGialle does not publish email addresses directly on business listings or profiles — only a "Scrivici" (contact us) web form. This actor never fabricates an email field. **Why do PagineGialle links (`sourceUrl`) sometimes fail to open for me?** paginegialle.it restricts access at its CDN edge to IP addresses geolocated in Italy (a "geo-restriction", not a broken link or bot-block). The actor itself is unaffected — it runs on Apify's cloud infrastructure, which reaches the site normally — but if you personally browse to a `sourceUrl` from outside Italy you may see a 403 page. The business's own `website` field is not affected by this restriction. **Does this actor need a proxy?** No proxy is required for normal use. The actor automatically escalates to Apify's free `AUTO` datacenter proxy (Italy-pinned) only if it is temporarily rate-limited. **Is there a limit on how many results I can get for one category+city search?** For very popular category+city combinations in large cities (e.g. "ristoranti" in Roma), PagineGialle's own search-results pagination genuinely runs out of distinct businesses after a handful of pages — deeper pages start repeating the same listings rather than surfacing new ones. When this happens the actor detects it automatically and stops cleanly (no duplicate records, no wasted requests) rather than hanging or fabricating data. For a wider net on saturated categories, narrow your search with a more specific city, comune, or postal code (CAP) instead of a broad category alone. **What about opening hours or "open now"?** On the search-listing page, `isOpenNow` is computed live from PagineGialle's own published weekly schedule at the moment of scraping (Europe/Rome time). With `fetchDetails: true`, the full structured weekly `openingHours` schedule from the business's profile page is also included. # Actor input Schema ## `mode` (type: `string`): What to fetch: search a category + city, or fetch full business profiles from direct URLs. ## `category` (type: `string`): Business category to search for. Pick a common category, or choose 'Custom category' and type your own slug below (mode=search). ## `customCategory` (type: `string`): Free-text category slug not in the curated list above, e.g. 'traduttori' or 'fisioterapisti-sportivi' (mode=search). Takes priority over 'Category' when set. ## `city` (type: `string`): Italian city, town (comune), or 5-digit postal code (CAP) to search in, e.g. 'Roma', 'Milano', 'Napoli', or '20121' (mode=search). ## `fetchDetails` (type: `boolean`): For each search result, also visit its business profile page to collect the precise rating, structured opening hours, website, VAT number and social links. Slower but much richer (mode=search). When off, results still include name, address, phone, category and rating derived from the listing page. ## `openNowOnly` (type: `boolean`): Only return businesses that are currently open, computed from their published opening hours at scrape time (mode=search). Businesses with no published hours are excluded when this is on. ## `ratedOnly` (type: `boolean`): Only return businesses that have at least one customer rating (mode=search). ## `minRating` (type: `string`): Only return businesses rated at least this many stars, e.g. '4' for 4.0+ (mode=search). ## `sortBy` (type: `string`): Order search results the same way PagineGialle's own 'Ordina per' dropdown does (mode=search). 'Relevance' (default) mixes sponsored placement with geographic/category relevance. ## `websiteOnly` (type: `boolean`): Only return businesses that have a website listed (mode=search). ## `businessUrls` (type: `array`): Direct PagineGialle business profile URLs to fetch, e.g. https://www.paginegialle.it/\. Use the 'sourceUrl' field from search results. ## `maxItems` (type: `integer`): Hard cap on the number of business records to return. ## Actor input object example ```json { "mode": "search", "category": "ristoranti", "city": "Roma", "fetchDetails": true, "openNowOnly": false, "ratedOnly": false, "minRating": "", "sortBy": "relevance", "websiteOnly": false, "businessUrls": [], "maxItems": 12 } ``` # Actor output Schema ## `businesses` (type: `string`): Dataset containing all scraped PagineGialle business listings. # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "search", "category": "ristoranti", "city": "Roma", "fetchDetails": true, "openNowOnly": false, "ratedOnly": false, "minRating": "", "sortBy": "relevance", "websiteOnly": false, "businessUrls": [], "maxItems": 12 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/paginegialle-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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "search", "category": "ristoranti", "city": "Roma", "fetchDetails": True, "openNowOnly": False, "ratedOnly": False, "minRating": "", "sortBy": "relevance", "websiteOnly": False, "businessUrls": [], "maxItems": 12, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/paginegialle-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 '{ "mode": "search", "category": "ristoranti", "city": "Roma", "fetchDetails": true, "openNowOnly": false, "ratedOnly": false, "minRating": "", "sortBy": "relevance", "websiteOnly": false, "businessUrls": [], "maxItems": 12 }' | apify call crawlerbros/paginegialle-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/paginegialle-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "PagineGialle Scraper - Italian Business Directory", "description": "Scrape PagineGialle.it (Italy's leading business directory). Search by category and city/comune, or fetch full business profiles by URL. Get names, addresses, phone numbers, categories, ratings, opening hours, and websites.", "version": "1.0", "x-build-id": "wNQIQ0Q0jZDmtibqH" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~paginegialle-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-paginegialle-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/crawlerbros~paginegialle-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-paginegialle-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/crawlerbros~paginegialle-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-paginegialle-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", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "search", "detail" ], "type": "string", "description": "What to fetch: search a category + city, or fetch full business profiles from direct URLs.", "default": "search" }, "category": { "title": "Category (categoria)", "enum": [ "custom", "ristoranti", "pizzerie", "bar", "hotel", "avvocati", "commercialisti", "notai", "dentisti", "farmacie", "studio-medico", "oculisti", "veterinari", "ospedali", "idraulici", "elettricisti", "fabbri", "ferramenta", "imprese-di-pulizia", "parrucchiere", "barbieri", "centro-estetico", "estetiste", "palestre", "piscine", "agenzie-immobiliari", "architetti", "ingegneri", "geometri", "autofficine", "carrozzerie", "gommisti", "autolavaggi", "concessionarie-auto", "autoscuole", "autonoleggio", "taxi", "supermercati", "alimentari", "macellerie", "pescherie", "fruttivendoli", "panetterie", "pasticcerie", "gelaterie", "fioristi", "librerie", "tabaccherie", "negozi-di-abbigliamento", "negozi-di-scarpe", "assicurazioni", "banche", "agenzie-di-viaggio", "onoranze-funebri", "traslochi", "disinfestazione", "lavanderie", "fisioterapisti", "logopedia", "psicologi", "nutrizionisti", "asili-nido", "scuole-di-lingue", "corsi-di-inglese", "cinema", "fotografi", "wedding-planner" ], "type": "string", "description": "Business category to search for. Pick a common category, or choose 'Custom category' and type your own slug below (mode=search).", "default": "ristoranti" }, "customCategory": { "title": "Custom category (overrides selection above)", "type": "string", "description": "Free-text category slug not in the curated list above, e.g. 'traduttori' or 'fisioterapisti-sportivi' (mode=search). Takes priority over 'Category' when set." }, "city": { "title": "City / comune / postal code (CAP)", "type": "string", "description": "Italian city, town (comune), or 5-digit postal code (CAP) to search in, e.g. 'Roma', 'Milano', 'Napoli', or '20121' (mode=search).", "default": "Roma" }, "fetchDetails": { "title": "Fetch full business profiles", "type": "boolean", "description": "For each search result, also visit its business profile page to collect the precise rating, structured opening hours, website, VAT number and social links. Slower but much richer (mode=search). When off, results still include name, address, phone, category and rating derived from the listing page.", "default": true }, "openNowOnly": { "title": "Open now only", "type": "boolean", "description": "Only return businesses that are currently open, computed from their published opening hours at scrape time (mode=search). Businesses with no published hours are excluded when this is on.", "default": false }, "ratedOnly": { "title": "Only businesses with ratings", "type": "boolean", "description": "Only return businesses that have at least one customer rating (mode=search).", "default": false }, "minRating": { "title": "Minimum rating", "enum": [ "", "1", "2", "3", "4", "5" ], "type": "string", "description": "Only return businesses rated at least this many stars, e.g. '4' for 4.0+ (mode=search).", "default": "" }, "sortBy": { "title": "Sort by", "enum": [ "relevance", "distance", "popularity" ], "type": "string", "description": "Order search results the same way PagineGialle's own 'Ordina per' dropdown does (mode=search). 'Relevance' (default) mixes sponsored placement with geographic/category relevance.", "default": "relevance" }, "websiteOnly": { "title": "Only businesses with a website", "type": "boolean", "description": "Only return businesses that have a website listed (mode=search).", "default": false }, "businessUrls": { "title": "Business profile URLs (mode=detail)", "type": "array", "description": "Direct PagineGialle business profile URLs to fetch, e.g. https://www.paginegialle.it/<slug>. Use the 'sourceUrl' field from search results.", "items": { "type": "object", "properties": { "url": { "title": "URL", "type": "string", "description": "PagineGialle business profile URL." } } }, "default": [] }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Hard cap on the number of business records to return.", "default": 50 } } }, "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 } } } } } } } } } } ```