Le contrat de récupération de Reddit Extract

Comprenez les routes GET, les filtres autorisés, les limites de pagination et les erreurs HTTP avant de transformer les enregistrements reçus.

Obtenir une clé API

Routes et paramètres de requête

Envoyez les requêtes de lecture en GET avec votre clé dans Authorization: Bearer ou X-API-Key. /v1/search interroge le contenu historique; /v1/posts impose le type post et /v1/comments le type comment. Ces deux routes ne demandent pas d’id. /v1/item exige id pour consulter un élément précis et ne reçoit pas les filtres généraux d’une recherche.

Pour les recherches de contenu, les paramètres disponibles sont q, subreddit, author, kind, from, to, min_score, limit et page. kind accepte post ou comment. Les dates from et to utilisent YYYY-MM-DD et filtrent created_utc en UTC; to inclut toute la dernière journée. min_score est uniquement un seuil de filtrage, jamais une demande de classement. parent_id et link_id ne sont pas des filtres exposés.

/v1/subreddits recherche des noms avec prefix et limit. Cette route n’accepte ni page ni les filtres de dates des recherches de contenu; ses décomptes ne constituent pas un inventaire global exact. /v1/status est public et non facturé. Sa déclaration statique permet de constater une réponse du serveur HTTP, sans contrôler le moteur de recherche ou la disponibilité d’un enregistrement.

Lire une réponse sans surestimer sa portée

Les recherches de contenu acceptent limit de 1 à 100 et page de 1 à 100. L’ordre interne _doc n’est ni chronologique, ni fondé sur la pertinence ou le score. L’itération reste bornée : atteindre la dernière page autorisée ne prouve pas que tous les éléments correspondants ont été récupérés. Un intervalle de dates plus étroit ne garantit pas non plus une couverture complète.

Interprétez le total avec sa relation : eq signifie exact, gte indique une borne inférieure et unknown signifie qu’aucun total fiable n’est disponible, éventuellement avec une valeur null. Ne remplacez pas cet inconnu par zéro. Conservez les paramètres et ces indications avec votre lot afin de séparer le nombre observé des conclusions qui nécessiteraient d’autres preuves.

Les réponses contiennent des enregistrements plats. Chaque propriété doit être examinée avant sa projection dans une colonne locale. Si parent_id ou link_id existe, votre application peut établir une relation, mais le parent peut manquer et aucune arborescence complète n’est garantie. Le schéma de votre destination peut imposer des exigences supplémentaires; il ne modifie pas le contenu retourné par l’API.

Erreurs et consommation de crédits

HTTP 400 indique une requête invalide : vérifiez paramètres, valeurs et formats. HTTP 401 signale une clé manquante ou invalide, HTTP 402 un crédit insuffisant et HTTP 429 une limite de fréquence. Corrigez la cause avant de recommencer. Pour un problème d’authentification, vérifiez notamment que la clé provient du bon domaine; la régénération n’est pas une étape obligatoire de chaque correction.

Chaque récupération réussie consomme un crédit, y compris une réponse vide. Les requêtes rejetées ne consomment pas de crédit et une défaillance du service source restitue la réservation. Si votre client perd la réponse après une réussite du serveur, celle-ci peut avoir été facturée. Une nouvelle tentative réussie coûte un autre crédit. Un échec de conversion dans votre application n’annule pas une récupération réussie.

Routes de l’API

Méthode	Route	Paramètres
`GET`	`/v1/search`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/posts`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/comments`	`q, subreddit, author, kind, from, to, min_score, limit, page`
`GET`	`/v1/item`	`id`
`GET`	`/v1/subreddits`	`prefix, limit`
`GET`	`/v1/status`	`—`

Paramètres de requête

Paramètre	Valeur / type / plage
`q`	`text`
`subreddit`	`keyword`
`author`	`keyword`
`kind`	`post \| comment`
`from`	`ISO date`
`to`	`ISO date`
`min_score`	`integer`
`limit`	`1–100`
`page`	`1–100`
`id`	`item ID`
`prefix`	`subreddit prefix`