juscraper

Raspador de tribunais e outros sistemas relacionados ao poder judiciário brasileiro.

📦 Instalação

Via PyPI (Recomendado)

pip install juscraper

Com uv

uv add juscraper

Versão de Desenvolvimento

Para instalar a versão mais recente do repositório:

pip install git+https://github.com/jtrecenti/juscraper.git

🚀 Exemplo Rápido

import juscraper as jus

# Criar scraper para o TJSP
tjsp = jus.scraper('tjsp')

# Buscar jurisprudência
dados = tjsp.cjpg('golpe do pix', paginas=range(1, 4))
print(f"Encontrados {len(dados)} resultados")

# Visualizar primeiros resultados
dados.head()

📊 Implementações

Tribunais Disponíveis

Tribunal	Funcionalidades Disponíveis
STF	contar_decisoes, listar_decisoes
TJAC	cjsg, baixar_acordao, baixar_acordaos
TJAL	cjsg
TJAM	cjsg
TJAP	cjsg ⚠️
TJBA	cjsg
TJCE	cjsg
TJDFT	cjsg
TJES	cjsg, cjpg
TJGO	cjsg
TJMG	cposg, cjsg
TJMS	cjsg
TJMT	cjsg
TJPA	cjsg
TJPB	cjsg
TJPE	cpopg, cjsg
TJPI	cjsg
TJPR	cjsg
TJRJ	cjsg
TJRN	cjsg
TJRO	cjsg
TJRR	cjsg
TJRS	cjsg
TJSC	cjsg
TJSP	cpopg, cposg, cjsg, cjpg, baixar_acordao, baixar_acordaos, baixar_sentenca, baixar_sentencas
TJTO	cjsg, cjpg, cjsg_ementa
TRF1	cpopg
TRF3	cpopg, cjsg
TRF5	cpopg
TRF6	cpopg

Agregadores Disponíveis

Nome	Funcionalidades Disponíveis
ComunicaCNJ	listar_comunicacoes
Datajud	contar_processos, listar_processos
Falcao	listar_decisoes
JusBR	cpopg, download_documents
PDPJ	cpopg, contar, documentos, download_documents, existe, movimentos, partes, pesquisa

⚠️ TJAP — cjsg indisponível: desde ~2026 a busca de jurisprudência do TJAP (plataforma Tucujuris) passou a exigir um CAPTCHA Cloudflare Turnstile, validado no servidor. Como o raspador faz requisições HTTP puras (sem navegador), não há como gerar o token e o backend responde "A verificação de segurança falhou". Nesse caso cjsg levanta TJAPSecurityCheckError com a explicação, em vez de retornar vazio silenciosamente. Não há solução pela API pública. Ver issue #279.

Autenticação no JusBR e no PDPJ

JusBR e PDPJ usam o mesmo token JWT do SSO do PJe. Com o extra govbr, auth_govbr() abre o Google Chrome, o Chromium ou o Microsoft Edge instalado na máquina, num perfil temporário, no portal de serviços do PDPJ; a pessoa faz o login no gov.br, o token é capturado e a janela fecha sozinha:

pip install 'juscraper[govbr]'

import juscraper as jus

jusbr = jus.scraper("jusbr")
jusbr.auth_govbr()

O token fica em ~/.config/juscraper/pdpj_token.json (ou em $XDG_CONFIG_HOME/juscraper/), legível só pelo dono do arquivo, e as próximas instâncias do JusBR e do PDPJ o carregam sem novo login. Quando o portal entrega refresh token, o access token é renovado sozinho antes de vencer. Se o navegador não for encontrado, informe o executável em auth_govbr(navegador=...). O login exige navegador com janela e não roda no Google Colab nem em CI; nesses ambientes, passe o token em auth(token) ou na variável de ambiente PDPJ_JWT (o JusBR também aceita JUSBR_JWT).

Notebooks de Exemplo

[!WARNING] Ambiente de execução: estes notebooks fazem requisições reais a serviços externos e não têm compatibilidade garantida com o Google Colab. Tribunais podem bloquear ou limitar IPs compartilhados de provedores de nuvem e datacenters, mesmo quando a mesma consulta funciona em uma conexão local. Alguns exemplos também dependem de CAPTCHA, tokens de acesso ou dependências opcionais. A execução local no Jupyter é o ambiente de referência do projeto; uma falha de conexão no Colab não indica, por si só, uma regressão do juscraper.

• Exemplo TJAC
• Exemplo TJAL
• Exemplo TJAM
• Exemplo TJAP
• Exemplo TJBA
• Exemplo TJCE
• Exemplo TJDFT
• Exemplo TJES
• Exemplo TJGO
• Exemplo TJMG
• Exemplo TJMS
• Exemplo TJMT
• Exemplo TJPA
• Exemplo TJPB
• Exemplo TJPE

