APIs


Introdução

Se você usar o código ou as informações deste guia em um trabalho publicado, solicito que cite-o como uma fonte nas referências bibliográficas.

DUTT-ROSS,Steven Como lidar com APIs no R? Introdução ao acesso às APIs no R. Rio de Janeiro. 2020. mimeo. Disponível em: https://blog.metodosquantitativos.com/api/


Você não precisa usar o R, mas é uma boa ideia.


Como acessar qualquer API RESTful usando a linguagem R

Este é um guia de instruções para se conectar a uma API para receber informações quando a API não possui um pacote específico para R.

Este tutorial pressupõe que você tenha um conhecimento básico de trabalho de R e esteja confortável com scripts com o RStudio ou com o console do Rstudio.

Aqui estão as etapas básicas: 1. Instale os pacotes “httr” e “jsonlite”, 2. Faça uma solicitação “GET” para a API para inserir dados brutos em seu ambiente e buscar dados de sua forma bruta, 3. Coloque em um formato utilizável por meio do JavaScript Object Notification (JSON), 4. Coloque no formato tibble ou data.frame, 5. Escreva um loop na “página” através desses dados e recupere o conjunto de dados completo, 6. Aplique a mesma metodologia a outras APIs.

Uma boa maneira de seguir este guia de instruções é copiar cada linha de código em um script no RStudio. Isso permitirá que você execute cada linha de código individualmente para que você possa vê-lo funcionando e, em seguida, execute todos eles de uma vez no final.

Instale os pacotes “httr” e “jsonlite”

  1. Inicie seu script instalando os pacotes httr e jsonlite
install.packages("httr")
install.packages("jsonlite")
library("httr")
library("jsonlite")

Esse pacote (httr) facilita a solicitação de dados de qualquer API formatando suas solicitações GET com os cabeçalhos e autenticações adequados.

Quando os dados provavelmente estão no formato JSON. Se você é como a maioria dos usuários de R, convém converter o JSON para um tibble, para que seja mais fácil trabalhar com ele. O pacote jsonlite facilita isso.

Fazendo uma solicitação “GET” no R

A extração de dados de uma API RESTful geralmente requer uma senha de API, um nome de usuário da API ou ambos, além de um URL e cabeçalho formatados corretamente. O URL (tecnicamente conhecido como o endereço da API) informa à API quais dados você está procurando e o nome de usuário / senha são para APIs que têm o que é chamado de “autenticação básica”.

############################
#      base da API
############################
base <- "http://www.transparencia.gov.br/api-de-dados/despesas/por-orgao?ano="
############################
# parametros obrigatorios
############################
ano<-2019
# Ministerio da Educacao =26000
orgaoSuperior<-26000
# Unidade Orcamentaria: UNIRIO = 26269
orgao<-26269
pagina<-1
############################
# colocando tudo junto
############################
call1 <- paste(base,ano,"&orgaoSuperior=26000&orgao=",orgao,"&pagina=", pagina, sep="")

Quando uma API responde a uma solicitação, o ato de formatar os dados para transmissão na resposta é chamado de “serialização”. Quando a resposta é recebida na outra extremidade, o aplicativo que fez a solicitação original deve desserializar a carga útil. Neste exemplo, a resposta à chamada de API é uma lista. A lista tem muitos itens diferentes, sendo a maioria informações administrativas da API, não os dados que você deseja.

Certifique-se de entender essas informações, pois você precisará de algumas delas mais tarde. Mas, para obter os dados que você deseja, use outra função httr para iniciar o processo de desserialização:

# acesso (Status: 200 = ok)
get_budget <- GET(call1, type = "basic")
get_budget
Response [http://www.transparencia.gov.br/api-de-dados/despesas/por-orgao?ano=2019&orgaoSuperior=26000&orgao=26269&pagina=1]
  Date: 2020-06-29 22:58
  Status: 200
  Content-Type: application/json;charset=UTF-8
  Size: 251 B

Em seguida, digite o seguinte para exibir o conteúdo da variável recém-carregada:

get_budget_text <- content(get_budget, "text")
get_budget_text
[1] "[{\"ano\":2019,\"orgao\":\"Universidade Federal do Estado do Rio de Janeiro\",\"codigoOrgao\":\"26269\",\"orgaoSuperior\":\"Ministério da Educação\",\"codigoOrgaoSuperior\":\"26000\",\"empenhado\":\"663.610.599,16\",\"liquidado\":\"610.137.571,72\",\"pago\":\"574.461.766,03\"}]"

Isso converte os dados brutos da sua chamada à API no formato JSON. Em seguida, você pode analisar o JSON usando o pacote jsonlite (que você instalou anteriormente):

get_budget_json <- fromJSON(get_budget_text, flatten = TRUE)
get_budget_json
   ano                                            orgao codigoOrgao
1 2019 Universidade Federal do Estado do Rio de Janeiro       26269
           orgaoSuperior codigoOrgaoSuperior      empenhado      liquidado
1 Ministério da Educação               26000 663.610.599,16 610.137.571,72
            pago
1 574.461.766,03

Para transformar em um data.frame, precisamos do código:

get_budget_df <- as.data.frame(get_budget_json)
get_budget_df
   ano                                            orgao codigoOrgao
1 2019 Universidade Federal do Estado do Rio de Janeiro       26269
           orgaoSuperior codigoOrgaoSuperior      empenhado      liquidado
1 Ministério da Educação               26000 663.610.599,16 610.137.571,72
            pago
1 574.461.766,03
paste0("O orçamento executado (valor pago) pela UNIRIO foi:  R$ ",get_budget_df$pago)
[1] "O orçamento executado (valor pago) pela UNIRIO foi:  R$ 574.461.766,03"



Para saber sobre outras funções no R e no Python, você pode acessar o meu blog https://blog.metodosquantitativos.com/ ou o meu site pessoal https://steven.metodosquantitativos.com/