Uma API de web scraping faz as partes difíceis de coletar páginas da web por você: ela escolhe o proxy, executa o navegador quando uma página precisa, refaz as tentativas em caso de falha e devolve o HTML ou os dados que você pediu. Você envia uma requisição com uma URL; o serviço cuida de tudo entre você e o site.
Este guia leva você da primeira requisição até um scraper pequeno e confiável, usando a Web Scraping API da Shifter como exemplo. As etapas e os padrões são os mesmos para a maioria dos serviços desse tipo. Se você quiser entender primeiro o que acontece por trás da requisição, nosso artigo explicativo sobre como funciona uma web scraping API cobre isso.
Etapa 1: obtenha uma chave de API
Toda requisição é autenticada com uma chave de API. No painel da Shifter, abra Web Scraping API, depois API Keys, e copie uma chave ativa.
Mantenha a chave fora do seu código. Guarde-a em uma variável de ambiente, para que ela nunca acabe em um repositório ou em uma captura de tela:
export SHIFTER_SCRAPER_KEY="your-key-here"Etapa 2: faça sua primeira requisição
A API é um único endpoint, https://scrape.shifter.io/v1. Passe sua chave e a página que você quer como parâmetros de consulta:
curl "https://scrape.shifter.io/v1?api_key=$SHIFTER_SCRAPER_KEY&url=https://example.com"A resposta é o HTML da página, obtido através dos proxies da API. É tudo que uma requisição básica precisa.
Etapa 3: ative a renderização de JavaScript quando a página precisar
Muitos sites modernos enviam uma página quase vazia e montam o conteúdo no navegador com JavaScript. Se o HTML que você recebe estiver sem os dados que você vê no seu navegador, adicione render_js=1. A API então carrega a página em um navegador headless e retorna o resultado renderizado. Na Shifter, uma requisição renderizada custa o mesmo que uma comum.
Duas configurações relacionadas ajudam com páginas lentas:
wait_for_cssespera até que um elemento específico apareça antes de retornar, para que você não receba a página antes de seus dados terem carregado.timeoutdá mais tempo para sites lentos.
A renderização é mais lenta do que uma busca simples, então use-a apenas para páginas que precisam dela. Nosso guia sobre scraping de sites com muito JavaScript explica como identificar isso.
Etapa 4: obtenha JSON em vez de HTML
Analisar HTML manualmente é onde a maioria dos scrapers quebra. Em vez disso, descreva os campos que você quer com extract_rules: um objeto JSON mapeando cada nome de campo para um seletor CSS e o que retornar dele.
output | Retorna |
|---|---|
text | O texto do elemento |
html | O HTML interno do elemento |
@href, @src e assim por diante | O valor de um atributo |
Por exemplo, {"title": {"selector": "h1", "output": "text"}} retorna {"title": "Example Domain"} para example.com. Muitas páginas também incorporam seus dados já como JSON estruturado; nosso guia sobre extrair JSON-LD em vez de analisar HTML mostra como usá-lo.
Etapa 5: trate os erros corretamente
Todo scraper encontra falhas: sites lentos, páginas que não renderizam, requisições demais ao mesmo tempo. A API informa o que deu errado por meio do código de status, e a resposta correta depende de qual código você recebe:
| Status | Significado | O que fazer |
|---|---|---|
200 | Sucesso | Use a resposta |
400, 401, 403 | Um problema com sua requisição, chave ou recursos do plano | Corrija; tentar novamente não ajudará |
408 | O site de destino expirou (timeout) | Tente novamente, talvez com um timeout maior |
422 | A página falhou ao renderizar | Tente novamente; verifique se o site funciona em um navegador normal |
429 | Requisições simultâneas demais para o seu plano | Espere, depois tente novamente |
500 | Um erro interno | Tente novamente após um breve atraso |
Na Shifter, requisições com falha não são cobradas; você paga um crédito para cada resposta bem-sucedida. A API também tenta novamente internamente algumas falhas antes de responder, e essas contam como uma única chamada.
Juntando tudo
Aqui está um pequeno auxiliar em Python que envolve todas as cinco etapas: ele lê a chave do ambiente, adiciona renderização e extração quando você solicita, tenta novamente os erros que vale a pena tentar novamente com uma pausa crescente, e para imediatamente nos que precisam de uma correção.
import json
import os
import time
import requests
API = "https://scrape.shifter.io/v1"
RETRY = {408, 422, 429, 500} # worth another try after a pause
STOP = {400, 401, 403} # fix the request; retrying will not help
def scrape(url, render_js=False, extract_rules=None, attempts=3, session=None, wait=2.0):
"""Fetch one page through the Web Scraping API; returns text, or parsed JSON with extract_rules."""
session = session or requests.Session()
params = {"api_key": os.environ["SHIFTER_SCRAPER_KEY"], "url": url}
if render_js:
params["render_js"] = 1
if extract_rules:
params["extract_rules"] = json.dumps(extract_rules)
for attempt in range(1, attempts + 1):
response = session.get(API, params=params, timeout=120)
if response.status_code == 200:
return response.json() if extract_rules else response.text
if response.status_code in STOP or attempt == attempts or response.status_code not in RETRY:
raise RuntimeError(f"{url}: HTTP {response.status_code} {response.text[:200]}")
time.sleep(wait * attempt) # back off a little more each timeUsando-o:
from scrape_api import scrape
html = scrape("https://example.com")
data = scrape("https://example.com", extract_rules={"title": {"selector": "h1", "output": "text"}})
print(data["title"])Testamos a construção de requisições, as novas tentativas e as condições de parada do auxiliar contra respostas simuladas para cada código de status acima.
Se você é novo em lógica de novas tentativas, nosso guia sobre retry e backoff para web scrapers explica por que a pausa cresce a cada tentativa.
Etapa 6: escale
Quando as requisições individuais funcionarem, três coisas importam à medida que você cresce:
- Concorrência. Envie várias requisições ao mesmo tempo com um pool de threads ou um cliente assíncrono. Cada plano tem um limite de concorrência (de 20 a 500 requisições simultâneas na Shifter, dependendo do plano); fique abaixo dele e trate
429como um sinal para desacelerar. - Localização e tipo de proxy. Use o parâmetro
countrypara buscar uma página como ela aparece em um país específico. Nos planos Growth e acima,premium_proxyroteia as requisições por IPs residenciais para sites que bloqueiam tráfego de datacenter. - Sessões. Para fluxos de múltiplas etapas, um
session_idmantém o mesmo IP e os mesmos cookies entre as requisições.
Quando os dados começarem a fluir, armazene-os em algum lugar que você possa consultar. Nosso guia sobre mover dados da web scraping API para SQL cobre um pipeline limpo da resposta até a tabela.
Erros comuns de iniciantes
- Fixar a chave de API diretamente no código. Use uma variável de ambiente ou um gerenciador de segredos.
- Renderizar tudo. Tente primeiro uma requisição simples; renderize apenas as páginas que precisam disso.
- Tentar novamente tudo. Um
401falhará para sempre. Tente novamente apenas os erros que podem ter sucesso depois. - Analisar HTML manualmente. Use regras de extração ou JSON incorporado sempre que possível.
- Ignorar limites de concorrência. Requisições paralelas demais produzem
429s, não velocidade.
Perguntas frequentes
O que é uma web scraping API?
Um serviço que busca páginas da web para você por meio de seus próprios proxies e navegadores, lida com novas tentativas e bloqueios, e retorna o HTML ou os dados extraídos em resposta a uma única requisição.
Preciso saber programar para usar uma web scraping API?
Um pouco. Uma única requisição funciona pela linha de comando com curl, mas a maioria dos projetos reais usa um script curto em Python ou outra linguagem para enviar requisições, tratar erros e armazenar os resultados.
Quando devo ativar a renderização de JavaScript?
Quando o HTML retornado sem renderização estiver sem conteúdo que você vê no seu navegador. Muitos sites constroem suas páginas com JavaScript, e a renderização retorna a página como um navegador a exibiria.
Requisições com falha custam créditos?
Na Shifter, não. Você é cobrado um crédito por resposta bem-sucedida, e requisições com falha, incluindo erros do site de destino, são gratuitas.
Conclusão
Usar uma web scraping API se resume a alguns hábitos: manter a chave no ambiente, começar com requisições simples e adicionar renderização apenas onde necessário, pedir JSON com regras de extração em vez de analisar HTML, tentar novamente apenas os erros que podem ter sucesso depois, e respeitar a concorrência do seu plano. O auxiliar acima cobre todos eles em cerca de vinte linhas. Planos e limites estão na página de preços da Web Scraping API.