경로별 조건과 인증
기본 주소는 https://api.subredditdata.com 입니다. /v1/search는 과거 기록을 검색하고 /v1/posts와 /v1/comments는 기록 유형을 제한합니다. 이 목록 경로는 id가 필요하지 않습니다. 반면 /v1/item은 개별 기록의 id가 필요합니다. /v1/subreddits는 prefix와 limit으로 이름을 찾으며 회원 수와 성장 이력을 담은 완전한 커뮤니티 프로필을 제공하지 않습니다.
보호된 조회에는 원본 키를 X-API-Key로 보내거나 같은 키를 Authorization: Bearer로 보낼 수 있습니다. X-API-Key 값에 Bearer를 붙이지 마세요. subredditdata.com에서 발급된 키와 잔액을 사용해야 하며 다른 도메인과 공유되지 않습니다. 웹 계정의 Secure HttpOnly 세션 쿠키는 프로그램의 조회 인증과 별개입니다.
본문 검색 조건은 q, subreddit, author, kind, from, to, min_score, limit, page입니다. kind는 post 또는 comment이고 search에서는 생략할 수 있습니다. q는 title과 text에서 분석된 여러 단어를 일치 필드 안의 AND 조건으로 검색합니다. 모든 단어가 두 필드에 동시에 있어야 하는 것은 아니며 정확한 구절 검색도 보장하지 않습니다.
경로에 따라 허용되는 조건이 다릅니다. item은 id, subreddits는 prefix와 limit을 받고 모르는 매개변수 이름은 오류가 됩니다. parent_id, link_id, 감정이나 인구 특성을 지정하는 검색 조건은 없습니다. 비교표에는 사용한 경로와 기록 유형뿐 아니라 생략한 조건도 적어 두세요. 검색어를 바꾸면 선택되는 기록의 범위 역시 달라집니다.
날짜와 평면 기록의 해석
날짜는 정확히 YYYY-MM-DD로 보내며 created_utc를 UTC 기준으로 필터링합니다. from은 자정부터, to는 해당 날짜의 23:59:59까지 포함합니다. 예를 들어 from=2026-04-01과 to=2026-04-30은 사월의 달력 날짜를 뜻합니다. 오늘을 to로 지정해도 요청 순간이 아니라 오늘 전체가 경계이며 아직 없거나 누락된 기록을 제공한다는 약속은 아닙니다.
API 응답은 서버가 조립한 스레드 트리가 아니라 평면적인 기록 구조를 반환합니다. 응답 데이터 내에 parent_id나 link_id와 같은 필드가 포함될 경우, 클라이언트 측에서 이를 기반으로 로컬에서 그룹화하는 것은 사용자가 선택할 수 있는 옵션입니다. 그러나 이 방식이 완전한 대화 맥락이나 계보 구조를 완벽하게 보장하지는 않습니다.
선택적인 필드는 비어 있거나 없을 수 있습니다. 빠진 값을 추정해 실제 응답처럼 저장하지 말고 원래 값과 로컬 메모를 구별하세요. 식별자가 없다고 기록이 유일한 것은 아닙니다. 부모 식별자가 있어도 부모 본문을 읽을 수 있다는 보장은 없습니다. 읽지 못한 문맥은 비교표에서 판단 보류의 이유로 남길 수 있습니다.
limit과 page는 각각 1부터 100까지입니다. 결과의 _doc 순서는 시간순, 관련도순, 점수순이 아닙니다. min_score는 점수 하한만 적용하므로 신뢰할 수 있는 글을 선별하지 않습니다. 최대 페이지까지 조회해도 완전한 내보내기라고 할 수 없습니다. 로컬 시간 정렬도 이미 받은 기록만 다시 배치할 뿐 누락을 복원하지 않습니다.
총계의 eq는 해당 응답에 대한 정확한 값, gte는 하한, unknown은 신뢰할 총계가 없음을 뜻하며 null일 수 있습니다. 어떤 경우도 커뮤니티 대표성을 증명하지 않습니다. 이름별 집계 수치 역시 전체 범위에서 정확하다고 보장되지 않습니다. 로컬 주제 집계에는 실제 읽은 기록을 쓰고 중복과 제외 대상을 별도로 나타내세요.
오류와 통신 불확실성
HTTP 400은 잘못된 요청, 401은 누락되거나 무효인 키, 402는 잔액 부족, 429는 요청 빈도 제한입니다. 원인을 해결하기 전에 계속 반복하지 마세요. 오류를 해당 주제가 없다는 조사 결과로 바꾸면 안 됩니다. 공개 /v1/status는 무료이며 정적인 서비스 설명과 HTTP 응답만 제공합니다. 검색 원본이나 아카이브 가용성을 검사하지 않습니다.
성공한 조회는 빈 응답도 한 크레딧을 사용합니다. 잘못된 요청은 차감하지 않고 상위 원본 오류는 예약된 크레딧을 반환합니다. 하지만 클라이언트 타임아웃은 서버 실패의 증거가 아닙니다. 서버가 이미 성공하여 과금한 뒤 응답만 사라졌을 수 있습니다. 성공한 재시도는 별도 비용이고 성공 이후 로컬 처리 오류도 기존 요금을 취소하지 않습니다.
