Autenticazione e Gestione Errori
Invia richieste GET a api.subredditapi.com con Authorization: Bearer <chiave> oppure X-API-Key: <chiave> per i recuperi autenticati. Entrambe le opzioni sono supportate. /v1/status è pubblico e non richiede chiave. La sessione del pannello account usa un cookie Secure HttpOnly distinto da queste intestazioni. Chiave e saldo appartengono soltanto a questo dominio, senza condivisione tra marchi.
I codici di errore HTTP devono essere letti come cifre ASCII letterali senza traduzioni. Un 400 indica una richiesta malformata o parametri errati. Un 401 segnala una chiave assente o non valida per l'autenticazione. Un 402 indica crediti insufficienti per completare la transazione richiesta. Un 429 avvisa che il limite di frequenza è stato superato temporaneamente.
Ogni recupero riuscito costa un credito, anche vuoto. Le richieste non valide non addebitano saldo e gli errori del fornitore di ricerca restituiscono la riserva. Un’interruzione sul client può seguire un successo addebitato sul server; una ripetizione riuscita costa un altro credito. /v1/status è pubblico e non addebitato, ma restituisce una dichiarazione statica e una risposta HTTP, senza verificare ricerca o archivio.
Struttura Record e Endpoint Principali
Usa /v1/search per ricerche generali, /v1/posts per pubblicazioni e /v1/comments per commenti. Solo /v1/item richiede id per un elemento noto. /v1/subreddits accetta prefix e limit per esplorare nomi di community, non author o kind. I suoi conteggi aggregati non sono garantiti come globalmente esatti. Se vuoi un indice alfabetico dei nomi ricevuti, ordinali localmente.
Le risposte contengono record piatti, non alberi di thread assemblati dal server. I campi parent_id e link_id possono essere presenti per raggruppamento locale cliente, ma non garantiscono un'ancestralità completa o una conversazione intera. Non esistono filtri di query per link_id o parent_id disponibili negli endpoint standard. La struttura è semplice e priva di gerarchie server-side complesse.
Il percorso /v1/item richiede obbligatoriamente l'ID univoco dell'elemento per il recupero preciso. /v1/posts e /v1/comments non richiedono id come parametro di query. I valori consentiti per il filtro kind sono post e comment. L'ordine dei documenti nell'archivio è quello interno _doc, che non è né cronologico né basato sulla rilevanza. Il raggruppamento è facoltativo per il client che processa i dati locali.
Filtri e Limiti di Paginazione
I filtri di ricerca sono q, subreddit, author, kind, from, to, min_score, limit e page. kind accetta post o comment. Le date sono YYYY-MM-DD in UTC, con to inclusivo. min_score è una soglia numerica, non un ordinamento o una misura della qualità. limit e page vanno da 1 a 100: fino a 100 record per richiesta e 100 pagine per query.
Nei totali, eq indica un valore esatto per la query, gte un limite inferiore e unknown l’assenza di un totale affidabile, eventualmente nullo. Un limite inferiore non è una stima approssimativa. Nessuna relazione prova copertura completa o recupero esaustivo. L’ordine _doc è documentale interno, non cronologico, di rilevanza o di punteggio; un checkpoint non congela la composizione delle pagine.
Il prezzo è di $1 per 1000 recuperi riusciti e la ricarica minima di $50 acquista 50000 crediti. I crediti acquistati non scadono e non ci sono abbonamenti. La chiave appare una volta alla registrazione, prima di pagare. La rigenerazione richiede accesso e password, invalidando la precedente. localStorage conserva identificatori di fattura e utente per recuperare la fattura, non la chiave o l’autenticazione della sessione.
Due ricerche con criteri documentati
Comincia da /v1/search?q=soil&subreddit=gardening&limit=3, poi cambia soltanto subreddit se questa è la variabile da confrontare. Mantieni termine, tipo, date e soglie. Definisci come tratti significati diversi, traduzioni e testi mancanti. Conserva risposte e versione delle regole locali; gli stessi filtri non garantiscono dati futuri identici o campioni rappresentativi. L’API non esegue analisi di sentiment: eventuali classificazioni sono parte del tuo metodo.
