Os dados são uns dos elementos mais importantes de um projeto de ciência de dados. Existem várias formas de se obter os dados, mas as APIs vêm se tornando uma das formas mais comuns. A sigla vem do termo em inglês “Application Programming Interface” ou “Interface de Programação para Aplicativos”

Uma das grandes vantagens de utilizar APIs é que ela não depende de uma linguagem de programação, faremos uma requisição a uma URL, que nos retornará uma resposta. Apesar disso, todos os exemplos que mostrarei aqui, utilizam a linguagem R.

Antes de exemplificar como podemos acessar e criar uma API no R, vamos entender algumas coisas relacionadas a API de forma geral.

Endpoint

O endpoint é uma URL, um caminho, onde iremos fazer uma requisição e que possui a seguinte estrutura.

  • Base URL: é o início da URL da requisição, que se repetirá em qualquer requisição que fizermos.
    Ex.: https://api.covid19api.com/
  • Resource ou Path: é o tipo de informação que estamos buscando.
    Ex.: https://api.covid19api.com/country/brazil/status/confirmed
  • Query String: são os parâmetros da requisição que poderemos utilizar para fazer filtros, paginação, versionamento, ordenação e etc…
    Ex.: https://api.covid19api.com/country/brazil/status/confirmed&from=2020-06-01T00:00:00Z&to=2020-07-07T00:00:00Z
url para api

Métodos

Os métodos nos ajudam a informar o tipo de ação que queremos fazer no momento da requisição e esses são os principais métodos existentes:

  • GET: busca os dados.
  • POST: envia os dados.
  • PUT/PATCH: atualiza os dados.
  • DELETE: exclui os dados.

Código de status HTTP

HTTP ou do inglês “Hyper Text Transfer Protocol” é um protocolo de comunicação de dados da internet. Onde existem padrões de códigos de status, que facilitam o entendimento das respostas das APIs.

Os códigos de respostas mais utilizados são:

  • 200: requisição foi bem sucedida.
  • 201: requisição foi bem sucedida e um novo recurso foi criado como resultado.
  • 204: não há conteúdo para enviar para esta solicitação.
  • 400: essa resposta significa que o servidor não entendeu a requisição.
  • 404: o servidor não pode encontrar o recurso solicitado.
  • 500: o servidor encontrou uma situação com a qual não sabe lidar.

Acessando API

Veremos como acessar uma API no R, caso essa API não tenha um pacote criado, pois o R possui alguns pacotes que permitem acessarmos algumas APIs específicas, como o rtweet, que permite acessar a API do Twitter. Mas para exemplificar, veremos como utilizar uma API caso ela não tenha nenhum pacote já criado e nessa situação precisaremos instalar e carregar alguns pacotes essenciais para essa tarefa: httr e jsonlite.

Instalando os pacotes utilizando a função install.packages(), caso não o tenha instalado em seu computador e carregando os pacotes utilizando a função library().

# Instalando os pacotes
install.packages(c("httr", "jsonlite"))

# Carregando os pacotes
library(httr)
library(jsonlite)

Agora que instalamos e carregamos os pacotes necessários para acessar uma API, vamos iniciar as requisições e, como primeiro exemplo, iremos acessar uma API onde é possível solicitar várias informações relacionadas ao COVID-19.

# Separando a estrutura do endpoint 'endereço' que iremos acessar, em variáveis
base_url <- "https://api.covid19api.com"
path <- "country/brazil/status/confirmed"

endpoint <- paste(base_url, path, sep="/")

# Fazendo uma solitação GET a API, passando o endereço da requisição e o query string,
# que são parâmetros que segundo a documentação da API esse endpoint pode receber
res_api <- GET(
  url = endpoint, 
  query = list(
    from = "2020-06-20T00:00:00Z",
    to = "2020-07-07T00:00:00Z"
  )
)

