Introduza um URL e obtenha dados estruturados organizados

Scraping

O Yozh Scraper renderiza qualquer URL num navegador Playwright real e devolve exatamente o que pedes — campos extraídos, HTML bruto ou uma captura de ecrã da página completa. Cada extração é uma tarefa assíncrona: envie um URL, verifique o estado da tarefa e recupere o resultado. Proxies, modo discreto, predefinições e sessões autenticadas são todos suportados de forma nativa.

• Renderização real do navegador — O Playwright renderiza páginas criadas com JavaScript; desative render desativar para HTML estático.
• Extração estruturada — As regras de campos CSS ou XPath devolvem um objeto data , o que é muito mais eficiente do que descarregar e analisar HTML bruto por conta própria.
• Proxies integrados — CyberYozh residencial / LTE móvel / centro de dados, com segmentação geográfica e sem deteção de pool-id.
• Modo furtivo por predefinição — patches «playwright-stealth» (navigator.webdriver, impressão digital WebGL/Canvas, runtime do Chrome) para reduzir a deteção de bots.
• Predefinições — extrair dados da Amazon, Google, eBay, Walmart, YouTube e LinkedIn por nome, com autocorreção opcional do LLM.
• Sessões — sessões autenticadas geridas pelo servidor para alvos que iniciaram sessão, reutilizadas em várias recolhas de dados.

Início rápido

O raspador surge a partir da raiz docker-compose.yml (ao lado do rastreador):

cp .env.example .env          # set CYBERYOZH_API_KEY if using proxies
docker compose up --build
# scraper → http://localhost:8000
# crawler → http://localhost:8001

Verifique se está ativo:

curl http://localhost:8000/api/v1/health
# {"status":"ok","workers":2}

Utilização básica

Cada ponto final de scraping cria uma tarefa em segundo plano e devolve um job_id. Verifique o estado da tarefa e, em seguida, recupere os seus resultados.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://example.com", "proxy_type": "none" }'
# → { "job_id": "req_abc123" }

curl http://localhost:8000/api/v1/scrape/req_abc123          # status
curl http://localhost:8000/api/v1/scrape/req_abc123/results  # results

O resultado final inclui metadados e tudo o que tiver solicitado (data, raw_html, screenshot_base64):

{
  "job_id": "req_abc123",
  "status": "done",
  "total": 1, "done": 1,
  "results": [
    {
      "request_id": "req_abc123",
      "took_ms": 1234,
      "meta": { "url": "https://example.com", "final_url": "https://example.com/",
                "status_code": 200, "device": "desktop", "proxy_type": "none", "retries": 0 },
      "data": null, "raw_html": null, "screenshot_base64": null, "warnings": []
    }
  ]
}

Extrair dados

Aplicar uma extract regra e a resposta inclui um data objeto indexado pelos nomes dos teus campos — muito mais eficiente do que descarregar raw_html e analisá-lo você mesmo. As regras são css ou xpath.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{
    "url": "https://example.com",
    "extract": {
      "type": "css",
      "fields": {
        "title": { "selector": "h1", "attr": "text", "required": true }
      }
    }
  }'
# result → { "data": { "title": "Example Domain" } }

Cada campo é uma regra:

