Obter dados via R

Obter dados com o pacote OpenDataBio-R

  7 minute read  

O pacote Opendatabio-R foi criado para permitir aos usuários interagir com um servidor OpenDataBio, para obter (GET) dados, importar (POST) dados para a base de dados e atualizar dados (PUT). Este tutorial é um exemplo básico de como obter dados.

Configure a conexão

  1. Configure a conexão com o servidor OpenDataBio usando a função odb_config() do pacote. Os parâmetros mais importantes para esta função são base_url, que deve apontar para a URL da API do seu servidor OpenDataBio e token, que é o token de acesso usado para autenticar seu usuário.
  2. O token só é necessário para obter dados de conjuntos de dados que possuem uma das políticas de acesso restrito. Os dados dos conjuntos de dados de acesso público podem ser extraídos sem a especificação do token.
  3. Seu token está disponível em seu perfil na interface web
library(opendatabio)
base_url="https://opendb.inpa.gov.br/api"
token ="O SEU TOKEN AQUI"
cfg = odb_config(base_url=base_url, token = token)

A configuração mais avançada envolve a definição de uma versão de API específica, um agente de usuário personalizado ou outros cabeçalhos HTTP, mas isso não é coberto aqui.

Teste sua conexão

A função odb_test() pode ser usada para verificar se a conexão foi bem sucedida e se seu usuário foi identificado corretamente:

odb_test(cfg)
#will output
Host: https://opendb.inpa.gov.br/api/v0
Versions: server 0.9.1-alpha1 api v0
$message
[1] "Success!"

$user
[1] "admin@example.org"

Como alternativa, você pode especificar esses parâmetros como variáveis ​​de sistema. Antes de iniciar o R, configure isso em seu shell (ou adicione ao final de seu arquivo .bashrc):

export ODB_TOKEN="YourToken"
export ODB_BASE_URL="https://opendb.inpa.gov.br/api"
export ODB_API_VERSION="v0"

Obter dados

Verifique a Referência rápida da API GET para obter uma lista completa de endpoints e parâmetros de solicitação. Veja também os parâmetros genéricos, em especial save_job que é importante para baixar grandes conjuntos de dados.

Para dados de acesso público o token é opcional. Abaixo alguns exemplos. Siga um raciocínio semelhante para usar os demais endpoints. Veja a ajuda do pacote R para todas as funções odb_get_{endpoint} disponíveis.

Obtendo nomes de táxons

Consulte GET API Taxon Endpoint para uma lista dos parâmetros de solicitação e uma lista de campos de resposta.

base_url="https://opendb.inpa.gov.br/api"
cfg = odb_config(base_url=base_url)
#get id for a taxon
mag.id = odb_get_taxons(params=list(name='Magnoliidae',fields='id,name'),odb_cfg = cfg)
#use this id to get all descendants of this taxon
odb_taxons = odb_get_taxons(params=list(root=mag.id$id,fields='id,scientificName,taxonRank,parent_id,parentName'),odb_cfg = cfg)
head(odb_taxons)

Algo como, dependo da sua base:

  id scientificName taxonRank parent_id  parentName
1 25    Magnoliidae     Clado        20 Angiosperms
2 43     Canellales     Ordem        25 Magnoliidae
3 62       Laurales     Ordem        25 Magnoliidae
4 65    Magnoliales     Ordem        25 Magnoliidae
5 74      Piperales     Ordem        25 Magnoliidae
6 93  Chloranthales     Ordem        25 Magnoliidae

Obtendo Localidades e geometrias

Consulte GET API Location Endpoint para os parâmetros de solicitação e uma lista de campos de resposta.

Obtenha alguns campos listando todas as Unidades de Conservação (adm_level=99) registradas no servidor:

base_url="https://opendb.inpa.gov.br/api"
cfg = odb_config(base_url=base_url)
odblocais = odb_get_locations(params = list(fields='id,name,parent_id,parentName',adm_level=99),odb_cfg = cfg)
head(odblocais)

Se o servidor usar os dados de seed fornecidos o resultado será:

id                                                           name
1 5628                              Estação Ecológica Mico-Leão-Preto
2 5698          Área de Relevante Interesse Ecológico Ilha do Ameixal
3 5700 Área de Relevante Interesse Ecológico da Mata de Santa Genebra
4 5703     Área de Relevante Interesse Ecológico Buriti de Vassununga
5 5707                                Reserva Extrativista do Mandira
6 5728                                   Floresta Nacional de Ipanema
parent_id parentName
1         6  São Paulo
2         6  São Paulo
3         6  São Paulo
4         6  São Paulo
5         6  São Paulo
6         6  São Paulo

Localidades como objetos espaciais em R

Para obter um objeto espacial em R, use o pacote sf. O exemplo abaixo plota um gráfico e seus subgráficos e também exporta as localizações como kml e shapefile.

library(sf)
library(opendatabio)

