SDK Python

Visão geral

O SDK Python oficial da Scrapeless fornece acesso a automação de navegador, scraping, crawling, proxies, resultados de busca e extração de chats de IA. Este guia segue o README do repositório do SDK, com exemplos executáveis e detalhes de configuração.

Requisitos

Python 3.8 ou posterior é declarado nos metadados do pacote. As integrações de navegador podem exigir uma versão mais recente do Python, dependendo da versão do Playwright ou Pyppeteer instalada.

Use um ambiente virtual para manter as dependências do SDK separadas de outros projetos.

Instalação

pip install scrapeless

O repositório usa python-dotenv para carregar variáveis de ambiente, mas seus metadados de pacote atuais não listam essa dependência. Instale-a junto com o SDK, se necessário:

pip install python-dotenv

Instale pyppeteer ou playwright separadamente ao usar a integração de navegador correspondente.

Autenticação / Chave de API

Faça login no painel da Scrapeless e crie uma chave de API. Exporte-a antes de executar os exemplos:

export SCRAPELESS_API_KEY="YOUR_API_KEY"

Mantenha sua chave de API no seu ambiente ou gerenciador de segredos em vez de fazer commit dela no controle de versão.

Scrapeless() lê SCRAPELESS_API_KEY. Você também pode passar uma entrada api_key no dicionário de configuração do cliente.

Início rápido

Salve isto como quickstart.py e execute python quickstart.py após definir sua chave de API.

from scrapeless import Scrapeless
from scrapeless.types import UniversalScrapingRequest
 
client = Scrapeless()
result = client.universal.scrape(UniversalScrapingRequest(
    actor='unlocker.webunlocker',
    input={'url': 'https://example.com', 'method': 'GET', 'redirect': False}
))
print(result)

Matriz de cobertura de produtos

Produto	Serviço do SDK	Cobertura
Agent Browser	`client.browser`	Cria e gerencia sessões de navegador remoto.
Browser Profiles	`client.profiles`	Persiste dados do navegador entre sessões.
Scraping API	`client.scraping`	Extrai dados estruturados usando actors de sites.
Web Unlocker	`client.universal`	Recupera conteúdo de sites protegidos.
Crawl	`client.scraping_crawl`	Faz scraping de uma página ou crawling de um site.
Google Search API	`client.deepserp`	Extrai resultados de mecanismos de busca.
Proxies	`client.proxies`	Gera URLs de conexão de proxy.
AI Scraper	`client.ai_scraper`	Cria tarefas de chat de IA e recupera seu status e resultados.

Exemplos de uso

Browser

Instale a integração de navegador com pip install pyppeteer.

Gerenciamento avançado de sessões de navegador com suporte aos frameworks Playwright e Pyppeteer, com recursos configuráveis de anti-detecção (por exemplo, spoofing de fingerprint, resolução de CAPTCHA) e fluxos de automação extensíveis:

from scrapeless import Scrapeless
from scrapeless.types import ICreateBrowser
import asyncio
import pyppeteer
 
client = Scrapeless()
 
 
async def example():
    # Create a browser session
    config = ICreateBrowser(
        session_name='sdk_test',
        session_ttl=180,
        proxy_country='US',
        session_recording=True
    )
    session = client.browser.create(config).__dict__
    browser_ws_endpoint = session['browser_ws_endpoint']
    print('Browser WebSocket endpoint created:', browser_ws_endpoint)
 
    # Connect to browser using pyppeteer
    browser = await pyppeteer.connect({'browserWSEndpoint': browser_ws_endpoint})
    try:
        page = await browser.newPage()
        await page.goto('https://example.com')
        print(await page.title())
    finally:
        await browser.close()
 
 
asyncio.run(example())

Browser Profile

Gerencie perfis de navegador para sessões persistentes.

from scrapeless import Scrapeless
 
client = Scrapeless()
profile = client.profiles.create('My Profile')
print(profile)

Scraping API

APIs de extração direta de dados para sites (por exemplo, e-commerce, plataformas de viagem). Recupere informações estruturadas de produtos, preços e avaliações com conectores pré-configurados:

from scrapeless import Scrapeless
from scrapeless.types import ScrapingTaskRequest
 
client = Scrapeless()
request = ScrapingTaskRequest(
    actor='scraper.google.search',
    input={'q': 'nike site:www.nike.com'}
)
result = client.scraping.scrape(request=request)
print(result)

Web Unlocker

Extraia dados de sites usando o Web Unlocker (exposto como client.universal).

from scrapeless import Scrapeless
from scrapeless.types import UniversalScrapingRequest
 
client = Scrapeless()
result = client.universal.scrape(UniversalScrapingRequest(
    actor='unlocker.webunlocker',
    input={'url': 'https://example.com', 'method': 'GET', 'redirect': False}
))
print(result)

Crawl

