Como utilizar a WebScrapingAPI: Guia da API de extração de dados e do Web MCP

A API Scraper é um ponto de extremidade REST que recebe um URL de destino e devolve a página em HTML, JSON ou campos selecionados. A WebScrapingAPI gere os proxies, a rotação, o tratamento de acesso, as tentativas de repetição e a renderização opcional em JavaScript. Utilize-a quando já souber quais os URLs de que necessita e pretender o conteúdo da página sem ter de gerir uma infraestrutura de scraping.

A sua aplicação fornece a URL de destino e qualquer contexto de pedido, como um país ou um formato de saída. A WebScrapingAPI opera a camada de acesso por trás desse pedido: encaminhamento e rotação de proxies, estratégias de gestão de acesso, novas tentativas internas em relação ao destino e um navegador quando solicita a renderização. O que é devolvido é o corpo da página, um envelope JSON com metadados, um DOM JSON ou apenas os campos que selecionou. Quando uma solicitação não pode ser concluída, recebe um erro explícito e documentado, em vez de conteúdo incorreto apresentado silenciosamente.

Tudo o que está fora dessa camada fica a seu cargo: fontes, finalidade, análise, validação e armazenamento. A API elimina o trabalho relacionado com o proxy e o navegador, mas não o trabalho do pipeline.

Todos os planos, incluindo o período de teste, incluem renderização em JavaScript, segmentação por país em todas as regiões geográficas e rotação de proxies com gestão de acesso. Os planos diferem em termos de volume de pedidos, simultaneidade e suporte, e não em termos de funcionalidades.

Ainda está a decidir se uma API gerida é a opção certa para si? Leia sobre as vantagens e desvantagens de utilizar uma API de scraping em vez da sua própria pilha de tecnologias. Se precisar de resultados de pesquisa, cliques e tempos de espera numa página, ou de registos estruturados em vez de páginas, avance diretamente para a escolha entre as cinco APIs de Acesso à Web.

Crie uma conta, copie a sua chave de API do separador «Web Scraping API» no painel de controlo e guarde-a numa variável de ambiente. Em seguida, envie uma solicitação GET para https://api.webscrapingapi.com/v2 com a chave «api_key» e um URL codificado. Deixe que a sua biblioteca HTTP codifique os parâmetros e nunca chame a API a partir do código do navegador.

1. Registe-se. Crie uma conta WebScrapingAPI e confirme-a. O período de avaliação oferece-lhe 5 000 pedidos.
2. Copie a sua chave. No painel de controlo, abra o separador «Web Scraping API» no painel esquerdo e copie a sua chave API.
3. Guarde-a como um segredo. Coloque a chave numa variável de ambiente no servidor que irá efetuar as chamadas, conforme mostrado abaixo.
4. Envie a solicitação. Utilize um dos exemplos abaixo.

export WSA_API_KEY=...   # paste your key here, never into code

As chaves devem ser guardadas como segredos do lado do servidor, nunca no código do navegador, em aplicações móveis, repositórios públicos, registos, capturas de ecrã ou cadernos partilhados. Qualquer pessoa com a chave pode utilizar as solicitações do seu plano.

curl

curl --get "https://api.webscrapingapi.com/v2" \
  --data-urlencode "api_key=$WSA_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "render_js=1" \
  --data-urlencode "country=us"

--get com --data-urlencode indica ao curl para colocar cada parâmetro na string de consulta e codificá-lo com o formato percentual por si.

Python (Python 3 com pip install requests)

Este pequeno cliente é aquele em que o resto do guia se baseia. Ele lê a chave a partir de WSA_API_KEY, permite que o Requests codifique a string de consulta através de params= (consulte o guia de início rápido do Requests) e repete apenas as tentativas que valem a pena.

"""Minimal Scraper API client: env-var key, safe retries, optional JSON envelope.

Usage:
  export WSA_API_KEY=...            # never hardcode the key
  python wsa_scrape.py https://example.com
  python wsa_scrape.py https://example.com --render --country us --json
  python wsa_scrape.py https://example.com --dry-run   # print the request, no call
"""
import argparse
import json
import os
import sys
import time

import requests

ENDPOINT = "https://api.webscrapingapi.com/v2"
RETRYABLE = {429, 500, 503}          # back off and retry
FINAL = {400, 401, 403, 406}         # fix the request or the account; do not retry


def build_params(url, render=False, country=None, json_response=False, extract_rules=None):
    params = {"url": url}
    if render:
        params["render_js"] = "1"
    if country:
        params["country"] = country.lower()
    if json_response:
        params["json_response"] = "1"
    if extract_rules:
        # The API expects a JSON-stringified object; requests URL-encodes it.
        params["extract_rules"] = json.dumps(extract_rules, separators=(",", ":"))
    return params


