Transformă orice URL în JSON curat.

API de extragere a datelor

Dă-ne un URL și un set de câmpuri. Aducem pagina, aplicăm selectorii tăi CSS și returnăm JSON curat. Niciun browser de rulat, niciun cod de parsare, nicio rotație de IP de gestionat. URL-ul de bază pentru fiecare endpoint este https://scrape.land.

Există o singură cerere pe care o vei folosi cel mai des: POST /v1/extract. Restul acestei secțiuni arată exact acea cerere, apoi o transpune în fiecare limbaj ca să o poți integra rapid.

Autentificare

Trimite cheia ta API în antetul X-Api-Key la fiecare cerere:

X-Api-Key: pb_live_YOURKEY

Merge și un antet bearer Authorization, dacă se potrivește mai bine cu stack-ul tău:

Authorization: Bearer pb_live_YOURKEY

POST/v1/extract

Cererea canonică. Trimite un url și o hartă fields și primești înapoi un obiect data cu o cheie pentru fiecare câmp. Este aceeași cerere folosită în fiecare exemplu de limbaj de mai jos.

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",
      "image": {"css": "img.gallery", "attr": "src"},
      "tags":  {"css": ".tag", "all": true}
    }
  }'

Răspuns. Fiecare cheie din data corespunde câmpului pe care l-ai cerut:

{
  "url": "https://example-product.com/item/42",
  "status": 200,
  "data": {
    "title": "Vintage desk lamp",
    "price": "49.00",
    "image": "https://example-product.com/img/a.jpg",
    "tags": ["retro", "lighting", "brass"]
  }
}

Cum se mapează câmpurile la selectori

Fiecare intrare din fields ia una dintre aceste forme:

• Un selector CSS ca șir. Returnăm textul primului element care se potrivește. "title": "h1" returnează textul din primul h1.
• O prescurtare selector@attr pentru a citi un atribut. "image": "img.gallery@src" returnează src; folosește @text sau niciun parametru pentru text.
• O prescurtare XPath: orice șir care începe cu / este tratat ca XPath. "title": "//h1/text()", "link": "//a/@href".
• Un obiect cu css plus chei opționale: attr (citește un atribut în loc de text), all (returnează fiecare potrivire ca listă) sau xpath (o expresie XPath în loc de css). Se pot combina.

Deci această hartă de câmpuri:

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

produce acest obiect de date, câmp cu câmp:

Când un câmp revine null

Un câmp este null fie pentru că pagina chiar nu are un astfel de element, fie pentru că selectorul în sine nu a putut fi folosit. Pentru tine sunt lucruri foarte diferite, așa că le deosebim: dacă un selector nu a putut fi compilat, răspunsul poartă un obiect field_errors care numește câmpul și motivul. Câmpul rămâne prezent în data ca null, cererea rămâne un 200, iar celelalte câmpuri nu sunt afectate — un selector inutilizabil nu scufundă niciodată restul extragerii.

{
  "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"
  }
}

Lipsa cheii field_errors înseamnă că fiecare selector s-a compilat, deci un null acolo este un „nu se află pe pagină” real. XPath este validat din start și returnează 400.

Pagini JavaScript: render și wait_for

Dacă pagina își construiește conținutul cu JavaScript, adaugă "render": true. Pornim un browser real, lăsăm pagina să ruleze, apoi citim DOM-ul și aplicăm selectorii tăi. Combină-l cu "wait_for" setat pe un selector CSS, ca să așteptăm până apare acel element înainte de citire — modul sigur de a aștepta conținut care se încarcă târziu:

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"}
  }'

Alți parametri opționali de nivel superior pe care îi poți adăuga la orice cerere de extragere:

Extragere cu AI (descrie câmpurile în limbaj natural)

