{"openapi":"3.0.3","info":{"title":"로또피그 공개 API","version":"1.0.0","description":"당첨번호·통계·앙상블 추천 등 **로그인 없이** 호출 가능한 HTTP API입니다. 관리자·회원 전용·웹훅·크론 엔드포인트는 포함하지 않습니다. 과도한 트래픽은 서비스 운영에 지장을 줄 수 있으니 캐시 헤더를 활용하고 합리적인 간격으로 요청해 주세요.","contact":{"name":"로또피그","email":"support@lottopig.kr","url":"https://www.lottopig.kr/contact"}},"servers":[{"url":"https://www.lottopig.kr","description":"현재 요청 기준 기본 URL"}],"tags":[{"name":"meta","description":"서버 시간 등 부가 정보"},{"name":"draws","description":"당첨번호 조회"},{"name":"stats","description":"통계·분석"},{"name":"ensemble","description":"앙상블 추천·제외·백테스트"},{"name":"combination","description":"조합 생성"}],"components":{"schemas":{"ErrorMessage":{"type":"object","required":["error"],"properties":{"error":{"type":"string","description":"사용자에게 표시 가능한 한글 메시지"}}},"LottoRound":{"type":"object","description":"단일 회차 당첨 정보 (필드는 데이터 출처에 따라 일부 생략될 수 있음)","properties":{"round":{"type":"integer","example":1200},"date":{"type":"string","example":"2025-12-27"},"numbers":{"type":"array","items":{"type":"integer","minimum":1,"maximum":45},"minItems":6,"maxItems":6},"bonusNumber":{"type":"integer","minimum":1,"maximum":45},"machineNo":{"type":"integer","enum":[1,2,3],"nullable":true},"prizeInfo":{"type":"object","additionalProperties":true},"totalSales":{"type":"integer"}}},"DrawsListResponse":{"type":"object","properties":{"total":{"type":"integer"},"draws":{"type":"array","items":{"$ref":"#/components/schemas/LottoRound"}},"limited":{"type":"boolean","description":"기본 limit으로 잘린 목록일 때 true"},"defaultLimit":{"type":"integer"}}},"DrawsBatchBody":{"type":"object","required":["rounds"],"properties":{"rounds":{"type":"array","items":{"type":"integer","minimum":1},"maxItems":80,"description":"조회할 회차 번호 목록 (중복 제거, 최대 80)"}}},"DrawsBatchResponse":{"type":"object","properties":{"draws":{"type":"object","additionalProperties":{"type":"object","properties":{"round":{"type":"integer"},"date":{"type":"string"},"numbers":{"type":"array","items":{"type":"integer"}},"bonusNumber":{"type":"integer"}}},"description":"키는 회차 문자열 (예: \"1200\")"}}},"CombinationPostBody":{"type":"object","properties":{"recommendedNumbers":{"type":"array","items":{"type":"integer"},"description":"가중 반영할 추천 번호"},"fixedNumbers":{"type":"array","items":{"type":"integer"},"description":"recommendedNumbers 대체 호환; 조합에 반드시 포함"},"excludeNumbers":{"type":"array","items":{"type":"integer"}},"count":{"type":"integer","default":5,"maximum":1000},"algorithm":{"type":"string","enum":["random","weighted","top_pool","filtered","smart","backtrack"],"default":"smart"},"useFilter":{"type":"boolean","default":true},"strategyMode":{"type":"string","enum":["jackpot","balanced","standard","optimized","absence_focus","decade_flow"],"default":"standard"},"excludePrevOddEven":{"type":"boolean","default":true},"excludePastWinning":{"type":"boolean","default":false},"maxConsecutivePairs":{"type":"integer","minimum":0,"maximum":5,"nullable":true},"patternFilters":{"type":"object","additionalProperties":true}}}}},"paths":{"/api/time":{"get":{"tags":["meta"],"summary":"서버 시각 (UTC·KST)","responses":{"200":{"description":"성공","content":{"application/json":{"schema":{"type":"object","properties":{"utc":{"type":"string","format":"date-time"},"kst":{"type":"string"},"kstISO":{"type":"string"},"timestamp":{"type":"integer"},"timestampSeconds":{"type":"integer"},"timezone":{"type":"object"}}}}}}}}},"/api/lotto/latest-round":{"get":{"tags":["draws"],"summary":"가장 최근 완료 회차 번호","responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"round":{"type":"integer"}}}}}}}}},"/api/lotto/rounds":{"get":{"tags":["draws"],"summary":"전체 회차 배열 (최신이 앞)","description":"응답 크기가 큽니다. 앱에서는 `/api/lotto/draws` 페이지네이션 또는 `draws-batch` 사용을 권장합니다.","responses":{"200":{"content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/LottoRound"}}}}}}}},"/api/lotto/draws":{"get":{"tags":["draws"],"summary":"당첨번호 목록·단건","parameters":[{"name":"round","in":"query","schema":{"type":"integer"},"description":"지정 시 해당 회차 1건만 (404 가능)"},{"name":"limit","in":"query","schema":{"type":"integer","default":30,"maximum":2000}},{"name":"offset","in":"query","schema":{"type":"integer","default":0}},{"name":"all","in":"query","schema":{"type":"string","enum":["1"]},"description":"`all=1`이면 전체 배열을 `draws`에 담아 반환 (대용량)"}],"responses":{"200":{"description":"단건은 LottoRound, 목록은 DrawsListResponse 또는 total+draws","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/LottoRound"},{"$ref":"#/components/schemas/DrawsListResponse"}]}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}},"/api/lotto/draws-batch":{"post":{"tags":["draws"],"summary":"회차 목록 배치 조회","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawsBatchBody"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DrawsBatchResponse"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}},"/api/round/{id}":{"get":{"tags":["draws"],"summary":"회차 단건 (레거시 경로)","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LottoRound"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}},"/api/lotto/history":{"get":{"tags":["draws"],"summary":"페이지네이션·필터 당첨 목록","parameters":[{"name":"cursor","in":"query","schema":{"type":"integer"},"description":"회차 커서 (미지정 시 최신부터)"},{"name":"limit","in":"query","schema":{"type":"integer","default":30}},{"name":"machineNo","in":"query","schema":{"type":"integer","enum":[1,2,3]}},{"name":"numbers","in":"query","schema":{"type":"string"},"description":"포함 번호 CSV (예: 7,12,21)"},{"name":"oddCount","in":"query","schema":{"type":"integer","minimum":0,"maximum":6}},{"name":"lowCount","in":"query","schema":{"type":"integer","minimum":0,"maximum":6},"description":"저(1~22) 개수"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"draws":{"type":"array","items":{"$ref":"#/components/schemas/LottoRound"}},"nextCursor":{"type":"integer","nullable":true}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}},"/api/lotto/statistics":{"get":{"tags":["stats"],"summary":"집계 통계","parameters":[{"name":"recent","in":"query","schema":{"type":"integer","maximum":500},"description":"최근 N회만 사용해 계산 (미지정이면 전체 이력)"}],"responses":{"200":{"description":"computeLottoStatistics 결과 (번호별 빈도, 홀짝, 연번 등)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/lotto/ensemble-recommend":{"get":{"tags":["ensemble"],"summary":"다음 회 앙상블 추천·제외 및 백테스트","description":"동일 로직을 `ensemble_recommend_cache` 테이블에 스냅샷으로 두어, 최신 회차와 일치하면 DB에서 즉시 응답합니다. 캐시 없으면 계산 후 저장합니다.","parameters":[{"name":"machine","in":"query","schema":{"type":"string","enum":["predict","latest"],"default":"predict"},"description":"`latest`면 직전 회 추첨기 번호를 그대로 사용"},{"name":"backtestN","in":"query","schema":{"type":"string"},"description":"생략 또는 `all`: 가능한 전 구간. 숫자 N: 최근 N회. `0`: 백테스트 생략"}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","properties":{"lastCompletedRound":{"type":"integer"},"targetRound":{"type":"integer"},"machineMode":{"type":"string"},"next":{"type":"object","nullable":true,"additionalProperties":true},"backtest":{"type":"array","items":{"type":"object","additionalProperties":true}},"backtestMeta":{"type":"object","additionalProperties":true},"source":{"type":"string","enum":["cache","live"],"description":"cache=DB 스냅샷"},"cacheComputedAt":{"type":"string","nullable":true,"description":"스냅샷 계산 시각(ISO)"}}}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}},"/api/lotto/combination":{"post":{"tags":["combination"],"summary":"추천·제외 번호 기반 조합 생성","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CombinationPostBody"}}}},"responses":{"200":{"description":"조합 배열 등 (알고리즘별 필드)","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorMessage"}}}}}}}}}