Extraia dados de páginas individuais ou percorra domínios inteiros, exportando em formatos como Markdown, JSON, HTML, capturas de tela e links.

from scrapeless import Scrapeless
 
client = Scrapeless()
 
result = client.scraping_crawl.scrape_url("https://example.com")
print(result)

Proxy

Gere uma URL de proxy usando suas configurações de gateway e sessão.

from scrapeless import Scrapeless
from scrapeless.types import ICreateProxy
 
client = Scrapeless()
proxy_url = client.proxies.proxy(ICreateProxy(
    country='US',
    session_duration=30,
    session_id=client.proxies.generate_session_id(),
    gateway='your-proxy-gateway:port'
))
print(proxy_url)

AI Scraper

Extraia conteúdo de chats de IA em massa para monitorar menções à marca, comparar respostas e analisar inteligência competitiva a partir dos modelos mais recentes. Recupere URLs, prompts, respostas em Markdown, citações e muito mais por meio de uma única integração.

Os actors suportados incluem scraper.chatgpt, scraper.perplexity, scraper.copilot, scraper.gemini, scraper.aimode, scraper.overview, scraper.grok e scraper.alexa. O JSON de input depende do actor; consulte a documentação do AI Scraper para parâmetros detalhados. O JSON opcional webhook contém uma url de callback.

from scrapeless import Scrapeless
from scrapeless.types import AIScraperTaskRequest
 
 
def main():
    client = Scrapeless()  # Uses SCRAPELESS_API_KEY
    task = client.ai_scraper.create_task(AIScraperTaskRequest(
        actor='scraper.chatgpt',
        input={
            'prompt': 'Most reliable proxy service for data extraction',
            'country': 'US',
            'web_search': True,
        },
        # Optional: webhook={'url': 'https://your-webhook.example.com'},
    ))
    print('Created task:', task)
 
    result = client.ai_scraper.get_task_result(task['task_id'])
    print('Task status and result:', result)
    # If status is 'running', call get_task_result again later.
    # If status is 'failed', message contains the failure reason.
 
 
if __name__ == '__main__':
    main()

Ambos os métodos retornam o JSON da API inalterado. A criação retorna task_id, status e, quando disponível, task_result. A recuperação de resultados retorna status, task_result quando disponível e message em caso de falha. O status é success, failed ou running; o SDK não faz polling automaticamente.

create_task aceita um AIScraperTaskRequest ou um dicionário; dicionários também permitem parâmetros adicionais da API. As respostas são dicionários.

Google Search API

from scrapeless import Scrapeless
from scrapeless.types import ScrapingTaskRequest
 
client = Scrapeless()
result = client.deepserp.scrape(ScrapingTaskRequest(
    actor='scraper.google.search',
    input={'q': 'nike site:www.nike.com'}
))
print(result)

Para integrações mais completas, navegue pelo diretório de exemplos do repositório.

Tratamento de erros

Capture ScrapelessError para falhas em requisições à API. Verifique separadamente o status de uma resposta do AI Scraper para tratar falhas de tarefas.

from scrapeless import Scrapeless, ScrapelessError
from scrapeless.types import UniversalScrapingRequest
 
client = Scrapeless()
try:
    result = client.universal.scrape(UniversalScrapingRequest(
        actor='unlocker.webunlocker',
        input={'url': 'https://example.com', 'method': 'GET'}
    ))
    print(result)
except ScrapelessError as error:
    print(f'Scrapeless API error: {error}')

A exceção Python atual expõe a mensagem de erro; ela não define um atributo status_code.

Configuração / Variáveis de ambiente

A chave de API é obrigatória. As substituições de endpoint são opcionais; a tabela mostra seus valores padrão.

Passe um dicionário para Scrapeless para substituir a configuração:

import os
from scrapeless import Scrapeless
 
client = Scrapeless({
    'api_key': os.environ['SCRAPELESS_API_KEY'],
    'timeout': 30000,  # Request timeout in milliseconds
    'base_api_url': 'https://api.scrapeless.com',
    'browser_api_url': 'https://browser.scrapeless.com',
    'scraping_crawl_api_url': 'https://api.scrapeless.com',
})

A configuração explícita tem precedência sobre as variáveis de ambiente. O timeout de requisição padrão é de 30.000 milissegundos.

Variável de ambiente	Finalidade / padrão
`SCRAPELESS_API_KEY`	Chave de API obrigatória, obtida no painel.
`SCRAPELESS_BASE_API_URL`	`https://api.scrapeless.com`
`SCRAPELESS_BROWSER_API_URL`	`https://browser.scrapeless.com`
`SCRAPELESS_CRAWL_API_URL`	`https://api.scrapeless.com`

Suporte

O SDK é distribuído sob a Licença MIT.

Projetos relacionados

Node.js / TypeScript SDK Go SDK