Raspagem de tribunais: requisição http.

Este tutorial introduz os principais elementos de uma requisição http e como realizá-la em tribunais de justiça e administrativos.

José de Jesus Filho https://github.com/jjesusfilho
2023-04-26

Introdução

Neste tutorial, mostro como realizar requisições http. Ele é parte de material de apoio para o curso de raspagem de tribunais de justiça e administrativos.

Os principais conceitos do protocolo http são apresentados. Antes de iniciar, vamos instalar um pacote muito importante para realizar requisições http, o pacote httr. Falaremos desse pacote extensivamente ao longo desse e dos demais tutoriais.

install.packages("httr")

Além do pacote httr, há um outro pacote, que eu mantenho, chamado JurisMiner. Ele possui algumas funções auxiliares na requisição. Instale ele também:

remotes::install_github("courtsbr/JurisMiner")

Carregue os dois pacotes:

Requisição http

Quando você escreve o endereço ou url de uma página na barra de endereços do seu navegador, uma série de ações acontecem e muitas informações são transmitidas entre seu computador (cliente) e o computador de quem hospeda a página consultada (servidor).

Essa transmissão de dados entre o servidor que hospeda a página e o seu navegador é controlada pelo protocolo http (Hypertext Transfer Protocol). O protocolo http assegura uma transmissão de dados segura e íntegra.

A esse processo de abrir uma página e visualizar os dados carregados, chamamos de requisição http. A requisição http possui partes, que basicamente são a url, os headers ou cabeçalhos e o corpo.

Além das partes, existe que é a ação ou método de requisição. Há vários métodos de requisição conhecidos, mas dois são de especial relevância para web scraping: GET e POST.

Métodos

URL

A URL é o endereço que você digita no seu navegador ou outro endereço gerado a partir da interação com, e.g., uma página de busca. Por exemplo, se você acessar a página de busca de julgados de primeiro grau do TJSP e fizer uma busca qualquer verá que o endereço (url), após a busca, é composto de vários componentes, os quais descreveremos abaixo:

Outros componentes: eventualmente, alguns componenentes como params, username, password e fragment são requeridos, mas são excepcionais e dificilmente encontraremos um caso na área jurídica.

Para ajudar com um exemplo, vá para a consulta processual do TJSP neste link e realize uma consulta qualquer. Irei realizar uma pesquisa pelo nome do advogado: Fulano de Tal. Após clicar em Consultar, a barra de endereços do navegador mostrará o seguinte endereço (role a barra para ver o endereço completo)

https://esaj.tjsp.jus.br/cpopg/search.do?conversationId=&cbPesquisa=NMADVOGADO&dadosConsulta.valorConsulta=fulano de tal&cdForo=-1

A URL acima contêm os seguintes compontes:

O pacote httr possui uma função importante para desagregar a url em seus componentes:

$scheme
[1] "https"

$hostname
[1] "esaj.tjsp.jus.br"

$port
NULL

$path
[1] "cpopg/search.do"

$query
$query$conversationId
[1] ""

$query$cbPesquisa
[1] "NMADVOGADO"

$query$dadosConsulta.valorConsulta
[1] "fulano de tal"

$query$cdForo
[1] "-1"


$params
NULL

$fragment
NULL

$username
NULL

$password
NULL

attr(,"class")
[1] "url"

Se você reproduzir esse processo no RStudio, verá que a url_parseada é uma lista com nove elementos e com a classe “url”. Um dos elementos, query, é também uma lista com quatro elementos (pode ser mais): conversationId, cbPesquisa, dadosConsulta.valorConsulta e cdForo. Exceto o primeiro, conversationId, que está fazio, os demais foram preenchidos por você, ao interagir com a interface do esaj.

Você pode alterar a query, por exemplo, para informar o nome de um advogado. Como em toda lista, você usa $ para acessar os elementos em níveis inferiores da lista.

Agora você pode reconstruir a url a partir da url_parseada com a função build_url:

[1] "https://esaj.tjsp.jus.br/cpopg/search.do?conversationId=&cbPesquisa=NMADVOGADO&dadosConsulta.valorConsulta=Michel%20Temer&cdForo=-1"