def scrape(url, api_key, max_attempts=4, **opts):
    params = {"api_key": api_key, **build_params(url, **opts)}
    for attempt in range(1, max_attempts + 1):
        resp = requests.get(ENDPOINT, params=params, timeout=130)
        usage = {k: v for k, v in resp.headers.items() if k.lower().startswith("wsa-")}
        if resp.ok:
            return resp, usage
        if resp.status_code in FINAL:
            raise SystemExit(f"{resp.status_code}: {resp.text[:300]}")
        if resp.status_code == 422 and not opts.get("render"):
            # Scrape accepted but not completed (e.g. a challenge page). One rendered retry.
            opts["render"] = True
            params = {"api_key": api_key, **build_params(url, **opts)}
            continue
        if resp.status_code in RETRYABLE or resp.status_code == 422:
            time.sleep(min(2 ** attempt, 30))
            continue
        raise SystemExit(f"Unexpected {resp.status_code}: {resp.text[:300]}")
    raise SystemExit(f"Gave up after {max_attempts} attempts")


def main():
    ap = argparse.ArgumentParser()
    ap.add_argument("url")
    ap.add_argument("--render", action="store_true")
    ap.add_argument("--country")
    ap.add_argument("--json", dest="json_response", action="store_true")
    ap.add_argument("--dry-run", action="store_true")
    a = ap.parse_args()
    opts = dict(render=a.render, country=a.country, json_response=a.json_response)

    if a.dry_run:
        prepared = requests.Request("GET", ENDPOINT,
                                    params={"api_key": "REDACTED", **build_params(a.url, **opts)}).prepare()
        print(prepared.url)
        return

    api_key = os.environ.get("WSA_API_KEY")
    if not api_key:
        sys.exit("Set WSA_API_KEY first (dashboard -> Web Scraping API tab).")

    resp, usage = scrape(a.url, api_key, **opts)
    print("status:", resp.status_code)
    print("usage headers:", usage)
    if a.json_response:
        env = resp.json()
        print("initial-status-code:", env.get("initial-status-code"), "cost:", env.get("cost"), "type:", env.get("type"))
        print(env.get("body", "")[:300])
    else:
        print(resp.text[:300])


if __name__ == "__main__":
    main()

A --dry-run flag imprime o pedido exato sem o enviar, com a chave ocultada. Aqui está com um destino complicado que contém um espaço, um ?, e um &:

python wsa_scrape.py 'https://example.com/a b?x=1&y=2' --render --country US --json --dry-run

https://api.webscrapingapi.com/v2?api_key=REDACTED&url=https%3A%2F%2Fexample.com%2Fa+b%3Fx%3D1%26y%3D2&render_js=1&country=us&json_response=1

Node.js (Node 18 ou posterior, integrado fetch e URLSearchParams)

// Build a Scraper API request URL in Node 18+ without sending it.
// URLSearchParams handles encoding of the target URL and the extract_rules JSON.
const ENDPOINT = "https://api.webscrapingapi.com/v2";

export function buildScrapeUrl(apiKey, target, opts = {}) {
  const params = new URLSearchParams({ api_key: apiKey, url: target });
  if (opts.renderJs) params.set("render_js", "1");
  if (opts.country) params.set("country", opts.country);
  if (opts.extractRules) params.set("extract_rules", JSON.stringify(opts.extractRules));
  return `${ENDPOINT}?${params}`;
}

const target = "https://example.com/search?q=web scraping&page=2";
const url = buildScrapeUrl("REDACTED", target, {
  renderJs: true,
  country: "us",
  extractRules: { title: { selector: "h1", output: "text" } },
});
console.log(url);

// Round-trip check: the API sees exactly the original target and rules.
const parsed = new URL(url).searchParams;
console.log("url param decodes to original:", parsed.get("url") === target);
console.log("extract_rules parses:", JSON.parse(parsed.get("extract_rules")).title.selector);

// Live call (server-side only): uncomment with WSA_API_KEY set.
// const res = await fetch(buildScrapeUrl(process.env.WSA_API_KEY, "https://example.com"));
// console.log(res.status, res.headers.get("wsa-call-credit-usage"), (await res.text()).slice(0, 200));

Resultado:

https://api.webscrapingapi.com/v2?api_key=REDACTED&url=https%3A%2F%2Fexample.com%2Fsearch%3Fq%3Dweb+scraping%26page%3D2&render_js=1&country=us&extract_rules=%7B%22title%22%3A%7B%22selector%22%3A%22h1%22%2C%22output%22%3A%22text%22%7D%7D
url param decodes to original: true
extract_rules parses: h1

Por que é que a codificação é importante. O URL de destino é transmitido dentro da string de consulta de outro URL. Se colar https://example.com/search?q=web scraping&page=2 na forma bruta, o & termina o url parâmetro mais cedo, e page=2 chega à API como um parâmetro separado. A extração continua a «funcionar», mas na página errada. A codificação em percentagem, definida na RFC 3986, transforma ? em %3F e & em %26 , pelo que todo o destino é preservado. Deixa que seja uma biblioteca a tratar disso: URLSearchParams no Node, params= no Requests ou --data-urlencode no curl. A verificação de ida e volta acima comprova que a API recebe exatamente a cadeia de caracteres com que começou.

Prefere uma biblioteca cliente? A WebScrapingAPI mantém SDKs publicados para Node.js, Python, Java, PHP e Rust, além de uma integração com o Scrapy. Para análise e rastreamento para além da chamada à API, consulte estes padrões de scraping em Python para além da chamada à API.

