엔드포인트 구조 및 인증 방식
호스트는 api.redditapistack.com이며 GET /v1/search는 검색, /v1/posts는 게시글, /v1/comments는 댓글에 사용합니다. 개별 항목은 /v1/item에 id를 지정하고, 두 목록 경로에는 id가 필요하지 않습니다. /v1/subreddits는 커뮤니티 이름의 prefix 탐색을 지원합니다. 목적에 맞는 경로를 고르고 모든 경로가 같은 매개변수를 받는다고 가정하지 마세요. 응답 필드도 실제 자료에서 확인해야 합니다.
조회 요청은 X-API-Key 헤더의 키로 인증합니다. 키는 가입 직후 결제 전에 한 번 표시됩니다. 로그인 후 비밀번호를 확인하여 재생성하면 이전 키가 즉시 무효화됩니다. 계정 패널은 키 페이지에 있으며 세션 쿠키는 해당 패널의 인증에 사용됩니다. 쿠키가 데이터 조회 키를 대신하지는 않습니다. 비밀번호 재설정과 이메일을 통한 키 전달 기능은 없습니다.
키와 잔액은 redditapistack.com의 개별 계정에 속하며 다른 네트워크 사이트의 키나 잔액과 공유되지 않습니다. 체험 크레딧 100개는 네트워크 전체의 남용 방지 자격 조건에 따라 제공될 수 있습니다. 이 공통 조건이 공통 잔액을 뜻하지는 않습니다. Python과 JavaScript에서도 키를 검색 주소나 공개 로그에 포함하지 말고 비밀 정보로 관리하는 것이 좋습니다.
데이터 검색 및 정렬 규칙
응답은 평면 기록이며 서버가 대화 트리를 완성하지 않습니다. parent_id나 link_id가 반환되면 앱에서 선택적으로 관계를 묶을 수 있지만 전체 대화나 모든 상위 기록을 보장하지 않습니다. 두 필드를 직접 지정하는 검색 필터도 없습니다. 로컬 그룹화의 결과를 완전한 원본 스레드라고 표시하지 말고, 관계가 없는 경우와 관련 기록이 누락된 경우를 구분하세요.
정렬 기준은 매우 명확합니다. min_score 파라미터는 필터링 용도로만 사용되며, 결과의 순서를 변경하는 정렬 기준이 절대 아닙니다. 데이터 검색 시 아카이브의 _doc 순서가 유지되며, 이는 시간순이나 관련도 순, 점수 순이 아닙니다. 따라서 동일한 쿼리를 반복하여 호출하더라도 항상 동일한 순서가 보장되는 것은 아니므로, 데이터의 안정성을 기대해서는 안 됩니다. 순서가 중요할 경우 클라이언트에서 추가적인 정렬 로직을 구현해야 합니다.
검색 매개변수는 q, subreddit, author, kind, from, to, min_score, limit, page입니다. kind는 post 또는 comment이며 날짜는 UTC 기준 YYYY-MM-DD, to는 지정한 날짜를 포함합니다. limit와 page는 각각 1부터 100입니다. 요청 한 번은 최대 100개 기록의 한 페이지를 반환하고 다음 페이지는 별도 호출입니다. 최대 100페이지의 조회가 전체 자료 수집을 보장하지는 않습니다.
오류 처리 및 페이지네이션 한계
400은 잘못된 요청, 401은 없거나 유효하지 않은 키, 402는 크레딧 부족, 429는 속도 제한을 뜻합니다. 코드의 숫자 크기로 오류 종류를 묶지 말고 각각 처리하세요. 400에는 매개변수, 401에는 헤더, 402에는 잔액을 확인합니다. 429에는 대기와 제한된 재시도를 고려할 수 있습니다. 같은 잘못된 설정을 계속 보내는 방식은 원인을 해결하지 못합니다.
전체 개수의 eq는 정확한 쿼리 일치 개수, gte는 하한값, unknown은 신뢰할 수 있는 총계를 알 수 없음을 뜻하며 값이 null일 수도 있습니다. 하한값은 실제 개수와 같을 수도 있지만 정확한 값이라고 확신할 수는 없습니다. 어느 경우에도 Reddit 전체가 보관되었다는 증거는 아닙니다. 분할 조회 역시 중복이나 누락이 없다는 보장이 아닙니다.
성공한 조회는 빈 결과도 1크레딧입니다. 잘못된 요청은 차감하지 않으며 상위 서비스 실패에는 예약분이 반환됩니다. 서버 성공 후 클라이언트 통신이 끊어지면 과금되었을 수 있고 성공한 재시도는 다시 유료입니다. /v1/status는 공개되고 무료지만 정적인 서비스 설명과 HTTP 응답만 제공하며 검색 기반, 자료 가용성, 완전성이나 지연 시간을 검사하지 않습니다.
API 엔드포인트
| 메서드 | 엔드포인트 | 매개변수 |
|---|---|---|
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 |
GET | /v1/status | — |
쿼리 매개변수
| 매개변수 | 값 / 유형 / 범위 |
|---|---|
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 |
curl -H "Authorization: Bearer YOUR_API_KEY" 'https://api.redditapistack.com/v1/search?q=research&limit=10'
import json, urllib.request
request = urllib.request.Request('https://api.redditapistack.com/v1/search?q=research&limit=10', headers={"Authorization": "Bearer YOUR_API_KEY"})
with urllib.request.urlopen(request) as response:
print(json.load(response))
fetch("https://api.redditapistack.com/v1/search?q=research&limit=10", {headers: {Authorization: "Bearer YOUR_API_KEY"}})
.then(response => response.json()).then(console.log);