aggregators.datajud.client.DatajudScraper

aggregators.datajud.client.DatajudScraper(
    api_key=None,
    verbose=1,
    download_path=None,
    sleep_time=0.5,
)

Scraper for CNJ’s Datajud API.

Note

Diferente de outros agregadores migrados em #204, o DataJud nao usa self._request_with_retry no caminho quente: a funcao :func:download.call_datajud_api aplica um retry especializado (504/Timeout -> refaz 1 vez com size reduzido por FALLBACK_DIVISOR), incompativel com o backoff exponencial do HTTPScraper. A heranca aqui garante session/headers compartilhados e o cumprimento de #185, mas o transporte segue via :func:call_datajud_api.

Methods

Name	Description
contar_processos	Conta processos no DataJud sem baixar nenhum documento.
listar_processos	Lista processos do DataJud via API publica do CNJ.

contar_processos

aggregators.datajud.client.DatajudScraper.contar_processos(**kwargs)

Conta processos no DataJud sem baixar nenhum documento.

Útil para análise de viabilidade — antes de uma raspagem grande, descobrir o volume estimado por tribunal. Usa track_total_hits=True com size=0 (cap do Elasticsearch é 10000 quando track_total_hits é True apenas via flag boolean — aqui exigimos a contagem exata, então o backend devolve relation="eq" quando o total é conhecido).

Aceita o mesmo conjunto de filtros de :meth:listar_processos (tribunal, numero_processo, ano_ajuizamento, classe, assunto, data_ajuizamento_inicio/_fim, tipos_movimentacao, movimentos_codigo, orgao_julgador, query), excluindo apenas os parametros de paginacao (paginas, tamanho_pagina, mostrar_movs) — nao ha paginacao numa contagem. Veja a docstring de :meth:listar_processos para a semantica de cada filtro (formato dual ISO+compacto em dataAjuizamento, mapping amigavel de tipos_movimentacao, escape-hatch query).

Parameters

Name	Type	Description	Default
**kwargs		Filtros aceitos pelo schema :class:InputContarProcessosDataJud.	{}

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: Uma linha por tribunal consultado, com colunas
	pd.DataFrame	tribunal (sigla), alias (índice ES), count (int) e
	pd.DataFrame	relation ("eq" exato ou "gte" truncado pelo cap
	pd.DataFrame	interno do Elasticsearch). Quando a chamada falha para um
	pd.DataFrame	tribunal, count é None e a coluna error traz o
	pd.DataFrame	motivo.

Raises

Name	Type	Description
	TypeError	Quando um kwarg desconhecido é passado.
	ValidationError	Quando um filtro tem formato inválido (ex.: data_ajuizamento_* fora de ISO 8601), quando ano_ajuizamento coexiste com data_ajuizamento_*, quando query coexiste com filtros amigaveis, ou quando um nome em tipos_movimentacao nao esta mapeado.
	ValueError	Quando nem tribunal nem numero_processo são informados, ou quando a sigla não tem alias mapeado.

Exemplo

import juscraper as jus dj = jus.scraper(“datajud”) dj.contar_processos(tribunal=“TJSP”, ano_ajuizamento=2023, classe=“436”) tribunal alias count relation error 0 TJSP api_publica_tjsp 12345 eq None

Range de data ajuizamento + categoria de movimentacao

dj.contar_processos( … tribunal=“TRF1”, … data_ajuizamento_inicio=“2024-01-01”, … data_ajuizamento_fim=“2024-03-31”, … tipos_movimentacao=[“decisao”], … )

See also

— usa o mesmo conjunto de filtros mas baixa os processos.

listar_processos

aggregators.datajud.client.DatajudScraper.listar_processos(
    paginas=None,
    **kwargs,
)

Lista processos do DataJud via API publica do CNJ.

Filtros sao validados pelo schema :class:InputListarProcessosDataJud (extra="forbid"); kwargs desconhecidos viram TypeError com a mensagem DatajudScraper.listar_processos() got unexpected keyword argument(s): '<nome>' em vez de serem silenciosamente ignorados.

Parameters

