SakeMe 공개 데이터 API

질문으로 찾기

GET /api/v1/discover?q=방어회에 먹을 사케 추천해줘

q는 1~200자입니다. 음식 별칭을 인식하면 guides에 설명·제품 후보·출처를 반환합니다. catalog_results는 별도의 이름 검색 결과이며, 음식과 어울린다고 판정한 목록이 아닙니다. “오늘의 사케 추천”처럼 조건이 없으면 음식과 취향을 묻는 clarification을 제공합니다. 임의의 모든 질문을 이해하는 언어 모델은 아닙니다.

제품 조회

GET /api/v1/products/35760

제품 ID와 원문 URL, 이름, 확인된 별칭의 출처, 공개 속성을 반환합니다. 모르는 가격·재고는 null 또는 unknown입니다. attributes.nama는 제품별 검수 공정이 nama이면 true, pasteurized이면 false, unknown이면 null입니다. 과거 is_nama의 true와 false 모두 공정의 근거로 쓰지 않습니다. false는 화입이 확인됐다는 뜻이며 횟수나 시점까지 뜻하지 않습니다.

food_pairings에는 이 제품을 후보로 다룬 음식별 가이드와 추천 이유, 제조사 설명·출처를 제공합니다. 편집 제안이 없는 제품은 빈 배열입니다. 같은 브랜드나 등급의 다른 제품으로 추천을 확대해서 해석하지 마세요.

제조사에서 확인한 제품 정보

검수한 제품은 verified_specifications에 제조사 출처와 확인일, 도수, 원료 쌀과 정미율, 일본주도·산도를 제공합니다. rice.koji는 누룩용 쌀, rice.kake는 덧술용 쌀입니다. 정미율이 다를 수 있으므로 하나의 수치로 합치지 마세요. 자료가 쌀의 용도를 구분하지 않으면 rice.unspecified만 제공합니다. 도수·일본주도·산도 등 개별 값의 null은 단일 숫자로 제공하는 값이 없다는 뜻이며 0으로 해석하지 마세요. 제조사가 공개한 범위와 조건은 variation_note에서 확인할 수 있습니다.

description_type이 manufacturer_summary인 설명은 제조사 설명을 정리한 문안입니다. 실제 사용자 시음으로 해석하지 마세요. 아직 검수하지 않은 제품은 verified_specifications가 null이며, 등급·도수 등 기존 카탈로그 속성과 구분합니다. attributes.nama는 별도의 검수 공정 상태에서만 결정합니다. 같은 브랜드의 다른 제품이나 계절 변형에 복사하지 마세요.

확인한 원료와 제조 방식

verified_attributes에는 검수 출처와 확인일이 있는 쌀·제조 방식만 제공합니다. rice는 역할별 배열이며 polishing_ratio는 정미율, blend_ratio는 명시된 배합 비율입니다. 배합 비율이 null이면 알 수 없다는 뜻입니다. rice.variety가 null인 경우에도 출처의 원래 쌀 표기는 label에 남습니다.

pasteurization.state는 unknown, nama, pasteurized 중 하나입니다. 확인 자료가 없으면 unknown이며 과거 카탈로그의 true나 false를 비가열·화입 근거로 사용하지 않습니다. styles의 같은 쌀·제조 방식은 제품 간 공통점이며 맛이나 만족도 예측이 아닙니다. 개인 기록이나 내부 검수자 정보는 공개 응답에 포함하지 않습니다.

국가·주종·원어 이름

reviewed_classification은 제조사 자료로 확인한 국가·주종·원어 이름과 포장 용량을 제공합니다. 한국 청주에 일본 사케의 준마이·긴죠 등급을 적용하지 않습니다. null은 아직 검수하지 않은 제품이며 일본산이라는 뜻이 아닙니다.

country.scope가 brand이면 브랜드 생산 자료 기준입니다. 해당 포장의 제조 라벨까지 확인했다는 뜻은 아닙니다. country.scope가 product이면 검수한 제품 종류의 제조국가 자료 기준이며, 특정 포장 용량까지 확인했다는 뜻은 아닙니다. brand.brewery와 brand.brewery.area는 브랜드 카탈로그 정보이므로 모든 제품의 제조국가로 사용하지 마세요. 닷사이 BLUE의 미국 생산 근거는 제품별 reviewed_classification에 있으며 일반 닷사이 제품으로 확대하지 않습니다. source.published_on은 자료 발표일, checked_on은 검수일이며 현재 재고 확인일이 아닙니다. 이름·브랜드·등급이 검수 대상과 달라지면 재검수 전 공개하지 않습니다.