# Visualizando a resposta da requisição
res_api
## Response [https://api.covid19api.com/country/brazil/status/confirmed?from=2020-06-20T00%3A00%3A00Z&to=2020-07-07T00%3A00%3A00Z]
##   Date: 2020-07-09 00:53
##   Status: 200
##   Content-Type: application/json; charset=UTF-8
##   Size: 3.15 kB
## [{"Country":"Brazil","CountryCode":"BR","Province":"","City":"","CityCode":""...
# Nesse momento os nossos dados da requisição estão contidos em um Unicode bruto,
# sendo necessário converter seu conteúdo para um vetor de caracteres
content_text <- rawToChar(res_api$content)

# Visualizando o resultado da conversão, que será uma estrutura JSON no formato caractere
content_text
# Convertendo a estrutura JSON no formato caratere para um objeto do R
content_json <- fromJSON(content_text, flatten=TRUE)

# Visualizando o resultado da conversão
content_json
##    Country CountryCode Province City CityCode    Lat    Lon   Cases    Status          Date
## 1   Brazil          BR                        -14.24 -51.93 1067579 confirmed  2020-06-20T00:00:00Z
## 2   Brazil          BR                        -14.24 -51.93 1083341 confirmed  2020-06-21T00:00:00Z
## 3   Brazil          BR                        -14.24 -51.93 1106470 confirmed  2020-06-22T00:00:00Z
## 4   Brazil          BR                        -14.24 -51.93 1145906 confirmed  2020-06-23T00:00:00Z
## 5   Brazil          BR                        -14.24 -51.93 1188631 confirmed  2020-06-24T00:00:00Z
## 6   Brazil          BR                        -14.24 -51.93 1228114 confirmed  2020-06-25T00:00:00Z
## 7   Brazil          BR                        -14.24 -51.93 1274974 confirmed  2020-06-27T00:00:00Z
## 8   Brazil          BR                        -14.24 -51.93 1313667 confirmed  2020-06-28T00:00:00Z
## 9   Brazil          BR                        -14.24 -51.93 1344143 confirmed  2020-06-29T00:00:00Z
## 10  Brazil          BR                        -14.24 -51.93 1368195 confirmed  2020-06-30T00:00:00Z
## 11  Brazil          BR                        -14.24 -51.93 1402041 confirmed  2020-07-01T00:00:00Z
## 12  Brazil          BR                        -14.24 -51.93 1448753 confirmed  2020-07-02T00:00:00Z
## 13  Brazil          BR                        -14.24 -51.93 1496858 confirmed  2020-07-03T00:00:00Z
## 14  Brazil          BR                        -14.24 -51.93 1539081 confirmed  2020-07-04T00:00:00Z
## 15  Brazil          BR                        -14.24 -51.93 1577004 confirmed  2020-07-05T00:00:00Z
## 16  Brazil          BR                        -14.24 -51.93 1603055 confirmed  2020-07-06T00:00:00Z
## 17  Brazil          BR                        -14.24 -51.93 1623284 confirmed  2020-07-07T00:00:00Z
## 18  Brazil          BR                        -14.24 -51.93 1668589 confirmed  2020-07-08T00:00:00Z

Nesta API que acabamos de acessar, não foi necessário realizar nenhuma autenticação, porém agora mostrarei um exemplo da API do AccuWeather que para ter acesso aos dados é necessário utilizar uma chave, que é disponibilizada após fazer o cadastro no site.

# Separando a estrutura do endpoint 'endereço' que iremos acessar, em variáveis
base_url <- "http://dataservice.accuweather.com"
path <- "locations/v1/regions"

endpoint <- paste(base_url, path, sep="/")

# Atribuindo o token a uma variável de ambiente do R
# 1° opção: Será aberto um arquivo com todas as variáveis de ambiente e você poderá adicionar uma nova
#usethis::edit_r_environ()
# 2° opção: Cria uma variável, sem a necessidade de abrir o arquivo
#Sys.setenv("KEY_API" = "sua_api")

