Documentazione

API di estrazione dati

Dacci un URL e un insieme di campi. Recuperiamo la pagina, applichiamo i tuoi selettori CSS e restituiamo JSON pulito. Nessun browser da avviare, nessun codice di parsing, nessuna rotazione di IP da gestire. L'URL di base di ogni endpoint è https://scrape.land.

Autenticazione

Invia la tua chiave API nell'intestazione X-Api-Key a ogni richiesta:

X-Api-Key: pb_live_YOURKEY

Va bene anche un'intestazione bearer Authorization, se si adatta meglio al tuo stack:

Authorization: Bearer pb_live_YOURKEY

curl https://scrape.land/v1/extract \
  -H "X-Api-Key: pb_live_YOURKEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example-product.com/item/42",
       "fields":{"title":"h1","price":".price"}}'

import requests

r = requests.post("https://scrape.land/v1/extract",
    headers={"X-Api-Key": "pb_live_YOURKEY"},
    json={"url": "https://example-product.com/item/42",
          "fields": {"title": "h1", "price": ".price"}},
    timeout=60)
print(r.json()["data"])

from scrapeland import ScrapelandClient

client = ScrapelandClient("pb_live_YOURKEY")   # or $SCRAPELAND_API_KEY
data = client.extract("https://example-product.com/item/42",
                      {"title": "h1", "price": ".price"})
print(data)

const res = await fetch("https://scrape.land/v1/extract", {
  method: "POST",
  headers: { "X-Api-Key": "pb_live_YOURKEY", "Content-Type": "application/json" },
  body: JSON.stringify({
    url: "https://example-product.com/item/42",
    fields: { title: "h1", price: ".price" },
  }),
});
console.log((await res.json()).data);

package main

import ("bytes"; "encoding/json"; "fmt"; "net/http")

func main() {
    body, _ := json.Marshal(map[string]any{
        "url":    "https://example-product.com/item/42",
        "fields": map[string]string{"title": "h1", "price": ".price"},
    })
    req, _ := http.NewRequest("POST", "https://scrape.land/v1/extract", bytes.NewReader(body))
    req.Header.Set("X-Api-Key", "pb_live_YOURKEY")
    req.Header.Set("Content-Type", "application/json")
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    var out map[string]any
    json.NewDecoder(resp.Body).Decode(&out)
    fmt.Println(out["data"])
}