Detalhes

O pacote foi pensado para atender a requisitos básicos de consulta de dados de processos judiciais em alguns tribunais.

A maior parte dos tribunais implementa alguns dos métodos abaixo; as tabelas da seção Implementações dizem quais cada tribunal e agregador tem (o STF, por exemplo, tem listar_decisoes e contar_decisoes no lugar deles):

• .cpopg(): consulta de processos originários do primeiro grau
• .cposg(): consulta de processos originários do segundo grau
• .cjsg(): consulta de jurisprudência de segundo grau
• .cjpg(): consulta de julgados de primeiro grau

Os métodos .cpopg() e .cposg() recebem como input um número de processo no padrão CNJ (NNNNNNN-DD.AAAA.J.TT.OOOO), com ou sem separadores, e retorna um dict com tabelas dos elementos do processo (dados básicos, partes, movimentações, entre outros específicos por tribunal).

O método .cjsg() recebe como input parâmetros de busca de jurisprudência (que variam por tribunal) e retorna uma tabela com os resultados da consulta. Boa parte dos tribunais apresentam limites de paginação ao realizar buscas muito gerais (i.e. que retornam muitos resultados). Nesses casos, o método dará um aviso ao usuário com o número total de resultados, confirmando se deseja mesmo baixar todos os resultados.

Controle de arquivos

Caso o usuário queira controlar o armazenamento dos arquivos brutos dos processos, deverá implementar as seguintes funções:

• .cpopg_download(): baixa o arquivo bruto da consulta de processos originários do primeiro grau, retornando o caminho do arquivo baixado.
• .cpopg_parse(): lê e processa um arquivo bruto ou arquivos dentro de uma pasta resultantes da consulta de processos, retornando o dict com tabelas dos elementos do processo, como na função .cpopg().

O mesmo se aplica para as funções .cposg_download() e .cposg_parse().

Observação: Em alguns tribunais ou situações específicas, a consulta a um processo pode gerar vários arquivos brutos. Por esse motivo, toda consulta cria uma pasta com o número do processo e, dentro dessa pasta, cria os arquivos correspondentes ao download.

Para a função .cjsg(), uma consulta pode resultar

Diferenciais do juscraper

• Controle sobre arquivos brutos: o pacote fornece uma interface para baixar e armazenar arquivos brutos (HTML e JSON, por exemplo) dos processos. Por padrão, no entanto, esses arquivos brutos são descartados assim que os dados são processados, com exceção dos arquivos que apresentaram algum problema na leitura.

Restrições

Por ser um pacote bastante complexo e também nichado, adotamos algumas restrições sobre o escopo do pacote para que seja simples de usar.

• O pacote não utiliza paralelização, ou seja, se o usuário tiver interesse em realizar requisições em paralelo, deverá desenvolver as adaptações necessárias.
• O pacote não possui absolutamente todas as funcionalidades que os tribunais permitem. Se o usuário tiver interesse em consultar processos em mais tribunais, deverá desenvolver os raspadores.

Por que não um juscraper no R?

O pacote juscraper foi criado em python inicialmente com o propósito de ser usado em aulas de Ciência de Dados no Direito do Insper. Portanto, não houve incentivo nem fôlego para criar uma alternativa em R.

Já existem soluções usando o R para esses raspadores, como os pacotes tjsp e stj, mas a comunidade convergiu para soluções em python, que atualmente são mais populares.

Observação sobre o parâmetro paginas

O parâmetro paginas é 1-based em todos os scrapers. Ao utilizar as funções de download, range(1, n+1) faz o download das páginas 1 até n, ou seja, range(1, 4) baixa as páginas 1, 2 e 3. Onde suportado, passar um inteiro (ex: paginas=3) é equivalente a range(1, 4).

Exemplo de uso:

scraper.cjsg_download(pesquisa="dano moral", paginas=range(1, 6))  # Baixa as páginas 1 a 5
scraper.cjpg_download(pesquisa="contrato", paginas=range(1, 3))    # Baixa as páginas 1 e 2

Instalação em desenvolvimento

Para instalar o pacote em modo desenvolvimento, siga os passos abaixo:

# Clone o repositório (caso ainda não tenha feito)
$ git clone https://github.com/jtrecenti/juscraper.git
$ cd juscraper

# Instale as dependências e o pacote em modo editável
$ uv pip install -e .

Contribuição

Interessado em contribuir? Verifique as diretrizes de contribuição. Por favor, note que este projeto é lançado com um Código de Conduta. Ao contribuir para este projeto, você concorda em obedecer às suas termos.

Licença

juscraper foi criado por Julio Trecenti. Está licenciado sob os termos da licença MIT.

Créditos

juscraper foi criado com cookiecutter e o template py-pkgs-cookiecutter.