AI Actor Template - Web Scraper

Template per creare rapidamente actor Apify di web scraping guidati da AI (Claude Code).

💡 Before you run this scraper

Some datasets like this one are already available ready-to-use on bananalitycs.com — download instantly or request custom delivery.

 

Come Funziona

1. Compila PROMPT.md con le direttive del tuo scraper (URL target, selettori HTML, paginazione, struttura dati)
2. Chiedi a Claude Code: "Leggi PROMPT.md e genera l'actor"
3. Claude Code legge le direttive, modifica il codice, aggiorna gli schema e genera un actor completo

Quick Start

1. Compila il Prompt

Apri PROMPT.md e compila le sezioni:

Sezione	Cosa Inserire
Informazioni Generali	Nome, descrizione, sito target
URL di Partenza	URL della pagina lista/catalogo
Struttura HTML Lista	Come sono fatti gli items nella pagina elenco
Paginazione	Tipo e formato URL delle pagine
Pagina Dettaglio	Struttura HTML della pagina singola
Struttura Output	Campi JSON da estrarre
Regole Speciali	Headers, rate limiting, anti-bot

2. Genera l'Actor con AI

# In Claude Code, chiedi:
"Leggi PROMPT.md e implementa l'actor di scraping"

Claude Code:

• Legge le direttive da PROMPT.md
• Aggiorna src/config.py con nome e costanti
• Modifica src/parsers.py con i selettori CSS corretti
• Aggiorna .actor/input_schema.json con i parametri input
• Aggiorna .actor/dataset_schema.json con lo schema output
• Aggiorna .actor/actor.json con nome e descrizione

3. Testa Localmente

$apify run

4. Deploy su Apify

apify login
apify push

Struttura del Progetto

.actor/
├── actor.json            # Config actor (nome, versione, schema)
├── input_schema.json     # Parametri input per Apify Console
├── dataset_schema.json   # Schema visualizzazione output
└── output_schema.json    # Schema output
src/
├── config.py             # Configurazione: nome actor, costi, costanti
├── parsers.py            # Selettori CSS: listing, detail, paginazione
├── scraper.py            # Logica di scraping (loop pagine + dettaglio)
├── tracking.py           # Mixpanel tracking (non modificare)
├── main.py               # Entry point actor
├── __main__.py            # Runner (non modificare)
└── __init__.py            # Package marker
PROMPT.md                 # LE TUE DIRETTIVE (compila questo!)
AGENTS.md                 # Guida per AI agent
README.md                 # Questa documentazione
Dockerfile                # Container image
requirements.txt          # Dipendenze Python

Parametri Input di Default

Parametro	Tipo	Descrizione	Default
start_url	string	URL di partenza per lo scraping	(obbligatorio)
max_results	integer	Numero massimo risultati (0 = illimitato)	100
include_detail	boolean	Se visitare le pagine di dettaglio	true
delay_seconds	number	Pausa tra le richieste (secondi)	0.5
proxy_configuration	object	Configurazione proxy	Apify Proxy

Output di Esempio

{
  "url": "https://example.com/detail/123",
  "title": "Titolo dell'item",
  "description": "Descrizione completa",
  "price": "€ 1.200",
  "images": ["https://example.com/img1.jpg"],
  "address": "Via Roma 1, Milano",
  "phone": "+39 02 1234567",
  "email": "info@example.com",
  "category": "Categoria",
  "rating": 4.5,
  "review_count": 23
}

Pattern Supportati

Il template supporta i pattern di scraping piu' comuni:

• Lista + Dettaglio: Pagina elenco con link a pagine di dettaglio
• Solo Lista: Tutti i dati visibili nella pagina elenco
• API JSON: Siti che caricano dati via API interna
• Paginazione URL: ?page=1, ?page=2, ...
• Paginazione Next: Link "pagina successiva"

Tecnologie

• Python 3.13 - Linguaggio
• Apify SDK - Framework actor
• BeautifulSoup4 + lxml - Parsing HTML
• httpx - Client HTTP async
• Sentry - Error tracking
• Mixpanel - Analytics

Consigli

• Testa con max_results: 10 prima di scraping completi
• Usa delay_seconds: 1 per siti con rate limiting
• Abilita proxy per scraping su larga scala
• Programma esecuzioni periodiche per dati aggiornati