Nu vrei să scrii și să întreții selectori? Trimite un prompt în loc de fields: aducem pagina (toți parametrii de mai sus se aplică în continuare), o convertim în Markdown, iar un model de limbaj returnează exact câmpurile pe care le-ai descris, ca JSON. Selectorii se strică atunci când se schimbă markupul unui site; un prompt se adaptează. Adaugă o schema opțională (un obiect JSON de key→tip) ca să fixezi forma exactă a răspunsului. Trimite model ca să alegi un nivel de putere: "fast" (implicit — mediană 1,5 s și alegerea potrivită pentru aproape orice extragere, fiindcă a scoate dintr-o pagină câmpuri care sunt scrise acolo este o sarcină de citire) sau "smart" (mediană 3,4 s și mai bun când răspunsul trebuie dedus din pagină, nu doar citit — de pildă combinând o oră de început, o durată și un fus orar — facturat la o rată mai mare de unități de cerere). Un nume necunoscut este un 400 care le enumeră pe cele valide. Dacă nivelul cerut nu este disponibil, răspundem pe celălalt în loc să eșuăm, facturăm nivelul care a servit efectiv și îți spunem returnând requested_model alături de model.

Pui o întrebare în loc să enumeri câmpuri? Un prompt precum "what's this business about?" este o întrebare, nu o listă de câmpuri — dar modelul tot trebuie să inventeze nume de chei pentru ea (business, category, competitors_mentioned…), iar tu trebuie să ghicești ce a ales. Trimite "structured": false și primești în schimb un răspuns în limbaj natural sub answer, fără nicio cheie 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 și answer nu apar niciodată împreună, deci un client tipizat ramifică după cea pe care a primit-o, în loc să facă type-switch pe un singur câmp. structured este implicit true, deci nimic din ce trimiți deja nu se schimbă. Costă exact aceleași unități de cerere ca extragerea structurată — este aceeași pagină și același apel de model. O schema sau un extract_type fixează o formă JSON și deci implică ieșire structurată; trimițându-le împreună cu "structured": false primești un 400 care numește ambele câmpuri, în loc să ghicim în tăcere ce ai vrut. Nu are niciun efect asupra extragerii cu fields pe bază de selectori, care nu ajunge niciodată la un model.

Ai nevoie de o listă? Cere "every product on the page" și primești lista înapoi sub data.items. Dacă pagina nu are text (o pagină doar-JS adusă fără render), primești un 422 care îți spune să reîncerci cu "render": true, în loc de un răspuns plin de valori nule.

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-extragere (un cuvânt în loc de schemă)

Auto-extragerea este tot extragere cu AI dedesubt, deci cere același plan Scale sau mai sus.

Pentru tipurile de pagină uzuale nu ai nevoie nici măcar de un prompt. Trimite extract_type și aplicăm noi un prompt și o schemă îngrijite, ca să primești înapoi un obiect normalizat: product, article, job, discussion, event, recipe, real_estate și profile. prompt-ul sau schema ta au întâietate dacă le trimiți și pe ele.

Preseturile rulează pe nivelul implicit fast și răspund de obicei în câteva secunde. Trimite "model": "smart" dacă o pagină este chiar ambiguă — durează cam de două ori mai mult și costă mai multe unități de cerere. Cererile sincrone au un buget de 150 s; peste el primești un 504, deci trimite una lentă ca job asincron (POST /v1/jobs, buget de 5 minute).

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"
  }'

Obținerea anteturilor de răspuns

Uneori ai nevoie de anteturile de răspuns, nu doar de corp: un Location de redirect, un Set-Cookie, un Content-Type. Adaugă "headers": true și includem un obiect headers alături de data.

{
  "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"
  }
}

Mai multe endpointuri

POST/v1/fetch

Când vrei pagina întreagă în loc de câmpuri anume, folosește /v1/fetch. Setează format pe html (implicit), text (textul vizibil), markdown sau raw (octeți base64 + content_type, pentru PDF-uri/imagini/binare, până la 7 MiB). Se aplică aceleași opțiuni country, session, render, wait_for și headers.

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"}'

Markdown gata pentru LLM

"format": "markdown" returnează pagina ca Markdown curat sub o cheie markdown — forma pe care pipeline-urile RAG și ferestrele de context ale LLM-urilor chiar o vor, ca să nu trimiți etichete HTML brute unui model și să le plătești ca tokeni. Elementele de șablon ale site-ului (nav, header, footer, aside, scripturi și stiluri) sunt scoase, titlurile, listele, linkurile, blocurile de cod și tabelele sunt păstrate, iar linkurile și imaginile relative sunt rezolvate la URL-uri absolute, ca un fragment să funcționeze și după ce este separat de pagina sursă. Se combină cu orice altă opțiune — country, session, render, wait_for, actions, fingerprint — și funcționează și în /v1/batch. Costă exact o unitate de cerere, la fel ca orice alt fetch — nu există niciun supliment pentru Markdown sau 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..."}