Note que Fulano de Tal foi efetivamente substituído por Michel Temer e, mais, os espaços foram adequadamente preenchidos por %20, que é uma forma mais segura de realizar a requisição. Experimente copiar esta nova url e colá-la na barra de endereços do seu navegador.

Cabeçalhos

Cabeçalhos ou headers são informações adicionais passadas tanto pelo cliente quanto pelo servidor quando da requisição. Há basicamente três tipos de cabeçalhos: Geral, de requisição e de resposta, dos quais falaremos em seguida. Antes, porém, abra o seu navegador e coloque a url acima ou Clique aqui.

Imagem: consulta advogado por nome

Aperte o botão direito do mouse e selecione a opção inspect. Você verá que irá abrir uma nova janela, que é a interface do desenvolvedor. Em seguida, dê Ctrl+Shift+R (control, shift, R) ou Cmd+Shift+R no Mac. Isso fará que a mesma página seja recarregada. Dentro dessa nova janela, você verá várias abas. Uma delas chama-se Network ou Rede, clique nela. Dentro da aba Network ou Rede, clique em Headers. Se tudo ocorreu bem, você verá algo mais ou menos assim, a depender do seu navegador:

Inspetor

Isso que você vê são os headers, dos quais falaremos em seguida. Tente familiarizar-se com eles, pois serão de extrema relevância para uma requisição http bem sucedida.

Cabeçalho geral

O cabeçalho geral contêm informações do status da requisição, a versão http e o tamanho do arquivo transmitido.

Status

A informação mais importante quando você realiza uma requisição http é saber o status, pois ele informa a condição do processamento da requisição. Há seis grupos de status, cada um deles inicia um número de 1 a 6 e é formado por três dígitos. Abaixo um resumo dos principais status:

Tamanho

O tamanho é também mostrado. Se o status for 200, saber o tamanho é importante pois informa quanto tempo pode demorar para finalizar a transmissão e o quanto de memória você tem de reservar para receber esse dado.

Cabeçalhos de requisição

Se você rolar a aba headers até o final, verá uma série de pares chave: valor. Esse são os cabeçalhos de requisição. Eles são informações adicionais acerca de quem está realizando a requisição, bem como, o que este espera receber ou mesmo, informações retransmitidas, como os cookies. As mais importantes são accept, content-type, cookies e user-agent.

Accept

Esse cabeçalho informa ao servidor qual tipo de média o cliente entende. O tipo de media também é conhecido como MIME(Multipurpose Internet Mail Extensions).

O mais comum é text/html, mas pode ser json, xml, pdf etc.

Content-type

Esse cabeçalho existe tanto na requisição quanto na resposta. Na requisição server para informar ao servidor qual o tipo conteúdo está sendo enviado no corpo. Falaremos do corpo mais adiante.

Cookies

Os cookies são peças de informação enviadas pelo servidor e armazenadas no navegador do cliente. Falamos disso no tutorial introdutório. Por vezes, você precisará pegar o cookie de uma requisição anterior e informá-lo na posterior.

User-agent

O user-agent informa ao servidor qual aplicação com sua respectiva versão está realizando a requisição. Por exemplo, pode ser o Chrome, o Firefox, Safari etc. Nas requisições com o httr, a aplicação é um programa chamado curl/versão. O curl é o programa escrito em linguagem C, que roda por trás do httr.

Alguns servidores são restritivos em relação ao user-agent. Por vezes, temos de informar que o user-agent é o mesmo do navegador que estamos usando para inspecionar a página. Por exemplo, eu copiei o user-agent do meu navegador e veio essa informação: “Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:109.0) Gecko/20100101 Firefox/112.0”.

Cabeçalhos de resposta

Os cabeçalhos de resposta contêm informações prestadas pelo servidor. O mais importante deles é o content-type, porque ele diz qual o tipo de arquivo estamos importando. Pode ser text/html, application/json, application/pdf etc.

Corpo

O terceiro elemento da requisição é o corpo. Este, porém, só entra no método POST. O corpo é basicamente o um formulário que você preenche para fornecer informações de filtro para a consulta e/ou outras informações a seu respeito que autorizem acessar aquela informação ou mesmo informações de requisição anterior.

Exercícios práticos

Vamos aplicar o que aprendemos até aqui realizando requisições a alguns tribunais.