Documentação: Enviar um pedido.

Apenas o `api_key` e a `url` são obrigatórios. Adicione `render_js` para páginas renderizadas pelo cliente, `country`, `city`, `state` ou `asn` para a localização, `extract_rules` ou `json_response` para saída estruturada, `async` para páginas lentas e o `method` com `body` para POST, PUT ou PATCH. O valor predefinido de timeout é de 120 000 milissegundos, sendo este o limite máximo.

Tabela 1: Parâmetros da API do Scraper

Os parâmetros booleanos aceitam 1 ou true para ativar uma funcionalidade e 0 ou false para a desativar, pelo que render_js=1 e render_js=true significam a mesma coisa. snapshot_id substitui url em vez de o juntar: só o envias quando recolhes o resultado de uma tarefa assíncrona.

POST, PUT e PATCH são direcionados para o mesmo /v2 ponto final com um body carga útil, e a documentação classifica-os como beta. Teste-os com um alvo de eco inofensivo, como https://httpbin.org/post antes de os direcionar para um formulário real. Se preferires que a operação falhe rapidamente em vez de esperar até dois minutos por um destino lento, define timeout um número mais baixo de milissegundos.

Comece cada novo alvo com os dois parâmetros obrigatórios, observe o que é devolvido e adicione opções uma de cada vez. Cada opção deve justificar a sua inclusão ao corrigir algo que tenha observado na resposta simples.

Documentação: Parâmetros da API.

Ative render_js=1 apenas quando os dados de que necessita estiverem em falta no HTML simples, porque a página os constrói com JavaScript. Efetue a recuperação sem renderização primeiro e verifique os seus campos-alvo. A renderização não custa créditos adicionais na API do Scraper, mas é mais lenta do que uma recuperação HTTP simples; por isso, utilize-a por alvo.

O teste requer uma única solicitação. Escolha um valor que consiga ver num navegador normal, como um preço, faça a recuperação da página sem renderização e procure-o no corpo da resposta. Se estiver presente, ignore a renderização. Se estiver em falta, significa que a página o gera com JavaScript após o carregamento; por isso, tente novamente com render_js=1.

Decida por alvo, não por projeto, e guarde a configuração junto de cada alvo na sua configuração. As páginas de listagem de um site podem enviar HTML completo, enquanto as suas páginas de produtos carregam preços a partir de um script.

A renderização também interage com erros. A documentação indica que uma página de erro devolvida após render_js foi desativada como uma das causas de uma resposta 422. É por isso que a política de repetição de tentativas neste guia efetua exatamente uma repetição com renderização após um 422 antes de desistir. Também pode combinar a renderização com json_dom=1 se pretender que a página renderizada seja apresentada como uma árvore JSON.

A renderização tem, no entanto, um limite. Se os dados só aparecerem depois de esperar por um elemento específico, clicar num botão, percorrer a página, introduzir texto num campo ou tirar uma captura de ecrã, já ultrapassou o que uma única solicitação da API do Scraper consegue fazer. Essa é a função da API do Navegador.

Adicione um código de país de duas letras, como «us», «de» ou «gb». Restrinja ainda mais com o nome da cidade (em minúsculas, sem espaços), o estado para cidades dos EUA ou da Austrália, ou «asn» para escolher uma rede. A segmentação geográfica não implica créditos adicionais. A disponibilidade de alvos por cidade e ASN pode variar consoante o plano e a localização geográfica; por isso, recorra ao nível do país quando necessário.

Preços, stock, idioma e resultados de pesquisa mudam frequentemente consoante a localização do visitante. O country parâmetro encaminha o seu pedido através de um proxy nesse país, e city, state, e asn restringe-a ainda mais. city necessita sempre countrye state serve para esclarecer ambiguidades entre cidades em us ou au.

Para confirmar a rota antes de confiar nela, utilize um serviço de eco de IP. Este pedido solicita uma saída em Berlim e devolve o endereço IP que o destino viu:

curl --get "https://api.webscrapingapi.com/v2" \
  --data-urlencode "api_key=$WSA_API_KEY" \
  --data-urlencode "url=https://httpbin.org/ip" \
  --data-urlencode "country=de" \
  --data-urlencode "city=berlin"

A segmentação ao nível do país está disponível para todas as regiões geográficas em todos os planos. A segmentação mais precisa é menos garantida: a disponibilidade exata pode depender do plano atual, da região geográfica e da rota. Por isso, considere a cidade e o ASN como pedidos, não como garantias. Se um deles não estiver disponível, tente novamente ao nível do país e confirme as localizações de que a sua carga de trabalho necessita durante o período de avaliação.

O Google é o único sítio onde não se deve recorrer a country. A documentação indica que não se deve combinar o parâmetro próprio do Google gl com os da API do Scraper country na mesma solicitação. Para resultados de pesquisa, utilize a API SERP, que considera a localização e o idioma como parte da própria pesquisa.

Passe `extract_rules` como um objeto JSON que mapeia nomes de saída para seletores CSS ou XPath. Cada regra pode devolver texto, HTML, um atributo, uma tabela ou campos aninhados, com todos os resultados para cada correspondência e limpos para remover espaços em branco. A API devolve então JSON com uma propriedade por regra, em vez da página completa.