POST/v1/batch

Adu până la 20 de URL-uri într-un singur apel. Trimite o listă urls plus orice parametri comuni; primești o intrare results pentru fiecare URL, în ordinea de intrare — fiecare fie un rezultat obișnuit de fetch, fie un {"url","error"}. Fiecare URL se facturează ca o cerere livrată separată.

Extragere în masă: adaugă fields sau un prompt și fiecare URL este extras exact ca la /v1/extract — fiecare rezultat poartă un obiect data. Excelent pentru a transforma o listă de URL-uri în rânduri, într-un singur apel.

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"}'

POST/v1/search

Rulează o căutare web și primești înapoi rezultatele organice — title, url-ul real de destinație și un snippet — fără să parsezi tu un SERP. Trimite {"q": "...", "count": 10} plus orice parametri de proxy comuni. Se facturează ca o singură cerere livrată. count este plafonat la 10 — o singură pagină de rezultate de la motorul de căutare; ceri mai mult și tot 10 primești.

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}'

POST/v1/rank

Clasează linkurile de pe o pagină după cât de relevant este fiecare pentru un scop, ca să alegi ce sub-pagini să extragi în continuare în loc să parcurgi tot. Dă un url şi un query; noi aducem pagina, îi citim linkurile (cu tot cu textul ancorei), iar un LLM le returnează ordonate cu un score (0–1) şi un reason scurt. Este stateless: clasează linkurile pe care pagina le are deja şi nu le accesează. Adaugă top_k ca să limitezi lista, model ("fast"/"smart") şi orice parametri comuni de fetch. Dacă pasul AI eşuează, tot primeşti linkurile în ordinea din document, cu un ranking_error — codul tău nu se strică. Se taxează ca un fetch plus suprataxa AI; o clasare eşuată taxează doar fetch-ul.

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}'

POST/v1/jobs — async & webhooks

Pentru lucrări de durată (un batch mare, o randare lentă) rulează-le asincron: trimiți un job, primești imediat un id, apoi îl interoghezi sau primești rezultatul pe un webhook. Trimite parametrii obișnuiți ai operației plus type (fetch/extract/batch/search) și un webhook_url opțional.

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"

Când un job se termină trimitem un POST cu {"id","status","result"} către webhook_url-ul tău (un URL https public — cele interne/loopback sunt respinse). Joburile rulează până la câteva minute; fiecare este contorizat exact ca apelul sincron.

Verificarea webhookului. Fiecare livrare poartă un antet X-Scrapeland-Signature de forma t=<unix>,v1=<hex>, unde hexul este HMAC-SHA256("<t>.<raw body>") cu cheia secretului tău de webhook. Semnează octeții BRUȚI ai corpului (nu o copie reserializată), compară în timp constant și respinge orice are un t mai vechi de câteva minute — asta oprește o livrare capturată să fie reluată împotriva ta mai târziu. Cere secretul de la suport dacă folosești 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)

GET/v1/capabilities

Un endpoint cacheabil, ca să poți detecta din cod ce acceptă o instalare înainte de a trimite o cerere: formats și features disponibile, dacă render (și subopțiunile) și extragerea cu AI sunt pornite, models și extract_types ale AI-ului, endpoints-urile active și limits. Ambele SDK-uri îl expun ca capabilities().

Funcționează și fără cheie, dar trimite-ți X-Api-Key și răspunsul este adaptat contului tău. Extragerea cu AI depinde de plan (vezi Extragere cu AI), deci un apel fără cheie îți poate spune doar ce acceptă instalarea, în timp ce unul cu cheie îți spune ce poți apela tu: ai.enabled este atunci adevărat doar dacă planul tău îl include, iar extract_type/extract_types dispar odată cu el. ai.configured raportează instalarea, ai.min_plan numește planul de care ai avea nevoie, iar ai.plan_scoped îți spune dacă răspunsul a fost personalizat. Detectează pe ai.enabled și nu vei primi niciodată un da urmat de un 403.

{
  "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"], "default": "fast"},
  "extract_types": ["product", "article", "job", "discussion",
                    "event", "recipe", "real_estate", "profile"],
  "endpoints": ["/v1/fetch", "/v1/extract", "/v1/batch", "/v1/search",
                "/v1/jobs", "/v1/account", "/v1/capabilities"],
  "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"}
}

