pySINDA Client Library

A library client pySINDA facilita a interação com a API do SINDA (Sistema Nacional de Dados Ambientais) para coletar e analisar dados de Plataformas de Coleta de Dados (PCDs).

Esta biblioteca foi redesenhada para ser modular, eficiente e totalmente integrada com fluxos de ciência de dados e análise exploratória (EDA) usando Pandas e NumPy.

Instalação¶

pip install pysinda

Configuração¶

Para usar o cliente, você deve usar a chave de API fornecida pelo DataSINDA. O cliente SindaClient também 'utiliza variáveis de ambiente para evitar a exposição de credenciais no código:

• SINDA_API_KEY: Chave de autenticação (API Key) da API.

Você também pode passar a chave de API como parâmetro para o cliente SindaClient:

client = SindaClient(api_key="sua_api_key")

Uso Básico¶

from pysinda import SindaClient

# Instanciando o cliente (carrega chave de API da variável de ambiente)
client = SindaClient()

# Ou passando os parâmetros explicitamente
client = SindaClient(api_key="sua_api_key")

SindaClient Reference¶

A classe única SindaClient unifica todas as operações disponíveis na API do SINDA. A maioria dos métodos de dados suporta o parâmetro opcional to_df=True para retornar um DataFrame do Pandas diretamente.

Métodos de Listagem de PCDs¶

get_all(to_df=False)¶

Retorna a lista completa com todas as PCDs e seus metadados.

get_all_resumed(to_df=False)¶

Retorna uma lista contendo apenas os campos principais das PCDs (id, numero, ativo, proprietario, latitude, longitude, estado, cidade).

get_complete_pcds(to_df=False)¶

Retorna a lista de PCDs que possuem todos os metadados principais preenchidos.

get_incomplete_pcds(to_df=False)¶

Retorna a lista de PCDs que possuem algum metadados principal ausente.

get_pcds_by_owner(owner, to_df=False)¶

Filtra a lista de PCDs pelo nome do proprietário (case-insensitive).

get_pcds_by_state(state, to_df=False)¶

Filtra a lista de PCDs pelo estado (sigla ou nome por extenso).

get_public_pcds(to_df=False)¶

Recupera a lista de todas as PCDs públicas.

get_private_pcds(to_df=False)¶

Recupera a lista de todas as PCDs de acesso privado.

Métodos de Dados e Metadados de uma PCD¶

get_pcd(idPCD, to_df=False)¶

Recupera informações rápidas da PCD associada ao ID informado.

get_period_availability(idPCD)¶

Obtém o período de disponibilidade dos dados temporais no banco. Retorna um dicionário contendo as chaves dataInicial e dataFinal.

get_sensors(idPCD)¶

Retorna a lista dos sensores habilitados para a respectiva PCD.

get_pcd_metadata(idPCD)¶

Retorna os metadados completos da PCD.

get_metadata_resumed(idPCD)¶

Retorna um resumo dos metadados da PCD.

get_owner(idPCD)¶

Obtém os detalhes do proprietário cadastrado da PCD.

is_private(idPCD)¶

Verifica se os dados daquela PCD específica são privados.

get_data(idPCD, data_inicial, data_final, to_df=False)¶

Recupera a série temporal de medições dos sensores para o intervalo de datas solicitado. Nota: Consultas maiores que 365 dias são automaticamente divididas em requisições anuais e agrupadas de forma transparente.

Módulo de Análise de Dados (Analytics)¶

A biblioteca oferece funções integradas para o tratamento, controle de qualidade e análise exploratória rápida das séries temporais das PCDs.

from pySINDA import SindaClient, clean_data, resample_time_series, compute_wind_components

client = SindaClient()
# Recupera dados brutos como DataFrame
df = client.get_data(idPCD=30847, data_inicial="2023-01-01", data_final="2023-02-01", to_df=True)

# 1. Trata outliers e interpola dados nulos
df_cleaned = clean_data(df, time_col='Data', fill_method='interpolate', outlier_threshold=3.0)

# 2. Decompõe velocidade e direção do vento em vetores U e V
df_wind = compute_wind_components(df_cleaned, speed_col='VelocidadeVento', dir_col='DirecaoVento')

# 3. Faz o resample para médias diárias
df_daily = resample_time_series(df_wind, time_col='Data', rule='D', agg='mean')

Funções Disponíveis¶

clean_data(df, time_col='Data', fill_method='interpolate', outlier_threshold=3.0)¶

Identifica outliers estatísticos (baseado em Z-score) substituindo-os por NaN. Em seguida, preenche valores ausentes utilizando o método escolhido ('interpolate', 'ffill', 'bfill' ou None).

detect_outliers(df, columns=None, threshold=3.0)¶

Retorna um DataFrame booleano indicando quais posições contêm valores atípicos (Z-score acima do limite especificado).

resample_time_series(df, time_col='Data', rule='D', agg='mean')¶

Agrupa a série temporal de acordo com a frequência informada (ex: 'D' para dia, 'H' para hora, 'ME' para mês) e calcula a agregação (ex: 'mean', 'sum', 'max', 'min').

summarize_time_series(df, time_col='Data')¶

Retorna um relatório geral contendo intervalo de datas, quantidade total de registros e porcentagens de valores ausentes e estatísticas básicas de cada sensor.

compute_wind_components(df, speed_col, dir_col)¶

Calcula as componentes zonais (U) e meridionais (V) do vento a partir da direção (em graus) e velocidade do vento. Ideal para análises meteorológicas e rosas dos ventos.

plot_time_series(df, time_col='Data', variables=None)¶

Plota subplots temporais para as variáveis numéricas do DataFrame de maneira automatizada. (Requer matplotlib instalado).