#download dados de uma parcela
cfg <- odb_config(base_url = "https://opendb.inpa.gov.br/api")

#daddos da parcela
parcela = odb_get_locations(params = list(fields='all',name='Parcela 25ha'), odb_cfg = cfg)
parcela$type = 'main plot'

#subparcelas
subplots = odb_get_locations(params = list(fields='all',location_root=parcela$id), odb_cfg = cfg)
subplots = subplots[subplots$adm_level==100 & subplots$id!=parcela$id,]
subplots$type = 'sub plot'

#convert footprintWKT para sf geometries
geoms <- st_as_sfc(parcela$footprintWKT, crs = 4326)
parcela_sf <- st_sf(parcela, geometry = geoms)

geoms <- st_as_sfc(subplots$footprintWKT, crs = 4326)
subplots_sf <- st_sf(subplots, geometry = geoms)

#imprime
png("plots_with_subplots.png", width = 15, height = 15,units='cm',res=300)
  par(mar=c(2,2,3,2))
  plot(st_geometry(subplots_sf),border='green',main = parcela$locationName)
  plot(st_geometry(parcela_sf),border='red',add=T)
  labs = gsub("Quadrat ","",subplots_sf$locationName)
  text(
   st_coordinates(st_centroid(subplots_sf)),
   labels = labs,
   cex = 0.2, col = "blue"
  )
dev.off()


#salva como kml
locais = rbind(parcela_sf,subplots_sf)
locais$name <- locais$locationName
cols_to_include <- setdiff(names(locais), c("footprintWKT",'locationName'))
locais_kml <- locais[, c("name", cols_to_include[cols_to_include != "name"])]
st_write(locais_kml, "plots_and_subplots.kml", layer=parcela$locationName, driver = "KML", delete_dsn = TRUE)
#salva como shapefile
st_write(locais_kml, "plots_and_subplots.shp", layer=parcela$locationName, delete_layer = TRUE)

Figura gerada:

Validando coordendas geográficas

Ver POST Locations-Validation Endpoint para parametros e campos resposta.

#sua conexao
library(opendatabio)
base_url="http://localhost/opendatabio/api"
token ="o seu token aqui"
cfg = odb_config(base_url=base_url, token = token)
odb_test(cfg)

#dados fake
dados = data.frame(
  latitude = sample(seq(-2,2,by=0.00001),10),
  longitude = sample(seq(-60,-59,by=0.00001),10)
)

#envia para validar
jb = odb_validate_locations(dados,odb_cfg = cfg)

#monitora execução
odb_get_jobs(params=list(id=jb$id),odb_cfg = cfg)

#pega resultado
dadosValidados = odb_get_jobs(params=list(id=jb$id,get_file=T),odb_cfg = cfg)

head(dados)
  latitude longitude
1  0.12975 -59.65745
2  1.77469 -59.77757
3 -0.89154 -59.80179
4 -1.25632 -59.87084
5  0.77085 -59.22740
6 -0.74237 -59.64591

head(dadosValidados)
  latitude longitude withinLocationName withinLocationParent withinLocationCountry withinLocationHigherGeography  withinLocationType
1  0.12975 -59.65745  Trombetas/Mapuera               Brasil                Brazil    Brasil > Trombetas/Mapuera Território Indígena
2  0.12975 -59.65745     Bioma Amazônia               Brasil                Brazil       Brasil > Bioma Amazônia           Ambiental
3  0.12975 -59.65745           Amazonia                World                                            Amazonia           Ambiental
4  0.12975 -59.65745            Urucará             Amazonas                Brazil   Brasil > Amazonas > Urucará           Município
5  1.77469 -59.77757            Jacamim              Roraima                Brazil    Brasil > Roraima > Jacamim Território Indígena
6  1.77469 -59.77757     Bioma Amazônia               Brasil                Brazil       Brasil > Bioma Amazônia           Ambiental
  withinLocationID withinLocationTypeAdmLevel searchObs
1             6393                         98        NA
2             6583                         97        NA
3            16597                         97        NA
4             1570                          8        NA
5             6121                         98        NA
6             6583                         97        NA

Obtendo dados de Individuos

Consulte GET API Individual Endpoint para as listas completas das opções de parâmetros de busca e dos campos de reposta.

library(opendatabio)
base_url="https://opendb.inpa.gov.br/api"
token ="O SEU TOKEN AQUI"

#estabelece a configuração da conexao
cfg = odb_config(base_url=base_url, token = token)

#BAIXA DIRETAMENTE - se forem poucos dados que voce quer baixar
inds = odb_get_individuals(params=list(limit=100),odb_cfg=cfg)