Dimensiunea răspunsului. limits.max_response_bytes este cel mai mare răspuns unic pe care îl returnăm și depinde de planul tău (Free și Starter 2 MB, Pay As You Go și Growth 5 MB, Scale 10 MB, Business 25 MB). Paginile reale sunt departe de această valoare — răspunsul median pe care îl servim are cam 40 KB, iar 99% sunt sub 1,2 MB — deci prinde doar un video, o arhivă sau un export de date. Un răspuns peste limită este refuzat în întregime, cu un 413 care numește dimensiunea, limita și planul tău; nu îți dăm niciodată o pagină trunchiată, pentru că o pagină care și-a pierdut coada în tăcere se facturează ca reușită și se parsează ca date corupte. limits.max_response_bytes_scope îți spune al cui număr ai primit: "key" când ai trimis un X-Api-Key (limita planului tău) sau "lowest_plan" când nu ai trimis — pragul minim pe care îl primește orice cont, deci mereu sigur pentru dimensionare, iar prezentarea unei chei nu poate decât să îl ridice.

GET/v1/account

Vezi din cod planul cheii tale, cota rămasă, creditul preplătit, rate limit-ul și bugetul per cheie (de ex. înainte de un job mare), în loc să deschizi panoul. Raportează întotdeauna doar contul tău. Ambele SDK-uri îl expun ca account().

{
  "plan": "pro",
  "included_requests_remaining": 421900,
  "prepaid_credit_cents": 0,
  "rate_limit_rps": 100,
  "key_budget": {"max_requests": 0, "requests_used": 1234, "unlimited": true}
}

Aceeași cerere, în fiecare limbaj

O cerere, transpusă idiomatic. Fiecare face același lucru: un POST HTTP către https://scrape.land/v1/extract cu antetul X-Api-Key și corpul JSON, apoi parsează răspunsul JSON.

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"];

SDK Python și migrarea de la Zyte

Clientul nostru Python înglobează atât API-ul de extragere, cât și tunelul brut, și include un adaptor drop-in pentru clientul Zyte API. Ești deja pe Zyte? Schimbă importul și cheia — formele cererii și ale răspunsului se potrivesc.

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"))

Tunel brut (avansat)

Majoritatea oamenilor vor date structurate și ar trebui să folosească API-ul de extragere de mai sus. Dacă în schimb ai nevoie chiar tu de acces HTTP brut la pagină, tunelul brut este un forward proxy: îndreaptă orice client HTTP spre el cu cheia ta API pe post de nume de utilizator, și fiecare cerere iese dintr-un IP nou, cu controale opționale de țară, sesiune și protocol. Gazdă: 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 de control

Adaugă perechi -nume-valoare la cheia din numele de utilizator, sau trimite anteturi de control X-Proxy-*.

Generator de URL pentru tunel

Alege-ți opțiunile și copiază comanda gata de rulat. Înlocuiește YOURKEY cu o cheie din panoul tău.

Folosirea tunelului din cod

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 { HttpsProxyAgent } from "https-proxy-agent";

const KEY = "pb_live_YOURKEY";
const agent = new HttpsProxyAgent(`http://${KEY}-country-gb:@gateway.scrape.land:8080`);
const res = await fetch("https://api.ipify.org?format=json", { agent });
console.log(await res.json());

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"}})

Erori

{
  "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)"
}

Antetul de răspuns X-Proxy-Country raportează țara de ieșire folosită. Statusurile site-ului țintă (200/403/404 ale site-ului însuși) sunt transmise neschimbate.

Limitele planului

Patru lucruri se schimbă odată cu planul: cât de repede ai voie să trimiți cereri, cât de mare poate fi un singur răspuns, dacă extragerea cu AI este disponibilă și dacă primești ieșiri prioritare. Se aplică identic pe API-ul de extragere și pe tunelul brut. GET /v1/capabilities cu cheia ta returnează drepturile tale sub entitlements, iar GET /v1/account cifrele tale.