$ch = curl_init("https://scrape.land/v1/extract");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["X-Api-Key: pb_live_YOURKEY", "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode([
    "url" => "https://example-product.com/item/42",
    "fields" => ["title" => "h1", "price" => ".price"],
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$data = json_decode(curl_exec($ch), true)["data"];

{
  "url": "https://example-product.com/item/42",
  "status": 200,
  "data": {
    "title": "Vintage desk lamp",
    "price": "49.00"
  }
}

Come i campi si mappano ai selettori

Ogni voce in fields ha una di queste forme:

• Una stringa con un selettore CSS. Restituiamo il testo del primo elemento corrispondente. "title": "h1" restituisce il testo dentro il primo h1.
• Una scorciatoia selettore@attr per leggere un attributo. "image": "img.gallery@src" restituisce src; usa @text o nessun parametro per il testo.
• Una scorciatoia XPath: una stringa il cui primo carattere è / o ( è trattata come XPath, tutto il resto come CSS. "title": "//h1/text()", "link": "//a/@href", "first": "(//p)[1]".
• Un oggetto con css più chiavi opzionali: attr (legge un attributo invece del testo), all (restituisce ogni corrispondenza come array) o xpath (un'espressione XPath invece di css, per i campi di primo livello). Si combinano.
• Un gruppo: un oggetto con css e i propri fields. Il css seleziona il contenitore che si ripete e i campi interni vengono letti dentro ciascuno, quindi ottieni un elenco di oggetti invece di array paralleli che possono disallinearsi. Usa "." per il contenitore stesso. "articles": {"css": ".card", "fields": {"title": "h3", "url": {"css": "a", "attr": "href"}}} restituisce [{"title": ..., "url": ...}, ...], e un campo mancante in un contenitore è null in quella riga senza spostare le righe successive.

Dove funziona XPath. XPath è supportato per i campi di primo livello, come scorciatoia o con la chiave xpath, e un XPath che non si compila dà 400 con il nome del campo. Il contenitore di un gruppo deve essere CSS: {"xpath": ..., "fields": {...}} dà 400. Dentro i fields di un gruppo XPath non è supportato: un sottocampo XPath torna null in ogni riga, quindi lì usa CSS.

Imposta "group": true nella richiesta per unire i campi elenco in un oggetto per riga sotto items, invece di array paralleli da allineare a mano. Le righe sono costruite sull’elenco più lungo e un campo senza valore a quell’indice è null. Se gli elenchi hanno numeri diversi di elementi la risposta lo segnala, perché il riempimento avviene in fondo: se la lacuna reale era nel mezzo, ogni colonna successiva risulta sfalsata. Quando le righe possono avere lacune, preferisci il gruppo annidato sopra, che legge ogni valore dal contenitore della riga stessa e non può disallinearsi.

Quindi questa mappa di campi:

{
  "title": "h1",
  "price": ".price",
  "image": "img.gallery@src",
  "tags":  {"css": ".tag", "all": true}
}

produce questo oggetto di dati, campo per campo:

Quando un campo torna null

Un campo è null o perché la pagina davvero non ha quell'elemento, o perché il selettore stesso non si è potuto usare. Per te sono cose molto diverse, quindi le distinguiamo: se un selettore non si è potuto compilare, la risposta porta un oggetto field_errors che indica il campo e il motivo. Il campo resta presente in data come null (un array vuoto per un campo con "all": true), la richiesta resta un 200 e gli altri campi non ne risentono: un selettore inutilizzabile non affonda mai il resto dell'estrazione.

{
  "data": {"title": "Example Domain", "price": null, "tags": null},
  "field_errors": {
    "tags": "selector did not compile (unknown pseudoclass or pseudoelement :is) — this field is null because the selector could not be used, not because the page lacks the element"
  }
}

L'assenza della chiave field_errors significa che ogni selettore si è compilato, quindi lì un null è un vero «non è sulla pagina». L'XPath invece è validato a monte e restituisce 400.

Opzioni della richiesta

Funzionano su ogni endpoint che scarica una pagina: /v1/extract, /v1/fetch, /v1/batch, /v1/rank e dentro i job. Le opzioni del browser richiedono render.

Pagine JavaScript: render e wait_for

Se la pagina costruisce i contenuti con JavaScript, aggiungi "render": true. Avviamo un browser vero, lasciamo girare la pagina, poi leggiamo il DOM e applichiamo i tuoi selettori. Abbinalo a "wait_for" impostato su un selettore CSS per aspettare che quell'elemento compaia prima della lettura. È il modo affidabile di attendere contenuti che arrivano tardi:

curl https://scrape.land/v1/extract \
  -H "X-Api-Key: pb_live_YOURKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example-product.com/item/42",
    "render": true,
    "wait_for": "h1.title",
    "fields": {"title": "h1.title", "price": ".price"}
  }'

Estrazione con AI (descrivi i campi a parole)

Non vuoi scrivere e mantenere selettori? Invia un prompt invece di fields: recuperiamo la pagina (tutti i parametri sopra valgono ancora), la convertiamo in Markdown e un modello linguistico restituisce esattamente i campi che hai descritto, in JSON. I selettori si rompono quando cambia il markup di un sito; un prompt si adatta. Aggiungi uno schema opzionale (un oggetto JSON di key→tipo) per fissare la forma esatta dell'output. Passa model per scegliere il livello. "fast" è il predefinito: mediana 1,5 s, ed è la scelta giusta per quasi ogni estrazione, perché tirare fuori campi già scritti in pagina è un compito di lettura. "smart" ha una mediana di circa 10 s ed è migliore quando la risposta va dedotta dalla pagina invece che letta, ad esempio mettendo insieme un orario di inizio, una durata e un fuso orario. "max" usa il nostro modello più forte (mediana di circa 3 s) ed è per le estrazioni in cui ogni campo deve essere giusto. Ogni livello si fattura a partire da un minimo oltre all'unità di recupero (fast 2, smart 4, max 25 unità di richiesta), e una pagina molto grande o una risposta lunga si fattura di più, in proporzione a quanto è costata davvero la chiamata al modello. Un nome non riconosciuto è un 400 che elenca quelli validi. Se il livello che hai chiesto non è disponibile rispondiamo con l'altro invece di fallire, fatturiamo il livello che ha davvero servito e te lo diciamo restituendo requested_model accanto a model.

Stai facendo una domanda invece di elencare campi? Un prompt come "what's this business about?" è una domanda, non un elenco di campi, ma il modello deve comunque inventare i nomi delle chiavi (business, category, competitors_mentioned…) e tu devi indovinare quali ha scelto. Invia "structured": false e ricevi invece una risposta in linguaggio naturale sotto answer, senza alcuna chiave data:

curl https://scrape.land/v1/extract \
  -H "X-Api-Key: pb_live_YOURKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://scrape.land/",
    "prompt": "what's this business about?",
    "structured": false
  }'

{
  "url": "https://scrape.land/",
  "status": 200,
  "extracted_by": "ai",
  "model": "fast",
  "answer": "scrape.land is a web data-extraction API: you send a URL and it returns clean structured data, handling proxy rotation, retries, geo-targeting and JavaScript rendering for you. Pricing is flat per 1,000 delivered requests."
}

data e answer non sono mai entrambi presenti, quindi un client tipizzato si ramifica su quale dei due ha ricevuto invece di fare type-switch su un solo campo. structured vale true per impostazione predefinita, quindi nulla di ciò che invii già cambia. Costa esattamente le stesse unità di richiesta dell'estrazione strutturata: è la stessa pagina e la stessa chiamata al modello. Uno schema o un extract_type fissa una forma JSON e quindi implica output strutturato; inviarne uno insieme a "structured": false dà un 400 che nomina entrambi i campi invece di farci indovinare in silenzio. Non ha alcun effetto sull'estrazione con fields basata su selettori, che non arriva mai a un modello.

Ti serve un elenco? Chiedi "every product on the page" e ricevi l'array sotto data.items. Se la pagina non ha testo (una pagina solo-JS presa senza render), ricevi un 422 che ti dice di riprovare con "render": true, invece di una risposta piena di valori nulli.

curl https://scrape.land/v1/extract \
  -H "X-Api-Key: pb_live_YOURKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://books.toscrape.com/",
    "prompt": "the page title, and the title and price (as a number) of the first book"
  }'