# Obtendo a variável de ambiente e atribuindo a uma nova variável
key_api <- Sys.getenv("KEY_API")

# Fazendo uma solitação GET a API, passando o endereço da requisição e o query string,
# que neste caso, será a chave e que queremos os detalhes
res_api <- GET(
  url = endpoint, 
  query = list(
    apikey= key_api,
    details = "true"
  )
)

# Visualizando o resposta da requisição
res_api
## Response [http://dataservice.accuweather.com/locations/v1/regions?apikey=GFElrX6oceGWX12S9dMppSaijYXjSC1p&details=true]
##   Date: 2020-07-09 00:53
##   Status: 200
##   Content-Type: application/json; charset=utf-8
##   Size: 673 B
# Nesse momento os nossos dados da requisição estão contidos em um Unicode bruto,
# sendo necessário converter seu conteúdo para um vetor de caracteres
content_text <- rawToChar(res_api$content)

# Visualizando o resultado da conversão, que será uma estrutura JSON no formato caractere
content_text
## [1] "[{\"ID\":\"AFR\",\"LocalizedName\":\"Africa\",\"EnglishName\":\"Africa\"},{\"ID\":\"ANT\",\"LocalizedName\":\"Antarctica\",\"EnglishName\":\"Antarctica\"},{\"ID\":\"ARC\",\"LocalizedName\":\"Arctic\",\"EnglishName\":\"Arctic\"},{\"ID\":\"ASI\",\"LocalizedName\":\"Asia\",\"EnglishName\":\"Asia\"},{\"ID\":\"CAC\",\"LocalizedName\":\"Central America\",\"EnglishName\":\"Central America\"},{\"ID\":\"EUR\",\"LocalizedName\":\"Europe\",\"EnglishName\":\"Europe\"},{\"ID\":\"MEA\",\"LocalizedName\":\"Middle East\",\"EnglishName\":\"Middle East\"},{\"ID\":\"NAM\",\"LocalizedName\":\"North America\",\"EnglishName\":\"North America\"},{\"ID\":\"OCN\",\"LocalizedName\":\"Oceania\",\"EnglishName\":\"Oceania\"},{\"ID\":\"SAM\",\"LocalizedName\":\"South America\",\"EnglishName\":\"South America\"}]"
# Convertendo a estrutura JSON no formato caratere para um objeto do R
content_json <- fromJSON(content_text, flatten=TRUE)

# Visualizando o resultado da conversão
content_json
##     ID   LocalizedName     EnglishName
## 1  AFR          Africa          Africa
## 2  ANT      Antarctica      Antarctica
## 3  ARC          Arctic          Arctic
## 4  ASI            Asia            Asia
## 5  CAC Central America Central America
## 6  EUR          Europe          Europe
## 7  MEA     Middle East     Middle East
## 8  NAM   North America   North America
## 9  OCN         Oceania         Oceania
## 10 SAM   South America   South America

E outra forma de autenticação, é através de um usuário e uma senha, porém não encontrei nenhuma API para mostrar, mas caso você se encontre nessa situação é bem simples o processo, segue abaixo o exemplo:

user <- "usuario_para_acesso_api"
password <- "senha"

endpoint <- "http://api.endereco.com"

req <- GET(
  url = endpoint, 
  authenticate(
    user, 
    password, 
    type = "basic"
  )
)

Gostou do nosso artigo? Se quiser se aprofundar mais nesse assunto indicamos o guia completo de APIs RESTFUL e o Tutorial: Construindo APIs. E siga-nos nas redes sociais para saber sempre que publicamos um novo artigo.

Artigo escrito com a colaboração de Valéria Nicéria da Silva.

0 respostas

Deixe uma resposta

Quer participar dessa discussão?
Sinta-se livre para contribuir!

Deixe uma resposta

O seu endereço de e-mail não será publicado. Campos obrigatórios são marcados com *