Utilize "type": "xpath" com seletores XPath (por exemplo, //h1) para a mesma forma.

Capturas de ecrã e HTML bruto

Definir screenshot: true para um PNG de página inteira (base64 em screenshot_base64) ou raw_html: true para obter o HTML completo após a renderização em raw_html.

curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://example.com", "screenshot": true, "raw_html": true }'

Proxies

Para uma extração de dados fiável, os proxies são essenciais — a maioria dos sites modernos bloqueia os pedidos diretos. O Yozh integra-se com o Serviço de Proxy CyberYozh; defina proxy_type em qualquer pedido.

Selecione um local com proxy_geo (country_code / region / city). Descubra o que comprou sem ter de procurar os IDs da piscina:

curl "http://localhost:8000/api/v1/proxies/available?proxy_type=res_rotating"
curl "http://localhost:8000/api/v1/proxies/countries"

Predefinições

Uma predefinição agrupa um perfil de pedido + modelo de URL + receita de análise, pelo que permite extrair dados de um site pelo nome, em vez de ter de montar manualmente um pedido. Estão disponíveis predefinições integradas para a Amazon, o Google, o eBay, o Walmart, o YouTube e o LinkedIn; também pode criar as suas próprias (CSS/XPath determinísticas ou geradas por IA).

curl -X POST http://localhost:8000/api/v1/scrape/preset/page 
  -H "Content-Type: application/json" 
  -d '{
    "source": "amazon_product",
    "preset_params": { "asin": "B08N5WRWNW" },
    "locale": "us",
    "llm": { "model": "openai/gpt-5.4-mini" }
  }'
# → { "job_id": "..." }  then GET /api/v1/scrape/<job_id>/results

Gerir predefinições através de GET /api/v1/presets, GET /api/v1/presets/{name}, e POST /api/v1/presets (os nomes das predefinições do utilizador têm de começar por user_).

Sessões

Sessões autenticadas geridas pelo servidor: crie uma, inicie sessão uma vez e, em seguida, passe o seu session_id para qualquer processo de rastreamento, para que as páginas sejam obtidas com os cookies guardados e o estado de armazenamento. Necessário para alvos que exigem início de sessão, como a linkedin_profile predefinição.

1. POST /api/v1/sessions — criar. Pinos device / proxy_type / proxy_geo e um TTL. Devolve { session_id, expires_at }.
2. POST /api/v1/sessions/{id}/login — executar novamente um script de início de sessão declarativo com creds no corpo: { script, creds }.
3. POST /api/v1/scrape/page com session_id set — scrape autenticado.
4. DELETE /api/v1/sessions/{id} — limpar.

# 1. create  →  {"session_id":"sess_...","expires_at":...}
curl -X POST http://localhost:8000/api/v1/sessions 
  -H "Content-Type: application/json" 
  -d '{ "device": "desktop", "proxy_type": "res_rotating" }'

# 2. log in (declarative DSL + creds)
curl -X POST http://localhost:8000/api/v1/sessions/sess_.../login 
  -H "Content-Type: application/json" 
  -d '{ "script": { "steps": [ {"op":"goto","url":"https://site/login"} ] },
        "creds": { "username": "...", "password": "..." } }'

# 3. scrape with the session
curl -X POST http://localhost:8000/api/v1/scrape/page 
  -H "Content-Type: application/json" 
  -d '{ "url": "https://site/secure", "session_id": "sess_...", "raw_html": true }'

Extracção em lote

Envie várias páginas num único trabalho com POST /api/v1/scrape/pages — cada entrada corresponde a um pedido completo de extração. Verifique o estado e obtenha os resultados através dos mesmos pontos de acesso do trabalho.

curl -X POST http://localhost:8000/api/v1/scrape/pages 
  -H "Content-Type: application/json" 
  -d '{
    "pages": [
      { "url": "https://example.com", "proxy_type": "none" },
      { "url": "https://example.org", "proxy_type": "none" }
    ]
  }'

MCP

O scraper disponibiliza um ponto de acesso do Protocolo de Contexto de Modelo em /mcp (HTTP Streamable). Aponte o Claude ou o Cursor para ele e as ferramentas aparecem automaticamente:

• run_scrape_page
• run_scrape_pages
• get_job_status
• get_job_result
• cancel_scrape_job
• health

"yozh-scraper": {
  "type": "http",
  "url": "http://localhost:8000/mcp"
}

Depois, basta perguntar: «Recolhe o conteúdo de https://example.com e diz-me o que está na página.» O mesmo ponto final funciona a partir de um agente LangChain ou de um nó da ferramenta cliente MCP do n8n.

Referência de configuração

Pedido — ScrapeRequest (selecionado)

Referência da API

Detalhes importantes