{
  "url": "https://books.toscrape.com/",
  "status": 200,
  "extracted_by": "ai",
  "model": "fast",
  "data": {
    "page_title": "Books to Scrape",
    "first_book_title": "A Light in the Attic",
    "first_book_price": 51.77
  }
}

Auto-estrazione (una parola invece di uno schema)

L'auto-estrazione è estrazione con AI sotto il cofano, quindi richiede lo stesso piano Scale o superiore.

Per i tipi di pagina più comuni non serve nemmeno un prompt. Passa extract_type e applichiamo noi un prompt e uno schema curati, così ricevi un oggetto normalizzato: product, article, job, discussion, event, recipe, real_estate e profile. Il tuo prompt/schema ha comunque la precedenza se lo invii.

I preset girano sul livello predefinito fast e di solito rispondono in un paio di secondi. Passa "model": "smart" se una pagina è davvero ambigua, ci mette circa il doppio e costa più unità di richiesta. Le richieste sincrone hanno un budget di 150 s; oltre ricevi un 504, quindi manda quelle lente come job asincrono (POST /v1/jobs, budget di 5 minuti).

curl https://scrape.land/v1/extract \
  -H "X-Api-Key: pb_live_YOURKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html",
    "extract_type": "product",
    "model": "fast"
  }'

Ottenere le intestazioni di risposta

A volte ti servono le intestazioni di risposta, non solo il corpo: un Location di redirect, un Set-Cookie, un Content-Type. Aggiungi "headers": true e includiamo un oggetto headers accanto a data. I nomi delle intestazioni arrivano in forma canonica (Content-Type, Set-Cookie) e un'intestazione ripetuta è unita con ", ". L'oggetto contiene anche due intestazioni nostre: X-Proxy-Country, il paese di uscita da cui è partita la richiesta, e X-Proxy-Tier, il livello di uscita che l'ha trasportata (premium o pool). Nessuna delle due è un'intestazione della risposta HTTP dell'API stessa.

{
  "url": "https://example-product.com/item/42",
  "status": 200,
  "data": {"title": "Vintage desk lamp"},
  "headers": {
    "Content-Type": "text/html; charset=utf-8",
    "Set-Cookie": "sid=abc123; Path=/; HttpOnly",
    "Cache-Control": "max-age=300",
    "X-Proxy-Country": "US",
    "X-Proxy-Tier": "premium"
  }
}

