AI Actor Template - Web Scraper

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

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