제품의 맛 추정

taste_estimate는 이 제품의 참고값이며 실제 사용자 평가와 구별합니다. catalog_estimate는 양조 수치나 등급·도수 등에서 계산한 추정값이고, manufacturer_chart는 제조사가 공개한 차트입니다. 감각의 세기는 1~5이며, 입력이 없는 축은 null입니다. 브랜드 스타일이나 사용자의 선호 점수로 바꾸어 해석하지 마세요.

method_version, inputs의 입력값·출처, computed_at의 계산 시각으로 계산 근거를 확인할 수 있습니다. 계산 시각은 원자료 관측일이 아닙니다. catalog_unverified는 개별 제조사 출처를 확인한 속성이 아닙니다. 과거 계산을 복원하지 못한 행은 버전과 입력 근거가 null 또는 빈 배열이며, 프로필이 없는 제품은 taste_estimate가 null입니다.

정보를 해석하는 방법

• 추천 이유는 editorial_inference, 제조사 설명은 별도 필드입니다. 직접 시음이나 제조사 보증으로 바꾸어 설명하지 마세요.
• 응답의 guide/product URL을 출처로 연결하면 사용자가 근거와 상세 정보를 확인할 수 있습니다.
• 브랜드 평점·맛을 모든 제품의 평점·맛으로 옮기지 마세요. 가격·국내 판매처·재고는 현재 확인하지 않습니다.
• 만 19세 이상을 위한 사케 정보입니다. API는 구매·발주를 처리하지 않으며 개인 기록을 제공하지 않습니다.

AI 대화에서 마신 기록으로 이어가기

사용자가 실제로 마신 사케의 감상을 공유하고 싶다고 할 때, 제품·브랜드 응답의 record_draft_url로 연결할 수 있습니다. 일반적인 추천 질문을 마신 기록으로 만들지 마세요. 전체 대화 대신 사용자가 고른 감상과 직접 말한 날짜만 사용합니다.

const draft = {version: 1, note: userSelectedNote};
const link = result.record_draft_url
  + '#draft=' + encodeURIComponent(JSON.stringify(draft));

감상은 최대500자이며, drank_on에 사용자가 직접 말한 과거·오늘 날짜를 YYYY-MM-DD로 넣을 수 있습니다. 모르는 날짜는 생략하고 별점은 만들지 않습니다. 내용은 URL의 fragment에만 넣으며 API 요청·주소의 query·외부 분석 도구에 전송하지 마세요.

연결 화면에서 당사자가 내용과 실제 마신 사실을 확인한 뒤, 기존 기록 작성으로 이어갑니다. 이 단계는 기기에24시간 초안을 준비하며 공개 게시가 아닙니다. 로그인·사용자 자신의 별점·명시적인 저장은 그대로 필요합니다. 다른 작성 중인 기록은 덮어쓰지 않습니다. 현재는 마신 기록으로 연결하며 일반 질문 게시판이나 계정 대화 조회 기능은 제공하지 않습니다.

연동과 운영

응답은 schema_version 1.0이며 JSON·UTF-8 형식입니다. GET만 지원하고 최대 8개 카탈로그 후보를 반환합니다. CORS는 공개 읽기를 허용합니다. 캐시 지시를 지키고, 503에는 Retry-After에 따라 재시도하세요. 잘못된 요청은 400, 없는 제품은 404입니다. 검수 후 통합한 제품의 예전 ID는 308 응답의 Location을 따라 같은 제품으로 연결됩니다. 응답의 id와 url을 기준으로 제품을 저장하세요. 웹 조회를 사람의 수요 이벤트로 기록하지 않습니다.

현재 서비스는 일반 HTTP API입니다. A2A 작업·메시지 처리 서버나 MCP 서버는 구현하지 않았습니다. 해당 규격을 지원하는 것처럼 Agent Card를 게시하지 않습니다. API 추가만으로 특정 AI 서비스의 추천·인용이 보장되는 것도 아닙니다.