Altri endpoint

curl https://scrape.land/v1/fetch \
  -H "X-Api-Key: pb_live_YOURKEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example-product.com/item/42", "format": "html"}'

{
  "url": "https://example-product.com/item/42",
  "status": 200,
  "html": "<!doctype html><html>…"
}

Quando la pagina restituita è una sfida anti-bot o un rifiuto (per esempio una pagina Cloudflare "Just a moment") invece del contenuto, la risposta contiene anche "blocked": true e l'header X-Scrapeland-Blocked: 1, anche se il target ha risposto 200. Riprova: le risposte bloccate non vengono mai fatturate.

Markdown pronto per gli LLM

"format": "markdown" restituisce la pagina come Markdown pulito sotto una chiave markdown, la forma che le pipeline RAG e le finestre di contesto degli LLM vogliono davvero, così non mandi tag HTML grezzi a un modello pagandoli come token. Gli elementi di contorno del sito (nav, header, footer, aside, script e stili) vengono tolti, titoli, elenchi, link, blocchi di codice e tabelle restano, e link e immagini relativi sono risolti in URL assoluti così un frammento funziona anche staccato dalla pagina di origine. Si combina con ogni altra opzione (country, session, render, wait_for, actions, fingerprint) e funziona anche in /v1/batch. Costa esattamente una unità di richiesta, come qualsiasi altro fetch; non c'è alcun sovrapprezzo per Markdown o AI.

curl https://scrape.land/v1/fetch \
  -H "X-Api-Key: pb_live_YOURKEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/blog/post", "format": "markdown", "render": true}'
# -> {"url":"...","status":200,"markdown":"# Post title\n\nBody text..."}

curl https://scrape.land/v1/batch \
  -H "X-Api-Key: pb_live_YOURKEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://a.example/", "https://b.example/"], "format": "text"}'

{
  "results": [
    {"url": "https://a.example/", "status": 200, "text": "…"},
    {"url": "https://b.example/", "error": "…"}
  ]
}

curl https://scrape.land/v1/search \
  -H "X-Api-Key: pb_live_YOURKEY" \
  -H "Content-Type: application/json" \
  -d '{"q": "best web scraping api", "count": 5}'

{
  "query": "best web scraping api",
  "count": 2,
  "results": [
    {"title": "…", "url": "https://…", "snippet": "…"},
    {"title": "…", "url": "https://…", "snippet": "…"}
  ]
}

curl https://scrape.land/v1/rank \
  -H "X-Api-Key: pb_live_YOURKEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/blog", "query": "in-depth technical tutorials", "top_k": 10}'

{
  "url": "https://example.com/blog",
  "query": "in-depth technical tutorials",
  "status": 200,
  "total_links": 84,
  "ranked": [
    {"url": "https://example.com/blog/go-generics",
     "text": "A deep dive into Go generics",
     "score": 0.93, "reason": "long-form technical tutorial"}
  ],
  "ranked_count": 10,
  "extracted_by": "ai",
  "model": "fast"
}

curl https://scrape.land/v1/jobs \
  -H "X-Api-Key: pb_live_YOURKEY" -H "Content-Type: application/json" \
  -d '{"type":"batch","urls":["https://a.example","https://b.example"],
       "fields":{"title":"h1"},"webhook_url":"https://your.app/hook"}'
# -> {"id":"job_ab12","status":"queued"}

# poll it:
curl https://scrape.land/v1/jobs/job_ab12 -H "X-Api-Key: pb_live_YOURKEY"
# -> {"id":"job_ab12","type":"batch","status":"done","result":{}}

# list recent jobs (newest first, no result blobs):
curl "https://scrape.land/v1/jobs?limit=20" -H "X-Api-Key: pb_live_YOURKEY"

Quando un job finisce facciamo un POST di {"id","status","result"} al tuo webhook_url, che deve essere un URL https pubblico (gli indirizzi interni e loopback sono rifiutati). I job girano fino a qualche minuto; ognuno è contabilizzato esattamente come la chiamata sincrona.

