Authentification et routes disponibles
Les routes de récupération utilisent GET sur https://api.redditdatastream.com. Transmettez X-API-Key: <clé> ou Authorization: Bearer <clé> ; les deux en-têtes sont acceptés. Conservez le secret sur votre serveur. Le panneau du compte utilise une session avec cookie Secure HttpOnly, distincte de l’authentification nécessaire aux requêtes de récupération de votre application.
/v1/search recherche publications et commentaires ; /v1/posts se limite aux publications et /v1/comments aux commentaires. Ces routes n’acceptent pas id comme filtre. Pour un identifiant connu, /v1/item?id=... recherche un enregistrement individuel. Cette opération ne parcourt pas automatiquement ses réponses, ses descendants ou ses ancêtres et ne promet pas de retrouver le message demandé.
/v1/subreddits accepte prefix et limit pour découvrir des communautés. prefix n’est pas un filtre des routes de contenu. Les comptages de communautés ne constituent pas un recensement global garanti. /v1/status est public et non facturé : il décrit statiquement le service et confirme que l’application HTTP répond, sans sonder le moteur de recherche ni vérifier la disponibilité des données archivées.
Filtres et structure des réponses
Les paramètres de search, posts et comments sont q, subreddit, author, kind, from, to, min_score, limit et page. kind accepte les valeurs littérales post et comment. q effectue une recherche textuelle, sans langage arbitraire de requêtes ni classification des sentiments. Choisissez les filtres en tenant compte des messages qu’ils peuvent exclure alors que votre analyse en aurait besoin pour comprendre une réponse.
from et to utilisent YYYY-MM-DD en UTC et s’appliquent à created_utc. Le jour indiqué par to est inclus entièrement. Ces paramètres n’acceptent ni heures ni secondes et ne désignent pas le moment d’entrée dans l’archive. min_score définit un seuil numérique de score, sans trier les résultats et sans sélectionner automatiquement les résultats les plus utiles pour votre application.
Lorsque les champs parent_id ou link_id sont présents, vous pouvez les regrouper localement pour reconstruire une conversation, mais aucune garantie de complétude n’est offerte. Les requêtes sur les publications et les commentaires ne nécessitent pas de paramètre id, celui-ci étant réservé exclusivement à la route item. Des champs peuvent manquer ou désigner des données non reçues. La réponse contient data, pagination et credits. parent_id et link_id ne sont pas des filtres de recherche. JSONL est une transformation locale, pas le format de téléchargement de cette route.
Pagination, erreurs et coût des tentatives
Sur /v1/search, /v1/posts et /v1/comments, limit et page acceptent des valeurs de 1 à 100, avec une page par requête. La livraison suit _doc, un ordre interne, sans tri chronologique, par pertinence ou score ni échantillonnage aléatoire garanti. /v1/subreddits accepte seulement prefix et limit, sans page. Trier localement ou diviser les dates ne prouve ni exhaustivité, ni unicité, ni stabilité entre requêtes.
Lisez pagination.total avec relation : eq indique un total exact pour la requête, gte une borne inférieure et unknown l’absence d’un total fiable, éventuellement null. Ne remplacez pas inconnu par zéro. Même un total exact ne prouve pas que tous les résultats ont été téléchargés ni que l’archive contient toute l’histoire. Conservez aussi les indicateurs de pagination renvoyés pour décrire les limites rencontrées.
HTTP 400 indique des paramètres invalides, 401 une clé absente ou invalide, 402 un solde insuffisant et 429 une limite de fréquence. Une récupération réussie, même vide, coûte un crédit. Les requêtes invalides ne débitent pas le compte ; les échecs du service source restituent la réservation. Une perte de réponse côté client peut suivre une réussite facturée. Une nouvelle tentative réussie coûte un autre crédit ; enregistrez les réponses avant de mettre à jour votre progression.