Julgados de primeiro grau do TJSP

O primeiro passo para realizar uma requisição é interagir com a página e observar como ela opera para retornar os resultados. Passo a passo:

Feito isso, estamos prontos para realizar nossa primeira requisição. O pacote httr contêm uma função chamada GET que fará a requisição por nós. Eu colei a url abaixo, mas creio que ela é muito longa para ser visualizada numa página.

Agora vamos parsear essa url e imprimi-la:

$scheme
[1] "https"

$hostname
[1] "esaj.tjsp.jus.br"

$port
NULL

$path
[1] "cjpg/pesquisar.do"

$query
$query$conversationId
[1] ""

$query$dadosConsulta.pesquisaLivre
[1] "danos morais"

$query$tipoNumero
[1] "UNIFICADO"

$query$numeroDigitoAnoUnificado
[1] ""

$query$foroNumeroUnificado
[1] ""

$query$dadosConsulta.nuProcesso
[1] ""

$query$dadosConsulta.nuProcessoAntigo
[1] ""

$query$classeTreeSelection.values
[1] ""

$query$classeTreeSelection.text
[1] ""

$query$assuntoTreeSelection.values
[1] ""

$query$assuntoTreeSelection.text
[1] ""

$query$agenteSelectedEntitiesList
[1] ""

$query$contadoragente
[1] "0"

$query$contadorMaioragente
[1] "0"

$query$cdAgente
[1] ""

$query$nmAgente
[1] ""

$query$dadosConsulta.dtInicio
[1] ""

$query$dadosConsulta.dtFim
[1] "25/03/2023"

$query$varasTreeSelection.values
[1] ""

$query$varasTreeSelection.text
[1] ""

$query$dadosConsulta.ordenacao
[1] "DESC"


$params
NULL

$fragment
NULL

$username
NULL

$password
NULL

attr(,"class")
[1] "url"

Examine a url_parseada e note que a busca por danos morais está dentro do elemento \(query\)dadosConsulta.pesquisaLivre. Vamos alterá-lo para danos materiais e reconstruir a url:

Com isso, basta reconstruir a url:

Agora podemos realizar a requisição:

Visualize o cabeçalho geral da resposta:

Response [https://esaj.tjsp.jus.br/cjpg/pesquisar.do?conversationId=&dadosConsulta.pesquisaLivre=danos%20materiais&tipoNumero=UNIFICADO&numeroDigitoAnoUnificado=&foroNumeroUnificado=&dadosConsulta.nuProcesso=&dadosConsulta.nuProcessoAntigo=&classeTreeSelection.values=&classeTreeSelection.text=&assuntoTreeSelection.values=&assuntoTreeSelection.text=&agenteSelectedEntitiesList=&contadoragente=0&contadorMaioragente=0&cdAgente=&nmAgente=&dadosConsulta.dtInicio=&dadosConsulta.dtFim=25%2F03%2F2023&varasTreeSelection.values=&varasTreeSelection.text=&dadosConsulta.ordenacao=DESC]
  Date: 2023-04-26 10:23
  Status: 200
  Content-Type: text/html;charset=UTF-8
  Size: 242 kB










...

Note que o status é 200 (ok ou sucesso). O tamanho pode variar a depender do momento da pesquisa.

Vamos agora realizar a mesma requisição e salvá-la em disco. Para tanto, usamos, dentro da função GET uma outra função chamada write_disk. A diferença é que agora, não precisamos criar um objeto no R, somente um arquivo no disco.

GET(url, write_disk("nome_do_arquivo.html"))

Abra o arquivo e veja como ficou o resultado.

Citation

For attribution, please cite this work as

Filho (2023, April 26). Jurimetria: Raspagem de tribunais: requisição http.. Retrieved from https://direitoemdados.consudata.com.br/posts/2023-04-26-raspagem-de-tribunais-requisio-http/

BibTeX citation

@misc{filho2023raspagem,
  author = {Filho, José de Jesus},
  title = {Jurimetria: Raspagem de tribunais: requisição http.},
  url = {https://direitoemdados.consudata.com.br/posts/2023-04-26-raspagem-de-tribunais-requisio-http/},
  year = {2023}
}