Verifica del webhook. Ogni consegna porta un'intestazione X-Scrapeland-Signature della forma t=<unix>,v1=<hex>, dove l'hex è HMAC-SHA256("<t>.<raw body>") con la chiave del tuo segreto webhook. Firma i byte GREZZI del corpo (non una copia riserializzata), confronta a tempo costante e rifiuta tutto ciò il cui t è più vecchio di qualche minuto: è questo a impedire che una consegna intercettata ti venga rigiocata contro più tardi. Chiedi il segreto al supporto se usi webhook_url.

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    ts, sig = parts.get("t", ""), parts.get("v1", "")
    if not ts or not sig or abs(time.time() - int(ts)) > tolerance:
        return False
    expected = hmac.new(secret.encode(),
                        ts.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, sig)

curl https://scrape.land/v1/places \
  -H "X-Api-Key: pb_live_YOURKEY" \
  -H "Content-Type: application/json" \
  -d '{"category": "dentist", "location": "Austin, TX", "website": "yes"}'

{
  "attribution": "© OpenStreetMap contributors, ODbL (openstreetmap.org/copyright)",
  "bbox": [30.0985133, -97.9367663, 30.5166255, -97.5605288],
  "category": "dentist",
  "count": 10,
  "matched": 79,
  "preview": true,
  "preview_note": "Free plan: the first 10 matches. Every paid plan returns up to 200 per call.",
  "results": [
    {"name": "Aloha Dental", "category": "dentist",
     "address": "1614 East Riverside Drive, 78741", "city": "Austin",
     "lat": 30.245304, "lon": -97.730394,
     "website": "https://www.aloha-dental.com/", "phone": "+1-512-707-7300",
     "email": "riverside@aloha-dental.com",
     "opening_hours": "Mo 08:00-17:00; Tu 09:00-18:00; We 08:00-17:00; Th 09:00-18:00; Fr 08:00-17:00",
     "osm_url": "https://www.openstreetmap.org/node/3856445942"},
    {"name": "Austin Dental", "category": "dentist",
     "address": "2206 West Parmer Ln, 78727", "city": "Austin",
     "lat": 30.417672, "lon": -97.698822,
     "website": "https://www.lifetimedental.com/", "phone": "+1-512-982-4006",
     "opening_hours": "Mo-Fr 07:30-17:00",
     "osm_url": "https://www.openstreetmap.org/way/383188243"}
  ],
  "units": 1
}

{
  "formats": ["html", "text", "markdown", "raw"],
  "render": {"enabled": true, "screenshot": true, "actions": true,
             "device": true, "block_resources": true, "fingerprint": true},
  "ai": {"enabled": true, "configured": true, "min_plan": "scale",
         "plan_scoped": true, "models": ["fast", "smart", "max"], "default": "fast"},
  "extract_types": ["product", "article", "job", "discussion",
                    "event", "recipe", "real_estate", "profile"],
  "endpoints": ["/v1/fetch", "/v1/extract", "/v1/rank", "/v1/batch",
                "/v1/search", "/v1/jobs", "/v1/places", "/v1/account",
                "/v1/capabilities", "/mcp"],
  "limits": {"batch_max_urls": 20, "links_max": 2000,
             "search_max_count": 10, "raw_max_bytes": 7340032,
             "max_response_bytes": 5242880,
             "max_response_bytes_scope": "key"}
}

{
  "plan": "scale",
  "included_requests_remaining": 2871400,
  "prepaid_credit_cents": 0,
  "rate_limit_rps": 200,
  "key_budget": {"max_requests": 0, "requests_used": 1234, "unlimited": true}
}

MCP server (Claude, Cursor and other AI clients)

scrape.land is also a remote Model Context Protocol server, so an AI assistant can fetch pages, extract data, search the web and find local businesses as tools. Endpoint: https://scrape.land/mcp (Streamable HTTP, JSON-RPC over POST). Authenticate with your API key as Authorization: Bearer YOUR_KEY. Each tool call runs the matching endpoint on your account, so it is billed, rate limited and plan gated exactly like the API.

Aggiungilo al tuo strumento AI. Sostituisci YOUR_KEY con una chiave API dalla dashboard; i pulsanti di installazione lo aggiungono con questo segnaposto, quindi apri poi le impostazioni del server e incolla la tua chiave.

Add to Cursor Add to Kiro

Claude (claude.ai, Desktop, mobile): Settings, Connectors, Add custom connector. Chiamalo scrape.land, imposta l'URL su https://scrape.land/mcp e aggiungi l'header di richiesta Authorization con il valore Bearer YOUR_KEY.

