Artigo escrito com a colaboração de Valéria Nicéria da Silva.
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
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 AmericaE 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.
2 comentários em “Trabalhando com API no R”
Parabéns pelo artigo, ajudou bastante!
Valeu, Carlos!