Rate limit. Cereri pe secundă susținute, aplicate per cont pe toate cheile pe care le deții (o limită per cheie n-ar fi deloc o limită — cheile se creează gratis); o cheie individuală poate fi limitată și mai jos. Rafalele scurte peste limită sunt tolerate. Peste ea primești un 429 cu un antet Retry-After — încetinește și continuă, nu se pierde nimic și nu se facturează nimic. Rata fiecărui plan este dimensionată astfel încât o rulare la maximum pe toată alocația lunară să dureze ore, nu minute.

Răspuns maxim. Cel mai mare răspuns unic pe care îl returnăm, expus ca limits.max_response_bytes în GET /v1/capabilities. Paginile reale sunt departe de această valoare — răspunsul median pe care îl servim are cam 40 KB, iar 99% sunt sub 1,2 MB — deci prinde doar un video, o arhivă sau un export de date. Orice depășește este refuzat în întregime, cu un 413 care numește dimensiunea, limita și planul tău. Nu returnăm niciodată o pagină trunchiată, iar un răspuns refuzat nu se facturează.

Facturarea nu depășește niciodată ce ai plătit. Cererile incluse se consumă primele. După ele, cererile trag din creditul preplătit, la $0,20 / 1.000 — soldul scade și se oprește la zero, moment în care cererile returnează 402 în loc să continue. Nu există factură ulterioară și nicio cale de a acumula o cheltuială pe care nu ai autorizat-o dinainte.

Ghiduri

Sesiuni rotative vs. persistente

Implicit, fiecare cerere iese dintr-un IP nou (excelent pentru a distribui încărcarea și a evita rate limit-urile). Când ai nevoie de același IP între cereri (autentificări, coșuri, fluxuri în mai mulți pași) adaugă un parametru session (sau -session-NUME pe tunel); fixăm acea sesiune pe un singur IP de ieșire pentru vreo 10 minute, apoi se rotește. Folosește un nume de sesiune unic pentru fiecare utilizator logic.

Gestionarea rate limit-urilor și a erorilor

• Ținta returnează 429/403: reîncearcă. O cerere nouă se rotește spre un IP nou. Adaugă un mic backoff.
• 402 de la noi: cota sau soldul tău este epuizat. Treci pe un plan superior sau reîncarcă.
• 401/407 de la noi: cheia API lipsește sau este greșită (antet pentru API, nume de utilizator pentru tunel).
• 502 de la noi: niciun upstream nu s-a potrivit cu filtrele tale. Relaxează country/maxlatency și reîncearcă.

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")

Întrebări frecvente

Există un plan gratuit?

Da — 1.000 de cereri, fără card. Planurile plătite încep de la $99/lună (600k cereri = $0,165 / 1k), iar tariful se îmbunătățește pe măsură ce crește nivelul: $0,139 / 1k pe Business ($999 / 7,2M) și $0,100 / 1k pe Business Ultra ($9.999 / 100M). Vezi Limitele planului pentru scara completă.

Cum sunt facturat?

Per 1.000 de cereri livrate. Dacă un proxy este blocat sau returnează 403/429, reîncercăm cu alt IP și nu îl facturăm niciodată. Plătești doar când pagina revine.

Cererile incluse în planul tău se consumă primele. După ele, cererile ies din creditul preplătit, la $0,20 / 1.000 — reîncarci în avans, soldul scade și se oprește la zero. Nu există factură ulterioară și nicio cale de a acumula o notă pe care nu ai autorizat-o. Fără abonament, pay-as-you-go este $0,1165 / 1.000, cel mai ieftin tarif pe care îl vindem.

Pot alege o anumită țară?

Da. Pe API-ul de extragere adaugă "country": "us" în corpul cererii. Pe tunelul brut adaugă -country-us (orice cod ISO) la cheia ta. Vezi generatorul de URL pentru tunel.

Cum extrag pagini care au nevoie de JavaScript?

Adaugă "render": true la cererea ta de extragere și "wait_for" cu un selector CSS dacă tot conținutul se încarcă târziu. Vezi render și wait_for.

Oferiți IP-uri rezidențiale?

Astăzi pool-ul este format din IP-uri rotative de tip datacenter/ISP, autovalidate continuu. Pool-urile rezidențiale/mobile sunt pe foaia de parcurs (planuri premium).

Este legal?

Acestea sunt instrumente standard; tu ești responsabil să le folosești în mod legal și să respecți termenii site-urilor de destinație. Vezi Termenii noștri.