Claude Code:

claude mcp add --transport http scrape-land https://scrape.land/mcp --header "Authorization: Bearer YOUR_KEY"

Cursor, configurazione di Claude Desktop, Cline e altri client che usano una configurazione JSON mcpServers:

{
  "mcpServers": {
    "scrape-land": {
      "type": "http",
      "url": "https://scrape.land/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

VS Code (GitHub Copilot), in .vscode/mcp.json; VS Code chiede la chiave una sola volta e la conserva in modo sicuro:

{
  "inputs": [
    { "type": "promptString", "id": "scrapeland-key", "description": "scrape.land API key", "password": true }
  ],
  "servers": {
    "scrape-land": {
      "type": "http",
      "url": "https://scrape.land/mcp",
      "headers": { "Authorization": "Bearer ${input:scrapeland-key}" }
    }
  }
}

Gemini CLI, in ~/.gemini/settings.json:

{
  "mcpServers": {
    "scrape-land": {
      "httpUrl": "https://scrape.land/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Windsurf, in mcp_config.json:

{
  "mcpServers": {
    "scrape-land": {
      "serverUrl": "https://scrape.land/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Zed, in settings.json:

{
  "context_servers": {
    "scrape-land": {
      "url": "https://scrape.land/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

Il tuo agente, OpenAI Agents SDK (Python):

from agents import Agent, Runner
from agents.mcp import MCPServerStreamableHttp

async with MCPServerStreamableHttp(params={
    "url": "https://scrape.land/mcp",
    "headers": {"Authorization": "Bearer YOUR_KEY"},
}) as scrapeland:
    agent = Agent(name="researcher", mcp_servers=[scrapeland])
    result = await Runner.run(agent, "Find three dentists in Austin without a website")
    print(result.final_output)

Il tuo agente, Claude API (MCP connector, header beta anthropic-beta: mcp-client-2025-11-20):

{
  "model": "claude-sonnet-5",
  "max_tokens": 2048,
  "messages": [{ "role": "user", "content": "Summarise https://example.com" }],
  "mcp_servers": [{
    "type": "url",
    "url": "https://scrape.land/mcp",
    "name": "scrape-land",
    "authorization_token": "YOUR_KEY"
  }],
  "tools": [{ "type": "mcp_toolset", "mcp_server_name": "scrape-land" }]
}

SDK Python e migrazione da Zyte

Il nostro client Python racchiude sia l'API di estrazione sia il tunnel grezzo, e include un adattatore drop-in per il client Zyte API. Sei già su Zyte? Cambia l'import e la chiave: le forme della richiesta e della risposta coincidono.

pip install scrapeland

from scrapeland import ScrapelandClient

client = ScrapelandClient("pb_live_YOURKEY")          # or $SCRAPELAND_API_KEY

# structured extraction:
res = client.extract("https://example-product.com/item/42", {"title": "h1"})

# raw tunnel fetch through a fresh exit IP:
r = client.get("https://api.ipify.org", country="us", session="job42")

# or hand the tunnel mapping to your existing requests/httpx code:
import requests
requests.get("https://api.ipify.org", proxies=client.proxies(country="de"))

Tunnel grezzo (avanzato)

La maggior parte delle persone vuole dati strutturati e dovrebbe usare l'API di estrazione qui sopra. Se invece ti serve l'accesso HTTP grezzo alla pagina, il tunnel grezzo è un forward proxy: punta qualsiasi client HTTP verso di esso con la tua chiave API come nome utente, e ogni richiesta esce da un IP nuovo, con controlli opzionali di paese, sessione e protocollo. Host: gateway.scrape.land:8080.

curl -x http://pb_live_YOURKEY:@gateway.scrape.land:8080 https://api.ipify.org
# -> an exit IP, different on each request

Parametri di controllo

Aggiungi coppie -nome-valore alla chiave nel nome utente, oppure invia intestazioni di controllo X-Proxy-*. Ti colleghi sempre al gateway come a un proxy HTTP (schema http://); protocol sceglie quale tipo di proxy di uscita porta avanti la richiesta: http, https o socks5.

Generatore di URL per il tunnel

Scegli le opzioni e copia il comando pronto da eseguire. Sostituisci YOURKEY con una chiave dalla tua dashboard.

Usare il tunnel dal codice

import requests

KEY = "pb_live_YOURKEY"
proxy = f"http://{KEY}-country-us:@gateway.scrape.land:8080"
r = requests.get("https://api.ipify.org?format=json",
                 proxies={"http": proxy, "https": proxy}, timeout=30)
print(r.json())   # {'ip': '...'}  a US exit IP

import { ProxyAgent, fetch } from "undici";   // npm i undici

const KEY = "pb_live_YOURKEY";
// The key is the proxy username and the password is empty. undici only builds
// Proxy-Authorization from a URL that has both, so pass it as a token.
const dispatcher = new ProxyAgent({
  uri: "http://gateway.scrape.land:8080",
  token: "Basic " + Buffer.from(`${KEY}-country-gb:`).toString("base64"),
});
// Node's fetch ignores an `agent` option: the tunnel goes in `dispatcher`.
const res = await fetch("https://api.ipify.org?format=json", { dispatcher });
console.log(await res.json());   // { ip: '...' }  a GB exit IP

p, _ := url.Parse("http://pb_live_YOURKEY-country-us:@gateway.scrape.land:8080")
client := &http.Client{Transport: &http.Transport{Proxy: http.ProxyURL(p)}}
resp, _ := client.Get("https://api.ipify.org")

import { chromium } from "playwright";

const browser = await chromium.launch({
  proxy: {
    server: "http://gateway.scrape.land:8080",
    username: "pb_live_YOURKEY-country-us",
    password: "",
  },
});
const page = await browser.newPage();
await page.goto("https://api.ipify.org");

# settings.py
DOWNLOADER_MIDDLEWARES = {
    "scrapeland.scrapy.ScrapelandMiddleware": 740,
}
SCRAPELAND_API_KEY = "pb_live_YOURKEY"
SCRAPELAND_COUNTRY = "us"            # optional default for every request

# per-request override:
yield scrapy.Request(url, meta={"scrapeland": {"country": "de", "session": "job42"}})

Errori

{
  "error": "AI extraction (prompt, schema, extract_type) is not included on the \"free\" plan (it needs \"scale\" or above). Upgrade on the Plans page of your dashboard, or use CSS/XPath \"fields\" extraction, which every plan includes.",
  "code": "plan-upgrade-required",
  "plan": "free",
  "required_plan": "scale",
  "fallback": "use CSS/XPath \"fields\" extraction, which every plan includes",
  "capability": "AI extraction (prompt, schema, extract_type)"
}

Gli stati del sito di destinazione (i suoi 200/403/404) sono trasmessi invariati. Il paese di uscita non è un'intestazione della risposta dell'API stessa: invia "headers": true e lo trovi come X-Proxy-Country dentro l'oggetto headers. Sul tunnel grezzo, X-Proxy-Country è sulla risposta al CONNECT per le destinazioni https:// e sulla risposta stessa per le destinazioni http://.

Limiti del piano

Con il piano cambiano quattro cose: quanto in fretta puoi inviare richieste, quanto può essere grande una singola risposta, se l'estrazione con AI è disponibile e se ottieni le uscite prioritarie. Valgono allo stesso modo per l'API di estrazione e per il tunnel grezzo. GET /v1/capabilities con la tua chiave restituisce i tuoi diritti sotto entitlements, e GET /v1/account i tuoi numeri.

Pool costa $19/mese ($190/anno) ed è senza conteggio: non ha un numero mensile di richieste, e il rate limit di 10 richieste/s è l'unico tetto. Gira su uscite senza priorità, non include l'estrazione con AI né il rendering nel browser, e include gli strumenti di lead generation (POST /v1/places).

Rate limit. Richieste al secondo sostenute, applicate per account su tutte le chiavi che possiedi (un limite per chiave non sarebbe affatto un limite: le chiavi si creano gratis); una singola chiave può essere limitata più in basso. Brevi picchi oltre il limite sono tollerati. Sopra di esso ricevi un 429 con un'intestazione Retry-After: rallenta e prosegui, non si perde nulla e non si fattura nulla. La velocità di ogni piano è dimensionata perché una corsa a tavoletta sull'intera dotazione mensile duri ore e non minuti.

Risposta massima. La risposta singola più grande che restituiamo, esposta come limits.max_response_bytes in GET /v1/capabilities. Le pagine reali non ci si avvicinano (la risposta mediana che serviamo è di circa 40 KB e il 99% sta sotto 1,2 MB) quindi intercetta solo un video, un archivio o un dump di dati. Tutto ciò che è più grande viene rifiutato per intero con un 413 che indica dimensione, limite e piano. Non restituiamo mai una pagina troncata, e una risposta rifiutata non viene fatturata.

La fatturazione non supera mai quello che hai pagato. Le richieste incluse si consumano per prime. Dopo di esse, le richieste attingono al credito prepagato a $0,20 / 1.000: il saldo scende e si ferma a zero, e a quel punto le richieste restituiscono 402 invece di proseguire. Non c'è alcuna fattura a posteriori né modo di accumulare una spesa che non hai autorizzato in anticipo.

Guide

Sessioni a rotazione vs. sticky

Per impostazione predefinita ogni richiesta esce da un IP nuovo (ottimo per distribuire il carico ed evitare i rate limit). Quando ti serve lo stesso IP tra più richieste (login, carrelli, flussi in più passi) aggiungi un parametro session (o -session-NOME sul tunnel); fissiamo quella sessione su un solo IP di uscita per circa 10 minuti, poi ruota. Usa un nome di sessione diverso per ogni utente logico.

Gestione dei rate limit e degli errori

• Il target restituisce 429/403: riprova. Una nuova richiesta ruota su un IP nuovo. Aggiungi un piccolo backoff.
• 402 da noi: la tua quota o il tuo saldo è esaurito. Passa a un piano superiore o ricarica.
• 401/407 da noi: la chiave API manca o è sbagliata (intestazione per l'API, nome utente per il tunnel).
• 502 da noi: nessun upstream corrisponde ai tuoi filtri. Allenta country/maxlatency e riprova.

import requests, time

KEY = "pb_live_YOURKEY"
def get(url, tries=4):
    for i in range(tries):
        proxy = f"http://{KEY}:@gateway.scrape.land:8080"   # fresh IP each try
        try:
            r = requests.get(url, proxies={"http": proxy, "https": proxy}, timeout=30)
            if r.status_code < 400:
                return r
        except requests.RequestException:
            pass
        time.sleep(2 ** i)        # exponential backoff
    raise RuntimeError("all retries failed")

Domande frequenti

Esiste un piano gratuito?

Sì: 1.000 richieste, senza carta. Il piano a pagamento più economico è Pool a $19/mese (senza conteggio, a 10 richieste/s, senza estrazione con AI né rendering). I piani a consumo partono da $99/mese (600k richieste = $0,165 / 1k) e la tariffa migliora salendo di livello: $0,139 / 1k su Business ($999 / 7,2M) e $0,100 / 1k su Business Ultra ($9.999 / 100M). Vedi Limiti del piano per la scala completa.

Come vengo fatturato?

Per 1.000 richieste consegnate. Se un proxy è bloccato o restituisce 403/429, riproviamo con un altro IP e non lo fatturiamo mai. Paghi solo quando la pagina torna.

Le richieste incluse nel tuo piano si consumano per prime. Dopo di esse, le richieste escono dal credito prepagato a $0,20 / 1.000: ricarichi in anticipo, il saldo scende e si ferma a zero. Non c'è alcuna fattura a posteriori né modo di accumulare un conto che non hai autorizzato. Senza abbonamento, il credito prepagato costa gli stessi $0,20 / 1.000. Il pay-as-you-go come piano a sé arriva nel 2027; oggi non è in vendita.

Posso scegliere un paese specifico?

Sì. Sull'API di estrazione aggiungi "country": "us" al corpo della richiesta. Sul tunnel grezzo aggiungi -country-us (qualsiasi codice ISO) alla tua chiave. Vedi il generatore di URL per il tunnel.

Come estraggo pagine che richiedono JavaScript?

Aggiungi "render": true alla tua richiesta di estrazione e "wait_for" con un selettore CSS se il contenuto arriva tardi. Vedi render e wait_for.

Offrite IP residenziali?

Oggi il pool è fatto di IP a rotazione di tipo datacenter/ISP, autovalidati di continuo. I pool residenziali/mobili sono nella roadmap (piani premium).

È legale?

Sono strumenti standard; sei tu il responsabile di usarli in modo lecito e di rispettare i termini dei siti di destinazione. Vedi i nostri Termini.