Name	Type	Description	Default
**kwargs		Filtros aceitos pelo schema :class:InputListarProcessosDataJud. Listados abaixo (todos opcionais; None = sem filtro): * numero_processo (str | list[str]): CNJ formatado ou lista de CNJs. Quando informado sem tribunal, o alias- indice e inferido pelos digitos id_justica (pos. 14) + id_tribunal (pos. 15-16). CNJs invalidos ou nao mapeados emitem UserWarning e sao ignorados. * tribunal (str): Sigla do tribunal (ex.: "TJSP", "TRT2", "TRE-SP"). Mutuamente exclusivo com inferencia via numero_processo. * ano_ajuizamento (int): Filtra por ano de ajuizamento. Backend recebe range dual em dataAjuizamento (ISO YYYY-01-01 + compacto YYYYMMDDhhmmss). Mutuamente exclusivo com data_ajuizamento_inicio/_fim. * data_ajuizamento_inicio / data_ajuizamento_fim (str): Range de data de ajuizamento, formato YYYY-MM-DD (ISO 8601). Backend recebe bool.should com 2 range em dataAjuizamento (ISO + compacto), mesmo padrao dual- format do ano_ajuizamento (refs #51). Pode informar apenas inicio, apenas fim, ou ambos. Nao ha alias data_inicio/data_fim aqui (a convencao generica do projeto mapeia esses para data_julgamento_*, e o DataJud filtra por ajuizamento, nao julgamento). * classe (str): Codigo da classe processual CNJ. * assunto (list[str | int]): Lista de codigos de assuntos CNJ (TPU). Aceita int e str — int e a forma natural (codigos TPU sao inteiros); str e aceita por compatibilidade. O schema normaliza para str antes do payload, ja que o Elasticsearch coage int -> str em campos keyword. Backend: terms em assuntos.codigo. assuntos (plural) e aceito como alias deprecado. Refs #232. * tipos_movimentacao (list[str]): Nomes amigaveis de categorias de movimentacao (ex.: ["decisao", "sentenca"]). Resolvidos via TIPOS_MOVIMENTACAO para uma lista plana de codigos TPU CNJ. Para nomes nao mapeados, usar movimentos_codigo direto. Categorias atuais: decisao, sentenca, julgamento, tutela, transito_julgado. * movimentos_codigo (list[int | str]): Codigos TPU CNJ diretos. Aceita int e str — int e a forma natural; str e aceita por conveniencia (ex.: vinda de planilha/ CSV) e normalizada para int antes do payload. Concatenado com a lista resolvida de tipos_movimentacao (uniao). Backend: terms em movimentos.codigo. * orgao_julgador (str): Nome do orgao julgador (ex.: "Vara Civel de Brasilia"). Backend: match em orgaoJulgador.nome. * query (dict): Override total da query Elasticsearch. Quando fornecido, vira a chave query do payload literalmente. Mutuamente exclusivo com TODOS os filtros amigaveis acima (numero_processo, ano_ajuizamento, classe, assunto, data_ajuizamento_*, tipos_movimentacao, movimentos_codigo, orgao_julgador). Exige tribunal explicito (sem inferencia via CNJ). Em troca, oferece paridade com requisicao direta a /<alias>/_search — must_not, should com minimum_should_match, range em campos arbitrarios, wildcard, nested, etc. size/sort/_source/search_after (paginacao) continuam sendo controlados pela biblioteca. Shape oficial documentado em https://datajud-wiki.cnj.jus.br/api-publica/. * mostrar_movs (bool): Se True, inclui movimentos/movimentacoes no _source. Default False (paginacao mais leve). * paginas (int | list[int] | range): Intervalo 1-based. Aceita as 4 formas do contrato unico (refs #118): int (3 -> range(1, 4)), list ([3, 5] -> range(3, 6), baixa 3-5 contiguamente porque o cursor search_after e forwards-only), range (passthrough), None (default, todas). * tamanho_pagina (int): Hits por requisicao (default 5000, range 10-10000 conforme cap da API publica). Em caso de HTTP 504/Timeout, o client refaz a chamada com size // 4 automaticamente (1 retry, UserWarning); ainda assim, valores proximos de 10000 sao instaveis na pratica.	{}

Aliases deprecados

Sem aliases nesta API — DataJud nao tem pesquisa nem filtros de data baseados em DD/MM/AAAA, entao o pipeline canonico normalize_pesquisa/normalize_datas nao se aplica. Todos os filtros aceitam apenas o nome canonico listado acima.

Raises

Name	Type	Description
	TypeError	Quando um kwarg desconhecido e passado (traduzido de ValidationError por raise_on_extra_kwargs).
	ValidationError	Quando um filtro tem formato invalido (ex.: ano_ajuizamento nao-int, data_ajuizamento_* fora de ISO 8601), quando ano_ajuizamento coexiste com data_ajuizamento_*, quando query coexiste com filtros amigaveis, ou quando um nome em tipos_movimentacao nao esta mapeado.
	ValueError	Quando nem tribunal nem numero_processo sao informados, ou quando a sigla nao tem alias mapeado.

Returns

Name	Type	Description
	pd.DataFrame	pd.DataFrame: Um DataFrame com uma linha por processo. extra
	pd.DataFrame	do parser e passthrough do _source Elasticsearch — colunas
	pd.DataFrame	seguem nomenclatura camelCase do CNJ.

Exemplo

import juscraper as jus dj = jus.scraper(“datajud”) # Caminho amigavel: range de data + categoria de movimentacao df = dj.listar_processos( … tribunal=“TRF1”, … data_ajuizamento_inicio=“2024-01-01”, … data_ajuizamento_fim=“2024-03-31”, … tipos_movimentacao=[“decisao”, “sentenca”], … paginas=range(1, 3), … ) # Caminho query-override: paridade com requisicao direta df = dj.listar_processos( … tribunal=“TRF1”, … query={ … “bool”: { … “must_not”: [{“exists”: {“field”: “orgaoJulgador.nome”}}], … “should”: [{“match”: {“classe.nome”: “tutela”}}], … “minimum_should_match”: 1, … } … }, … paginas=1, … )

See also

— fonte da verdade dos filtros aceitos.