6  Download de Dados

Este capítulo cobre todas as estratégias de download de dados do dashboard VIGIAR.

6.1 Download de uma tabela específica

A função principal é vigiar_baixar():

library(vigiar)

vigiar_conectar()

# Download completo de uma tabela
pm25 <- vigiar_baixar("df_anual")

6.1.1 Parâmetros do download

vigiar_baixar(
  tabela      = "df_anual",
  colunas     = NULL,          # NULL = todas as colunas
  ordenar_por = NULL,          # Coluna para ordenação
  limite      = NULL,          # Número máximo de linhas
  timeout     = 120,           # Timeout HTTP em segundos
  uf          = "RJ",          # Filtro por UF (NULL = sem filtro)
  direcao     = c("asc", "desc")  # Direção da ordenação
)

6.1.2 Download seletivo (colunas específicas)

# Baixar apenas algumas colunas
pm25_select <- vigiar_baixar(
  "df_anual",
  colunas = c("muni", "UF", "ano", "Media_pm25")
)

6.1.3 Download com limite de linhas

# Útil para testes rápidos ou amostragem
amostra <- vigiar_baixar("df_anual", limite = 100)

6.1.4 Download com ordenação

# Ordenar por ano (ascendente)
pm25_ordenado <- vigiar_baixar("df_anual", ordenar_por = "ano")

# Ordenar por ano (descendente)
pm25_desc <- vigiar_baixar("df_anual", ordenar_por = "ano", direcao = "desc")

6.1.5 Filtro por UF

Por padrão, o vigiar_baixar() filtra para o Rio de Janeiro (uf = "RJ"). Para baixar dados de outro estado ou de todo o Brasil:

# Todo o Brasil
pm25_br <- vigiar_baixar("df_anual", uf = NULL)

# São Paulo
pm25_sp <- vigiar_baixar("df_anual", uf = "SP")

# Múltiplas UFs
pm25_sudeste <- vigiar_baixar("df_anual",
  uf = c("RJ", "SP", "MG", "ES"))

6.2 Download de múltiplas tabelas

6.2.1 Tabelas principais

A função de conveniência vigiar_baixar_principais() baixa as 14 tabelas mais relevantes:

tudo <- vigiar_baixar_principais()
names(tudo)
# [1] "df_anual"  "df_mensal"  "df_muni"  "pop"  "tb_brasil" ...

6.2.2 Todas as tabelas

6.2.3 Subconjunto de tabelas

# Apenas qualidade do ar
tabelas_ar <- c("df_anual", "df_mensal", "df_dias", "df_dias_conama")
dados_ar <- vigiar_baixar_tudo(tabelas_ar)

6.2.4 Com delay entre downloads (rate limiting)

# Esperar 1 segundo entre cada download
tudo <- vigiar_baixar_tudo(delay = 1)

6.3 Download com cache

Para evitar baixar os mesmos dados repetidamente:

# Configurar diretório de cache
vigiar_cache_dir("~/vigiar_cache")

# Download com cache (reusa por 24h por padrão)
pm25 <- vigiar_baixar_com_cache("df_anual")

# Verificar o que está em cache
vigiar_cache_info()

# Limpar cache
vigiar_limpar_cache(dias = 7)     # Remove cache > 7 dias
vigiar_limpar_cache(tabela = "df_anual")  # Remove tabela específica

6.4 Download específico para o Rio de Janeiro

Para o estado do Rio de Janeiro, o pacote oferece uma função otimizada:

# Download otimizado para RJ (estratégia ASC+DESC particionada)
pm25_rj <- vigiar_baixar_rj("df_anual")

A estratégia vigiar_baixar_rj() usa uma abordagem de download particionado:

  1. Baixa os dados em ordem ASC (crescente) — pega o início do range
  2. Baixa os dados em ordem DESC (decrescente) — pega o final do range
  3. Combina os resultados e remove duplicatas

Isso contorna o limite de ~30 mil linhas da API (ver Limitações metodológicas).

6.5 Estimando o tamanho dos dados

Antes de baixar, você pode verificar o catálogo:

info <- vigiar_info()
# Coluna 'colunas' mostra o número de colunas
# O número de linhas depende do escopo (UF, anos)

6.6 Histórico de downloads

O pacote mantém um registro de todas as operações de download:

# Visualizar histórico
vigiar_historico_downloads()

# Resumo dos downloads
vigiar_resumo_downloads()

Saída:

# A tibble: 3 × 6
  tabela    n_linhas n_colunas  tempo_seg  status  timestamp
  <chr>        <int>     <int>      <dbl>  <chr>   <dttm>
1 df_anual      5570        12       2.34  ok      2026-07-19 10:15:22
2 df_mensal    28540        14      12.10  ok      2026-07-19 10:15:40
3 pop           5570         7       1.87  ok      2026-07-19 10:15:45

6.7 Tratamento de erros no download

6.7.1 Tabela não encontrada

Erro: Tabela 'xyz' nao encontrada. Use vigiar_tabelas() para ver as disponiveis.

Solução: Verifique o nome exato com vigiar_tabelas().

6.7.2 Truncamento pela API

Se o download retornar cerca de 30 mil linhas, a API pode ter truncado a resposta (ver Limitações metodológicas):

Warning: Possivel truncamento: 29876 linhas (limite API ~30K)

Solução: Use vigiar_baixar_rj() para tabelas grandes, ou filtre por UF.

6.7.3 Sessão expirada

Erro: Nenhuma sessao ativa. Execute vigiar_conectar() primeiro.

Solução: Execute vigiar_conectar(refresh = TRUE).

6.8 Boas práticas

  1. Sempre valide após o download com vigiar_checar_dados()
  2. Prefira vigiar_baixar_rj() para tabelas grandes do RJ
  3. Use cache para evitar downloads repetidos desnecessários
  4. Monitore o log com vigiar_log() e vigiar_historico_downloads()
  5. Documente a proveniência com vigiar_snapshot()