#PREPARA ARQUIVO NO SERVIDOR - se tua busca implicar em muito registros
    #baixando todos os registros aos quais voce tem acesso ou publicos
    #salvando o processo, pois neste caso devem ser muitos
    jobid = odb_get_individuals(params=list(save_job=T),odb_cfg=cfg)
    #verificando o status do processo
    odb_get_jobs(params=list(id=jobid$job_id),odb_cfg=cfg)
    #qual terminr, pega os dados aqui (ou baixe o arquivo gerado pela interface web)
    todos.inds = odb_get_jobs(params=list(id=jobid$job_id),odb_cfg=cfg)

#BUSCANDO DADOS ESPECIFICOS
    
    #todos os individuos identificados como o taxon X
    params = list(taxon = "Licaria cannela tenuicarpa")
    licarias = odb_get_individuals(params=params,odb_cfg=cfg)

    #todos os individuos identificados como o taxon X ou seus descendentes
    params = list(taxon_root = "Licaria")
    licarias = odb_get_individuals(params=params,odb_cfg=cfg)

    #todos individuos do conjunto de dados X
    params = list(dataset = "MyDataset name or id")
    inds = odb_get_individuals(params=params,odb_cfg=cfg)
    #ou use o save_job acima se forem muitos dados

    #pode ver a lista dos conjuntos de dados existentes
    datasets = odb_get_datasets(odb_cfg = cfg)

Obtendo dados de Vouchers

Consulte GET API Voucher Endpoint para as listas completas das opções de parâmetros de busca e dos campos de reposta.

Siga o exemplo de indivíduos acima, mas usando a função odb_get_vouchers.

library(opendatabio)
base_url="https://opendb.inpa.gov.br/api"
token ="O SEU TOKEN AQUI"

#estabelece a configuração da conexao
cfg = odb_config(base_url=base_url, token = token)

#100 primeiros vouchers com registro numa biocoleção
vouchers = odb_get_vouchers(params=list(biocollection="INPA",limit=100),odb_cfg=cfg)

#vouchers na localidade x (id, ou nome, como registrado na base)
vouchers = odb_get_vouchers(params=list(location="Reserva Florestal Adolpho Ducke, Parcela PDBFF-100ha",limit=100),odb_cfg=cfg)

Obtendo Medições

Consulte GET API Measurement Endpoint para as listas completas das opções de parâmetros de busca e dos campos de reposta.

Use a função odb_get_measurements.

library(opendatabio)
base_url="https://opendb.inpa.gov.br/api" 
token ="O SEU TOKEN AQUI"

#estabelece a configuração da conexao
cfg = odb_config(base_url=base_url, token = token)

#100 primeiras medições do conjunto de dados X com id=10
medicoes = odb_get_measurements(params=list(dataset=10,limit=100),odb_cfg=cfg)

#100 primeiras medições do conjunto de dados X com id=10 para a variavel cujo export_name é treeDbh
medicoes = odb_get_measurements(params=list(trait="treeDbh",dataset=10,limit=100),odb_cfg=cfg)

#Medições do conjunto de dados X com id=10 para a variavel cujo export_name é treeDbh
#apenas para Lauraceae
medicoes = odb_get_measurements(params=list(trait="treeDbh",dataset=10,taxon_root="Lauraceae"),odb_cfg=cfg)

#ligando dados de individuos medicoes
louros = odb_get_individuals(params=list(dataset=10,taxon_root="Lauraceae"),odb_cfg=cfg)
filtro = grep("Individu",medicoes$measured_type) #opcional, depende do que esta em medicoes
g = match(medicoes$measured_id[filtro],louros$id)
medicoes$location = NA
medicoes$location[filtro] = louros$locationName[g]

Obtendo Mídia

Consulte GET API Media Endpoint para as listas completas das opções de parâmetros de busca e dos campos de reposta.

Use a função odb_get_media do pacote do R.

library(opendatabio)
base_url="https://opendb.inpa.gov.br/api" 
token ="O SEU TOKEN AQUI"

#estabelece a configuração da conexao
cfg = odb_config(base_url=base_url, token = token)

#os 50 primeiros arquivos de mídia de um conjunto de dados que tem imagens 
imgs = odb_get_media(params=list(dataset=97,limit=50),odb_cfg=cfg)

#veja esses metadados
head(imgs)

#a partir desses metadados, baixa os arquivos de media
#cria uma função para isso:
getImagesByURL <- function(url,downloadFolder='img') {
  dir.create(downloadFolder,showWarnings = F)
  fn = strsplit(url,"\\/")[[1]]
  fn = fn[length(fn)]
  nname = paste(downloadFolder,fn,sep="/")
  img = httr::GET(url=url)    
  writeBin(httr::content(img, "raw"), nname)
}
#usa a função para baixar as imagens numa pasta
sapply(imgs$file_url,getImagesByURL,downloadFolder='testeImgsFromOdb')

Obter Conjuntos de dados

Versões publicadas de conjuntos de dados, são arquivos já prontos no servidor para uso. Essas versões, se disponíveis, podem ter acesso aberto ou restrito.

Última modificação August 4, 2025: Fixed Location Tutorial - code upgraded (a4e18ab)