A forma mais curta mapeia um nome para um seletor CSS e devolve o texto da primeira correspondência:

{"title": "h1"}

A forma «rule-object» adiciona opções. Utilize-a quando precisar de um atributo, HTML, todas as correspondências ou análise de tabelas:

{
  "title": {"selector": "h1", "output": "text"},
  "links": {"selector": "a", "output": "@href", "all": 1}
}

As opções são:

• selector: um seletor CSS ou uma expressão XPath. Os seletores que começam por / são tratados como XPath, a menos que defina selector_type para css ou xpath.
• output: text (o valor predefinido), html, @attr para um atributo como @href, table_json, table_array, ou um objeto de regra aninhado.
• all: 1 retorna todas as correspondências, 0 apenas a primeira.
• clean: 1 elimina os espaços em branco e as quebras de linha no início e no fim do texto.

As regras aninhadas lidam com cartões, linhas ou blocos de resultados de pesquisa repetidos. Seleciona-se o elemento exterior com all: 1, e, em seguida, define os campos a extrair de cada correspondência. A resposta envolve cada valor numa lista, pelo que deve esperar "title": ["..."] em vez de uma string simples.

Pré-visualize os seus seletores numa cópia guardada da página antes de gastar créditos. Guarde o HTML do alvo uma vez e, em seguida, itere as suas regras localmente até que estas devolvam o resultado esperado. O script abaixo é uma aproximação local para verificar seletores CSS com o Beautiful Soup, e não com o próprio motor da API, mas suporta as opções de regras aqui apresentadas. Instale-o com pip install beautifulsoup4.

O fixture (fixture.html):

<html><body>
  <h1>  Example Store  </h1>
  <div class="result"><h2>Blue Mug</h2><a href="/p/blue-mug">view</a><span class="price">$12.00</span></div>
  <div class="result"><h2>Red Mug</h2><a href="/p/red-mug">view</a><span class="price">$14.50</span></div>
  <table id="specs"><tr><th>Size</th><th>Material</th></tr><tr><td>350 ml</td><td>Ceramic</td></tr></table>
</body></html>

O script de pré-visualização (preview_rules.py):

"""Preview extract_rules selectors locally on saved HTML before spending credits.

This is a local approximation for checking CSS selectors, not the API's own engine.
It supports the rule options used here: selector, output (text, html, @attr, nested), all, clean.
"""
import json
import sys
from bs4 import BeautifulSoup

RULES = {
    "title": {"selector": "h1", "output": "text", "clean": 1},
    "products": {
        "selector": ".result",
        "all": 1,
        "output": {
            "name": {"selector": "h2", "output": "text"},
            "url": {"selector": "a", "output": "@href"},
            "price": {"selector": ".price", "output": "text"},
        },
    },
}


def apply_rule(node, rule):
    if isinstance(rule, str):
        rule = {"selector": rule}
    matches = node.select(rule["selector"])
    if not rule.get("all"):
        matches = matches[:1]
    out = rule.get("output", "text")
    values = []
    for m in matches:
        if isinstance(out, dict):
            values.append({k: first(apply_rule(m, r)) for k, r in out.items()})
        elif out == "html":
            values.append(str(m))
        elif out.startswith("@"):
            values.append(m.get(out[1:]))
        else:
            text = m.get_text()
            values.append(text.strip() if rule.get("clean") else text)
    return values


def first(v):
    return v[0] if v else None


html = open(sys.argv[1] if len(sys.argv) > 1 else "fixture.html").read()
soup = BeautifulSoup(html, "html.parser")
print(json.dumps({k: apply_rule(soup, r) for k, r in RULES.items()}, indent=2))
print("extract_rules param:", json.dumps(RULES, separators=(",", ":"))[:80], "...")

Resultado:

{
  "title": [
    "Example Store"
  ],
  "products": [
    {
      "name": "Blue Mug",
      "url": "/p/blue-mug",
      "price": "$12.00"
    },
    {
      "name": "Red Mug",
      "url": "/p/red-mug",
      "price": "$14.50"
    }
  ]
}
extract_rules param: {"title":{"selector":"h1","output":"text","clean":1},"products":{"selector":".re ...

Assim que a pré-visualização parecer correta, passe o mesmo RULES dicionário para build_params(..., extract_rules=RULES) no cliente Python, que o serializa e codifica por si. É na construção manual da cadeia de consulta que ocorrem a maioria dos erros. Se o valor não for um objeto convertido em cadeia de caracteres, a API rejeita o pedido com um erro de validação:

{"status": "Failure", "status_code": 400, "error": "Key `extract_rules` must be a stringified object."}

As regras, o esquema e a atualização dos seletores quando um site sofre alterações são da sua responsabilidade.

Documentação: Regras de extração.

Adicione json_response=1 para envolver o resultado em JSON com os cabeçalhos do destino, o código de estado inicial, o corpo, um tipo de html, json ou b64, o custo em créditos e os microdados extraídos e metadados JSON-LD. Utilize-a quando o seu pipeline armazenar metadados ou precisar do código de estado real do destino. Caso contrário, analise o corpo bruto.

Por predefinição, a API do Scraper devolve diretamente o corpo da página, que é o que a maioria dos analisadores HTML pretende. O envelope JSON destina-se a pipelines que precisam de saber mais sobre cada recuperação: com que estado o alvo realmente respondeu, qual foi o custo e que dados estruturados a página continha.

O envelope tem seis campos: headers (os cabeçalhos de resposta do destino), cost (créditos para o pedido), initial-status-code (o primeiro código de estado do destino), body (o conteúdo da página), type (html, json, ou b64), e metadata (microdados extraídos e JSON-LD).

Este analisador verifica o estado do destino antes de armazenar qualquer coisa, descodifica corpos binários e lê o custo. A entrada é um ficheiro de amostra que reflete o conjunto de campos documentado, não uma saída em tempo real:

"""Parse a json_response=1 envelope. sample_envelope.json mirrors the documented field set;
it is a SAMPLE, not live output."""
import base64
import json
import sys
from bs4 import BeautifulSoup

env = json.load(open(sys.argv[1] if len(sys.argv) > 1 else "sample_envelope.json"))

status = env["initial-status-code"]
if status >= 400:
    raise SystemExit(f"Target answered {status}; inspect before storing")

body = env["body"]
if env.get("type") == "b64":               # binary targets arrive base64-encoded
    body = base64.b64decode(body)

print("cost (credits):", env["cost"])
print("content-type:", env["headers"].get("content-type"))
print("json-ld blocks:", len(env["metadata"]["json-ld"]))
if env.get("type") == "html":
    print("title:", BeautifulSoup(body, "html.parser").title.get_text())

Saída na amostra:

cost (credits): 1
content-type: text/html; charset=UTF-8
json-ld blocks: 0
title: Example Domain

Existe também json_dom=1, que devolve a página como uma árvore JSON semelhante ao DOM. Se pretender campos específicos, as regras de extração são normalmente mais simples do que percorrer uma árvore inteira.

Não é necessário o envelope para acompanhar o custo. Cada resposta contém cabeçalhos personalizados com um WSA- prefixo:

• WSA-Scraped-Resolved-Url: o URL final após os redirecionamentos
• WSA-Scraped-Headers: os cabeçalhos de resposta do destino
• WSA-Client-Cookies: cookies definidos pelo JavaScript após o carregamento da página
• WSA-Call-Credit-Usage: créditos utilizados nesta solicitação
• WSA-Current-Credit-Usage: total de créditos utilizados após esta solicitação

Registe os dois cabeçalhos de créditos em cada chamada. O cliente Python acima já recolhe todos os WSA- cabeçalhos no seu usage dicionário. Ao longo de uma semana de execuções, esses registos indicam-lhe quais os alvos que custam mais e qual o plano de que necessita. Para a parte de armazenamento e validação do mesmo trabalho, consulte «Criar o seu primeiro pipeline de dados fiável».

Envie a solicitação com async=true. A API coloca a recolha na fila e devolve imediatamente um response_id. Posteriormente, chame o mesmo ponto final /v2 com api_key e snapshot_id definidos para esse ID para obter a página concluída. Faça consultas com atrasos crescentes em vez de manter as ligações abertas e guarde o ID com o trabalho.

Uma solicitação síncrona mantém uma ligação aberta até que a página seja devolvida, por um período de até 120 segundos. Isso funciona bem para um pequeno número de URLs, mas é inconveniente para alvos lentos, lotes grandes ou trabalhadores que não podem esperar dois minutos por solicitação. O modo assíncrono divide a chamada em «submit» e «collect»:

"""Queue a long scrape with async=true, then poll by snapshot_id.

Needs WSA_API_KEY. Without it, prints the two request shapes (key redacted)."""
import os
import time
import requests

ENDPOINT = "https://api.webscrapingapi.com/v2"
key = os.environ.get("WSA_API_KEY")
target = "https://example.com/"

if not key:
    for p in ({"api_key": "REDACTED", "url": target, "async": "true"},
              {"api_key": "REDACTED", "snapshot_id": "<response_id>"}):
        print(requests.Request("GET", ENDPOINT, params=p).prepare().url)
    raise SystemExit("dry run: set WSA_API_KEY to run live")

job = requests.get(ENDPOINT, params={"api_key": key, "url": target, "async": "true"}, timeout=30).json()
snapshot_id = job["response_id"]
for delay in (2, 4, 8, 16, 30, 30):
    time.sleep(delay)
    r = requests.get(ENDPOINT, params={"api_key": key, "snapshot_id": snapshot_id}, timeout=60)
    if r.ok and r.text.lstrip().startswith("<"):
        print(r.text[:200])
        break
    print("not ready:", r.status_code, r.text[:120])

Sem uma chave, o script apresenta os dois formatos de pedido que enviaria:

https://api.webscrapingapi.com/v2?api_key=REDACTED&url=https%3A%2F%2Fexample.com%2F&async=true
https://api.webscrapingapi.com/v2?api_key=REDACTED&snapshot_id=%3Cresponse_id%3E
dry run: set WSA_API_KEY to run live

O ciclo de sondagem é deliberadamente conservador. Faz uma pausa entre tentativas e trata tudo o que não seja uma página HTML concluída como «ainda não pronta». Em produção, guarde o response_id com o registo da tarefa assim que o obtiver, para que o reinício de um trabalhador não perca os resultados concluídos. Recolha instantâneos imediatamente, em vez de assumir que eles vão esperar indefinidamente.

Trate os códigos de erro 400, 401, 403 e 406 como correções a solicitar ou à sua conta, e não como novas tentativas. Aguarde e tente novamente nos códigos 429, 500 e 503. Um código 422 significa que a API aceitou a solicitação, mas não conseguiu concluir a extração; por exemplo, uma página de verificação servida como HTTP 200. Portanto, tente novamente uma vez com renderização antes de desistir.

Tabela 2: Códigos de estado e o que o seu código deve fazer

A scrape() função no cliente Python implementa esta tabela. Os erros finais (400, 401, 403, 406) são interrompidos imediatamente com o texto da resposta, uma vez que reenviar a mesma solicitação resultará no mesmo erro. Os erros que permitem novas tentativas (429, 500, 503) aguardam com um intervalo exponencial, limitado a 30 segundos, por um máximo de quatro tentativas. Um código 422 numa solicitação não renderizada aciona uma nova tentativa com renderização. Um erro 422 que persista é então submetido a um backoff como qualquer outro erro que pode ser repetido, até que as tentativas se esgotem.

Um código 401 merece uma análise mais aprofundada, pois abrange dois problemas diferentes. A ausência de uma chave devolve isto:

{"error":"Access denied. No key `api_key` provided."}

O mesmo código também significa que a sua conta esgotou a quota de crédito; por isso, verifique a utilização do plano antes de alternar as chaves.

No caso do 429, a solução reside normalmente na concorrência, e não na velocidade. Os planos permitem entre 5 e 500 pedidos simultâneos, por isso dimensione o seu conjunto de trabalhadores de acordo com o seu plano, em vez de o deixar crescer até que a API rejeite os pedidos. A referência ao código 429 da MDN aborda o próprio estado. Se um destino continuar a falhar após as tentativas de repetição, experimente estas soluções para resolver os bloqueios antes de mudar de ferramentas.

Documentação: Respostas e erros.

Os planos são dimensionados com base no número de pedidos mensais: o Starter custa 19 $ por 7 000, o Basic 49 $ por 20 000, o Standard 99 $ por 45 000, o Advanced custa 149 $ por 100 000, o Premium custa 249 $ por 180 000 e o Pro custa 599 $ por 450 000. A versão de avaliação inclui 5 000 pedidos. A renderização em JavaScript e a segmentação geográfica não implicam créditos adicionais em nenhum plano.

Tabela 3: Planos da API Scraper (preços em outubro de 2026)

O preço efetivo por cada 1 000 pedidos diminui cerca de metade ao passar do plano Starter para o Pro, pelo que o volume é mais importante do que as funcionalidades na hora de escolher um plano. A simultaneidade também é importante: se o seu pipeline precisar de 100 pedidos em curso ao mesmo tempo, isso define um limite mínimo, independentemente do volume mensal.

Para saber quanto está realmente a gastar, utilize o custo por chamada indicado pela API: o cost campo no envelope JSON ou no WSA-Call-Credit-Usage cabeçalho. Teste a sua combinação real de alvos durante o período de avaliação, registe esses valores e multiplique-os por um mês. Isso dir-lhe-á qual o plano que se adequa melhor do que qualquer estimativa.

Utilize a API Scraper quando tiver URLs e precisar de obter a página. Utilize a API Browser quando a página exigir tempos de espera, cliques, introdução de texto ou capturas de ecrã. Utilize a API SERP para resultados de pesquisa, a API Crawl para um conjunto delimitado de páginas relacionadas e a API Data para registos estruturados provenientes de fontes suportadas.

A WebScrapingAPI comercializa cinco APIs de acesso à Web. Estas sobrepõem-se menos do que os seus nomes sugerem, porque cada uma parte de uma entrada diferente.

Tabela 4: Qual é a API de acesso à Web mais adequada para a tarefa

Responda a estas perguntas por ordem e pare na primeira resposta afirmativa:

1. Está a partir de uma consulta de pesquisa? Utilize a API SERP. Esta devolve resultados estruturados por motor de busca, localização e idioma, pelo que não precisa de analisar as páginas de resultados por conta própria.
2. A sua fonte é uma das fontes suportadas pela API de Dados e pretende registos em vez de páginas? Utilize a API de Dados. Esta abrange 116 fontes públicas suportadas, e a WebScrapingAPI mantém os analisadores.
3. Precisa de um conjunto definido de páginas relacionadas em vez de um URL de cada vez? Utilize a API Crawl para a recolha limitada de várias páginas.
4. A página requer tempos de espera, cliques, digitação, passos de navegação ou uma captura de ecrã? Utilize a API do Navegador, que executa um navegador hospedado por trás de um pedido REST.
5. Caso contrário, utilize a API Scraper, render_js=1 apenas se o HTML simples não contiver os seus dados.

As APIs também combinam bem entre si. Um fluxo de trabalho comum utiliza a API SERP para descobrir URLs de resultados, faz com que a sua aplicação selecione as mais relevantes e, em seguida, recupera essas páginas com a API Scraper ou a API Browser. Os preços da API Browser e da API Crawl são definidos por orçamento. A API Scraper, a API SERP e a fonte Amazon da API Data têm planos mensais publicados, a partir de outubro de 2026.

Para uma comparação completa lado a lado, incluindo o que cada API executa e o que fica na sua aplicação, compare todas as cinco APIs de Acesso à Web.

O Web MCP é um servidor Model Context Protocol alojado em https://mcp.webscrapingapi.com/mcp. O seu agente liga-se com um token MCP dedicado e obtém web_read e web_read_more através da API Scraper ou da API Browser, além de web_search através da API SERP. Utiliza os seus planos e limites existentes, e um token não acrescenta qualquer quota.

O Web MCP não é um produto separado que tenha de adquirir. É uma camada de ligação sobre o acesso à API que a sua conta já possui, sem necessidade de instalar qualquer pacote nem de executar qualquer servidor.

O que precisa. Precisa de uma conta WebScrapingAPI com acesso à API SERP, à API Web Scraping ou à API Browser. Também precisa de um cliente MCP que suporte o transporte HTTP Streamable com um cabeçalho Authorization: Bearer , o esquema de token definido na RFC 6750. Os clientes que apenas suportam o início de sessão OAuth não conseguem estabelecer ligação.

Configuração. Como titular da conta, abra o MCP no painel de controlo, copie o URL do servidor e selecione «Criar token». O token é apresentado apenas uma vez, por isso guarde-o imediatamente no armazenamento secreto do seu cliente ou num gestor de palavras-passe. Cada conta pode ter até dez tokens ativos, e um token perdido deve ser revogado e substituído. A chave da API do seu produto não é um token do MCP e não deve ser incluída nas definições de ligação. Os clientes que aceitam um mcpServers objeto têm uma configuração como esta:

{
  "mcpServers": {
    "webscrapingapi": {
      "url": "https://mcp.webscrapingapi.com/mcp",
      "headers": { "Authorization": "Bearer ${WSA_MCP_TOKEN}" }
    }
  }
}

Substitua o espaço reservado pelo seu token do MCP, disponível em Painel de controlo → MCP. Alguns clientes leem-no a partir de uma variável de ambiente, enquanto outros têm um campo para o token, e a sintaxe de interpolação varia consoante o cliente. Defina o tempo de espera da ferramenta do cliente para mais de 60 segundos.

Tabela 5: Ferramentas Web do MCP

O seu cliente só deteta as ferramentas que a sua conta suporta. Sem acesso à API SERP, o agente ainda consegue ler os URLs que lhe fornecer, mas não consegue efetuar pesquisas.

Roteamento e faturação. As leituras utilizam a API do Scraper quando a sua conta a possui; caso contrário, utilizam a API do Navegador, e um utilizador avançado pode escolher uma delas através do backend argumento. As leituras da API Scraper utilizam créditos e são estáticas por predefinição. Quando o agente define render_js: true, isso conta como uma nova solicitação cobrada. As leituras da API do Navegador são sempre renderizadas e consomem largura de banda. Uma solicitação falhada ou uma cota esgotada nunca muda para outro produto.

Limites. Cada resultado da ferramenta tem um limite máximo de 16 KiB, pelo que as páginas longas são recebidas em partes que recolhe com web_read_more. Páginas com mais de 10 MiB de HTML devolvem um erro, e as capturas permanecem válidas até uma hora. O tempo limite de ligação à fonte é de 55 segundos. Cada token permite quatro chamadas simultâneas à ferramenta e quatro sessões ativas, e uma sessão termina após 15 minutos de inatividade, uma hora ou 1 000 pedidos.

Para uma visão mais abrangente de como os agentes utilizam dados da Web em tempo real, consulte estes padrões de acesso à Web por agentes.

Documentação: Introdução ao Web MCP e Utilização e erros.

A API Scraper recupera uma página por pedido, pelo que não clica, não digita, não percorre a página nem inicia sessão por si. As solicitações expiram após 120 segundos, a simultaneidade é limitada pelo plano e a cobertura por cidade ou ASN varia. Não consegue tornar uma página legal para recolha. Escolha outra API ou ferramenta quando esses limites se tornarem um problema.

• Sem interação. Uma solicitação devolve uma página. A espera por um seletor, cliques, digitação, deslocamento e capturas de ecrã são funções da API do Navegador.
• Sem pesquisa. Para resultados de motores de busca, utilize a API SERP em vez de extrair páginas de resultados.
• Uma URL de cada vez. Se a tarefa abranger um conjunto definido de páginas relacionadas, a API Crawl gere esse âmbito por si.
• Tempo limite de 120 segundos. Alvos lentos e lotes grandes devem ser processados através de pedidos assíncronos.
• Concorrência por plano. Desde 5 pedidos paralelos na versão de avaliação até 500 na versão Pro. Dimensiona os teus «workers» em conformidade.
• A cobertura geográfica varia. A segmentação ao nível do país é ampla, mas a disponibilidade por cidade e ASN depende do plano, da localização geográfica e da rota.
• As páginas com CAPTCHA podem ainda assim falhar. A API trata do acesso por si, mas alguns alvos terminam com um erro 422. Não garante a resolução de CAPTCHAs, por isso, esteja preparado para falhas ocasionais nos alvos mais difíceis.

Existe também uma linha de responsabilidade que nenhuma API elimina. É o utilizador que define quais as fontes elegíveis e para que servem os dados. Utilize o serviço apenas para páginas públicas que esteja autorizado a recolher, reveja os termos de cada site, siga as regras relativas aos dados pessoais e respeite as políticas relativas a robôs.

Para conhecer os hábitos que mantêm um scraper em bom funcionamento ao longo de meses, consulte estas melhores práticas de ciclo de vida com código funcional. Está a ponderar opções para além da WebScrapingAPI? O nosso guia para comparar APIs de scraping de outros fornecedores abrange o campo de forma mais abrangente.

Envie um pedido HTTP para o ponto final da API com a sua chave de API e o URL pretendido e, em seguida, leia a página a partir da resposta. Com a WebScrapingAPI, trata-se de um pedido GET para https://api.webscrapingapi.com/v2 com a chave API e um URL codificado. Adicione parâmetros de renderização, localização ou extração apenas quando o alvo os necessitar.

Instale o Requests, coloque a sua chave numa variável de ambiente e passe api_key e url no argumento params para que o Requests os codifique. Verifique o código de estado, tente novamente em caso de respostas 429 e 5xx com backoff e analise o corpo com o seu analisador HTML ou solicite à API o JSON com extract_rules.

Sim. A versão de avaliação da API Scraper inclui 5 000 pedidos e não tem qualquer custo inicial, com cinco pedidos simultâneos. A renderização em JavaScript e a segmentação por país estão incluídas, pelo que pode testar os alvos que lhe interessam antes de escolher um plano pago. Os planos pagos começam nos 19 $ por mês para 7 000 pedidos.

Não. Na API Scraper, o parâmetro `render_js=1` e a segmentação geográfica não consomem créditos adicionais em nenhum plano. No entanto, a renderização é mais lenta do que uma simples recuperação de dados, por isso ative-a apenas para páginas cujos dados estejam em falta no HTML inicial. Verifique o cabeçalho «WSA-Call-Credit-Usage» para confirmar o que cada chamada consumiu.

É um serviço que recupera páginas web por si e devolve o seu conteúdo ou campos selecionados num formato utilizável. O fornecedor executa proxies, tentativas de repetição e navegadores, e você envia um URL e opções. A API Scraper da WebScrapingAPI devolve HTML, um envelope JSON ou campos selecionados com regras de extração CSS ou XPath.

Tecnicamente, muitas páginas públicas podem ser obtidas, mas nem todas as páginas devem sê-lo. Alguns conteúdos estão protegidos por inícios de sessão, algumas páginas requerem interação com o navegador e os termos do site ou as leis relativas aos dados pessoais podem restringir a recolha. Utilize a API Scraper para páginas públicas que esteja autorizado a recolher e a API Browser quando as páginas necessitarem de interação.

Recupere as suas páginas e extraia os campos por si próprio, ou deixe que uma API de scraping faça a recuperação. Com a API Scraper, envie o URL da página com «extract_rules» que mapeiem nomes de campos para seletores CSS, e receberá JSON em resposta. Pré-visualize primeiro os seletores numa cópia guardada da página para evitar pedidos desperdiçados.

A API Scraper gere o encaminhamento por proxy, a rotação e as estratégias de acesso, mas não garante a resolução de CAPTCHAs. Se um alvo devolver uma página de desafio com o código HTTP 200, a API pode classificar a extração como uma falha 422, em vez de lhe enviar conteúdo incorreto. Tente novamente uma vez com renderização e, em seguida, analise o alvo.

Precisa de uma conta WebScrapingAPI com acesso à Scraper API, à Browser API ou à SERP API, um token MCP dedicado a partir do painel de controlo e um cliente MCP que suporte Streamable HTTP com um cabeçalho «bearer». Aponte o cliente para https://mcp.webscrapingapi.com/mcp. Os clientes que apenas suportam o início de sessão via OAuth não conseguem estabelecer ligação.

Sim, quando lê páginas através da Scraper API. Cada web_read é um pedido normal medido, e a repetição com renderização constitui outro pedido. O web_read_more continua a mesma captura sem uma nova cobrança. As pesquisas utilizam a sua cota da SERP API, e a criação de um token MCP não acrescenta quota.

A API Scraper gere proxies, rotação, novas tentativas e renderização de JavaScript por trás de uma única solicitação. A renderização e a segmentação geográfica não custam créditos adicionais, e as solicitações falhadas não são cobradas. Escolha um plano quando o período de teste lhe mostrar o que precisa.

A integrar um agente de IA? Adicione a API SERP para que o Web MCP possa pesquisar e ler. O período de avaliação inclui 100 pesquisas no Google.