Autenticação e Parâmetros de Consulta
Envie requisições GET para api.redditdataapi.com com Authorization: Bearer <chave> ou X-API-Key: <chave>. A busca aceita q, subreddit, author, kind, from, to, min_score, limit e page. kind aceita post ou comment; as datas seguem YYYY-MM-DD em UTC, com to inclusivo. O cookie de sessão do painel não substitui a chave nas consultas autenticadas.
Os limites de paginação exigem precisão, permitindo de 1 a 100 registros por solicitação. A ordenação do documento é definida internamente pela ordem _doc, não sendo cronológica, por relevância ou pontuação. O parâmetro min_score atua exclusivamente como um filtro condicional, nunca controlando a ordem de classificação dos resultados retornados pelo servidor.
As respostas contêm registros planos, sem garantia de esquema imutável. Quando parent_id ou link_id aparecem, o cliente pode agrupar os elementos disponíveis, sem garantir uma árvore completa. Esses campos não são filtros expostos. Somente /v1/item exige id; /v1/posts e /v1/comments aceitam consultas sem esse identificador. /v1/subreddits admite prefix para explorar comunidades.
Inspeção em Python e preparação da carga
Comece por /v1/posts?subreddit=python&limit=3. Em Python, urllib.request permite configurar o cabeçalho e json interpretar o corpo; trate também HTTPError e falhas de conexão. Verifique se data é uma lista e se cada registro é um objeto antes de examinar as chaves. Essas verificações pertencem à sua aplicação, não a um SDK próprio do serviço.
Compare campos ausentes, valores nulos e tipos incompatíveis com as colunas propostas. Não converta silenciosamente uma falha de leitura em lista vazia. Guarde a resposta original e envie linhas problemáticas para revisão. Carregue primeiro uma tabela de preparação e documente as regras de combinação antes de atualizar as tabelas analíticas. Os objetos pagination e credits descrevem a resposta, não cada publicação.
Paginação, Totais e Retenção de Dados
A iteração de paginação suporta até cem páginas por consulta, mas não garante cobertura completa ou ingestão exaustiva do arquivo. Os totais de paginação carregam semânticas específicas: eq indica exato, gte representa um limite inferior e unknown significa ausência de total confiável, podendo ser nulo.
Um limite inferior informa pelo menos a quantidade indicada, podendo o total real ser igual ou maior. unknown significa ausência de total confiável, possivelmente nulo. Nenhuma dessas relações demonstra cobertura completa do arquivo. Agregações de comunidades também não garantem contagens globais exatas; use-as para exploração, sem tratá-las como inventário de todos os registros disponíveis.
Separe o controle da coleta do esquema do armazém. Registre rota, filtros, página e horário da execução em um manifesto sem credenciais. Preserve as respostas recebidas e associe a elas a versão da transformação. Esse material permite repetir o processamento local, mas não torna o arquivo imutável nem garante que novas consultas devolvam as mesmas páginas.
Códigos de Erro e Limitações Técnicas
400 indica requisição inválida; 401, chave ausente ou inválida; 402, créditos insuficientes; 429, limite de frequência. Confira o status HTTP antes de interpretar o corpo como dados. Requisições inválidas não debitam saldo e falhas do provedor de busca devolvem a reserva. Uma interrupção no cliente pode ocorrer depois de um sucesso já cobrado no servidor.
Cada recuperação bem-sucedida custa um crédito, inclusive vazia. Uma repetição bem-sucedida custa outro crédito. Limite as tentativas e diferencie erros HTTP de falhas de conexão. /v1/status é público e não cobrado: retorna uma declaração estática do escopo histórico e indica que a aplicação HTTP responde, sem testar o mecanismo de busca ou a disponibilidade dos registros.
Funcionalidades como OAuth, postagem, votação e mensagens privadas são incompatíveis com esta API independente. A geração de chave de API pode ser refeita após confirmação de senha, invalidando a chave anterior instantaneamente. A interface mantém os registros planos e foca na entrega eficiente de dados históricos para análise de engenharia.
