{"openapi":"3.1.0","info":{"title":"팜템포 공개 API","version":"2026-10-01","description":"농산물 시세·경락·표준 품목·이벤트 공개 데이터 API. 응답은 관측값과 기준일이며 예측이 아닙니다. 이용 조건: /api/spec/terms","termsOfService":"https://api.farmtempo.com/api/spec/terms","contact":{"name":"팜템포","url":"https://app.farmtempo.com"}},"servers":[{"url":"https://api.farmtempo.com"}],"paths":{"/api/market/summary":{"get":{"tags":["시세"],"summary":"Market Summary","description":"대시보드 상단 요약 — 등급 분포, 데이터 최신일, 전일 급등락 상위 N.","operationId":"market_summary","parameters":[{"name":"top","in":"query","required":false,"schema":{"type":"integer","maximum":20,"minimum":1,"default":5,"title":"Top"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"grade_distribution":{"type":"object","properties":{"A":{"type":"integer"},"B":{"type":"integer"},"C":{"type":"integer"}}},"total_items":{"type":"integer"},"data_latest_date":{"type":"string"},"currency":{"type":"string"},"bridge":{"type":"object","properties":{"series":{"type":"integer"},"last_date":{"type":"string"},"since":{"type":"string"},"basis":{"type":"string"}}},"derived":{"type":"object","properties":{"item_carryforward":{"type":"boolean"},"item_seasonal_normal":{"type":"boolean"}}},"crosscheck":{"type":"object","properties":{"quarantined":{"type":"integer"},"basis":{"type":"string"},"items":{"type":"array","items":{}},"ran_at":{"type":"string"},"big_pct":{"type":"number"},"max_ratio":{"type":"number"},"unverifiable_moves":{"type":"integer"},"unmapped_series":{"type":"integer"}}},"top_gainers":{"type":"array","items":{"type":"object"}},"top_losers":{"type":"array","items":{"type":"object"}},"movers_filter":{"type":"object","properties":{"fresh_window_days":{"type":"integer"},"max_obs_gap_days":{"type":"integer"},"eligible":{"type":"integer"},"excluded_stale":{"type":"integer"},"excluded_obs_gap":{"type":"integer"},"excluded_mirror":{"type":"integer"}}},"disclaimer":{"type":"string"}}},"example":{"grade_distribution":{"A":25,"B":71,"C":34},"total_items":130,"data_latest_date":"2026-09-30","currency":"KRW","bridge":{"series":113,"last_date":"2026-09-30","since":"2026-04-01","basis":"KAMIS periodProductList(도매·상품)을 겹침구간 중앙비로 보정해 이어붙였습니다. 검증 시계열(예측 입력)은 변경하지 않았습니다."},"derived":{"item_carryforward":true,"item_seasonal_normal":true},"crosscheck":{"quarantined":0,"basis":"KAMIS 원본 이상치를 전국 경락 낙찰가와 대조해 제외합니다. 판정은 '대폭 이동'에만 적용하고, 배수비(KAMIS 배수/경락 배수)가 임계를 넘으면 그 관측을 표시에서 뺍니다. 값은 마지막으로 검증된 관측으로 돌아갑니다.","items":[],"ran_at":"2026-10-01T06:40:02","big_pct":40.0,"max_ratio":1.8,"unverifiable_moves":1,"unmapped_series":46},"top_gainers":[{"item_key":"풋고추|03","display_name":"청양고추","grade":"A","grade_reason":"검증된 예측 계열 — 30년 데이터 백테스트 통과(마지막 3년 봉인 검증). 3스케일 방향 예측 제공.","unit_label":"원/kg","currency":"KRW","n_days":5804,"first_date":"2003-01-02","last_date":"2026-09-30","forecast_available":true,"has_volume":true,"price":5590.0,"change_pct":6.31,"vs_normal_pct":-1.52,"obs_gap_days":1,"change_basis":"ok","normal_basis":"climatology","carryforward_pct":2.3,"normal_n_years":3},{"item_key":"오이|02","display_name":"오이(다다기)","grade":"A","grade_reason":"검증된 예측 계열 — 30년 데이터 백테스트 통과(마지막 3년 봉인 검증). 3스케일 방향 예측 제공.","unit_label":"원/개","currency":"KRW","n_days":3477,"first_date":"2012-01-02","last_date":"2026-09-30","forecast_available":true,"has_volume":true,"price":369.2,"change_pct":4.29,"vs_normal_pct":-52.97,"obs_gap_days":1,"change_basis":"ok","normal_basis":"climatology","carryforward_pct":2.0,"normal_n_years":3}],"top_losers":[{"item_key":"알배기배추|00","display_name":"알배기배추","grade":"C","grade_reason":"관측 675일 — 시세 조회만 제공합니다. 관측 이력 부족으로 예측 신뢰도 확보 전입니다.","unit_label":"원/kg","currency":"KRW","n_days":675,"first_date":"2023-06-01","last_date":"2026-09-30","forecast_available":false,"has_volume":false,"price":3810.0,"change_pct":-18.46,"vs_normal_pct":null,"obs_gap_days":1,"change_basis":"ok","normal_basis":"thin","carryforward_pct":4.1,"normal_n_years":1},{"item_key":"시금치|00","display_name":"시금치","grade":"A","grade_reason":"검증된 예측 계열 — 30년 데이터 백테스트 통과(마지막 3년 봉인 검증). 3스케일 방향 예측 제공.","unit_label":"원/kg","currency":"KRW","n_days":7831,"first_date":"1996-01-03","last_date":"2026-09-30","forecast_available":true,"has_volume":true,"price":7250.0,"change_pct":-17.47,"vs_normal_pct":9.52,"obs_gap_days":1,"change_basis":"ok","normal_basis":"climatology","carryforward_pct":5.6,"normal_n_years":3}],"movers_filter":{"fresh_window_days":7,"max_obs_gap_days":7,"eligible":77,"excluded_stale":34,"excluded_obs_gap":18,"excluded_mirror":1},"disclaimer":"단가는 KAMIS 도매·상품 거래단위 정규화가(원/단위, 통화 KRW). A등급만 검증된 3스케일 방향 예측 제공, B·C등급은 시세만. 반입량 미포함."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"top":"3"},"x-example-path":"/api/market/summary"}},"/api/market/items":{"get":{"tags":["시세"],"summary":"Market List Items","description":"전품목 시세 목록. 등급·표기명·최근 시세·전일비·평년비.\n\nA등급=검증된 예측 계열(예측 제공), B등급=시세 상세, C등급=시세 조회.\n단가는 KAMIS 도매·상품 정규화가(원/단위, KRW). 반입량 미포함(이번 범위).","operationId":"market_list_items","parameters":[{"name":"grade","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"A|B|C 필터","title":"Grade"},"description":"A|B|C 필터"},{"name":"buryu","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"부류 필터(이번 범위: 미설정)","title":"Buryu"},"description":"부류 필터(이번 범위: 미설정)"},{"name":"q","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"품목명 검색","title":"Q"},"description":"품목명 검색"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","description":"change|vs_normal|name","default":"change","title":"Sort"},"description":"change|vs_normal|name"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"items":{"type":"array","items":{"type":"object"}},"currency":{"type":"string"},"derived":{"type":"object","properties":{"item_carryforward":{"type":"boolean"},"item_seasonal_normal":{"type":"boolean"}}},"crosscheck":{"type":"object","properties":{"quarantined":{"type":"integer"},"basis":{"type":"string"},"items":{"type":"array","items":{}},"ran_at":{"type":"string"},"big_pct":{"type":"number"},"max_ratio":{"type":"number"},"unverifiable_moves":{"type":"integer"},"unmapped_series":{"type":"integer"}}},"wholesale_live":{"type":"object","properties":{"date":{"type":"string"},"covered":{"type":"integer"},"excluded_outlier":{"type":"integer"},"mapped_series":{"type":"integer"},"note":{"type":"string"}}},"disclaimer":{"type":"string"}}},"example":{"count":2,"items":[{"item_key":"방울토마토|02","display_name":"대추방울토마토","grade":"C","grade_reason":"관측 1,648일 — 시세 조회만 제공합니다. 관측 이력 부족으로 예측 신뢰도 확보 전입니다.","unit_label":"원/kg","currency":"KRW","n_days":1648,"first_date":"2019-06-12","last_date":"2026-09-30","forecast_available":false,"has_volume":false,"price":9020.0,"change_pct":-0.95,"vs_normal_pct":33.12,"obs_gap_days":1,"change_basis":"ok","normal_basis":"climatology","carryforward_pct":25.8,"normal_n_years":3,"stale_days":0,"auction":{"price":4849.0,"date":"2026-10-01","unit":"원/kg","basis":"전국 도매시장 경락 낙찰가","garak_pum_nm":"방울토마토","comparable":true,"note":null},"wholesale_live":{"price":8000.0,"date":"09/30","unit":"원/kg","basis":"KAMIS 도매시장 실측(상품)","observed":"당일","kamis_unit":"3kg","kind_name":"대추방울토마토(3kg)"}},{"item_key":"방울토마토|KA","display_name":"방울토마토","grade":"B","grade_reason":"관측 7,273일 · 최근 활성 — 시세 상세를 제공합니다. 예측은 검증 통과 전이라 제공하지 않습니다.","unit_label":"원/kg","currency":"KRW","n_days":7273,"first_date":"1998-01-03","last_date":"2026-09-30","forecast_available":false,"has_volume":true,"price":9020.0,"change_pct":-0.95,"vs_normal_pct":33.12,"obs_gap_days":1,"change_basis":"ok","normal_basis":"climatology","carryforward_pct":19.1,"normal_n_years":3,"stale_days":0,"auction":{"price":4849.0,"date":"2026-10-01","unit":"원/kg","basis":"전국 도매시장 경락 낙찰가","garak_pum_nm":"방울토마토","comparable":true,"note":null},"wholesale_live":{"price":8000.0,"date":"09/30","unit":"원/kg","basis":"KAMIS 도매시장 실측(상품)","observed":"당일","kamis_unit":"3kg","kind_name":"대추방울토마토(3kg)"}}],"currency":"KRW","derived":{"item_carryforward":true,"item_seasonal_normal":true},"crosscheck":{"quarantined":0,"basis":"KAMIS 원본 이상치를 전국 경락 낙찰가와 대조해 제외합니다. 판정은 '대폭 이동'에만 적용하고, 배수비(KAMIS 배수/경락 배수)가 임계를 넘으면 그 관측을 표시에서 뺍니다. 값은 마지막으로 검증된 관측으로 돌아갑니다.","items":[],"ran_at":"2026-10-01T06:40:02","big_pct":40.0,"max_ratio":1.8,"unverifiable_moves":1,"unmapped_series":46},"wholesale_live":{"date":"09/30","covered":2,"excluded_outlier":0,"mapped_series":81,"note":"당일 KAMIS 도매 실측을 검증 시계열과 별도로 병기합니다. price 는 여전히 정산 도매가(~last_date)입니다."},"disclaimer":"단가는 KAMIS 도매·상품 거래단위 정규화가(원/단위, 통화 KRW). A등급만 검증된 3스케일 방향 예측 제공, B·C등급은 시세만. 반입량 미포함."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"q":"방울토마토"},"x-example-path":"/api/market/items"}},"/api/market/items/{item_key}":{"get":{"tags":["시세"],"summary":"Market Get Item","description":"품목 상세 — 시세 추이 + 평년 밴드 + 등급/등급사유.\n\n⚠ B·C등급 응답에는 예측 필드가 **없습니다**(부재). A등급만 forecast_available=true이며\n실제 3스케일 방향 예측·신뢰도는 기존 예측 파이프라인이 제공합니다.\n반입량·법인집중도는 이번 범위 밖(원자료 확보 후 추가).","operationId":"market_get_item","parameters":[{"name":"item_key","in":"path","required":true,"schema":{"type":"string","title":"Item Key"}},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":11000,"minimum":7,"description":"최근 N일 시세 추이","default":365,"title":"Days"},"description":"최근 N일 시세 추이"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"item_key":{"type":"string"},"display_name":{"type":"string"},"grade":{"type":"string"},"grade_reason":{"type":"string"},"unit_label":{"type":"string"},"currency":{"type":"string"},"n_days":{"type":"integer"},"first_date":{"type":"string"},"last_date":{"type":"string"},"forecast_available":{"type":"boolean"},"has_volume":{"type":"boolean"},"snapshot":{"type":"object","properties":{"last_date":{"type":"string"},"price":{"type":"number"},"change_pct":{"type":"number"},"vs_normal_pct":{"type":"number"},"obs_gap_days":{"type":"integer"},"change_basis":{"type":"string"},"normal_basis":{"type":"string"},"carryforward_pct":{"type":"number"},"normal_n_years":{"type":"integer"}}},"series":{"type":"array","items":{"type":"object"}},"normal_band_basis":{"type":"string"},"field_notes":{"type":"object","properties":{"low_price/high_price":{"type":"string"},"mid_price":{"type":"string"},"retail_price":{"type":"string"}}},"disclaimer":{"type":"string"},"auction":{"type":"object","properties":{"price":{"type":"number"},"date":{"type":"string"},"unit":{"type":"string"},"basis":{"type":"string"},"garak_pum_nm":{"type":"string"},"comparable":{"type":"boolean"},"note":{"type":"null"}}},"volume":{"type":"object","properties":{"garak_pum_nm":{"type":"string"},"buryu":{"type":"string"},"unit":{"type":"string"},"settle_lag_days":{"type":"integer"},"latest":{"type":"object"},"series":{"type":"array","items":{"type":"object"}},"note":{"type":"string"},"data_through":{"type":"string"},"age_days":{"type":"integer"},"stale":{"type":"boolean"}}},"no_forecast_note":{"type":"string"}}},"example":{"item_key":"방울토마토|KA","display_name":"방울토마토","grade":"B","grade_reason":"관측 7,273일 · 최근 활성 — 시세 상세를 제공합니다. 예측은 검증 통과 전이라 제공하지 않습니다.","unit_label":"원/kg","currency":"KRW","n_days":7273,"first_date":"1998-01-03","last_date":"2026-03-31","forecast_available":false,"has_volume":true,"snapshot":{"last_date":"2026-09-30","price":9020.0,"change_pct":-0.95,"vs_normal_pct":33.12,"obs_gap_days":1,"change_basis":"ok","normal_basis":"climatology","carryforward_pct":19.1,"normal_n_years":3},"series":[{"date":"2026-09-18","price_norm":8533.3333,"price_raw":8533.3,"low_price":null,"high_price":null,"mid_price":null,"retail_price":null,"bridged":1,"normal":10322.0},{"date":"2026-09-21","price_norm":8826.6667,"price_raw":8826.7,"low_price":null,"high_price":null,"mid_price":null,"retail_price":null,"bridged":1,"normal":9007.0}],"normal_band_basis":"climatology","field_notes":{"low_price/high_price":"KAMIS '당일최저가격/당일최대가격'(도매·상품)을 단위중량으로 나눈 값. price_norm 과 같은 척도이며 price_raw(포장 단위)와 다르다. 2024-11-19 이전 원천에 최저>최대인 날이 있어 그 날은 null + range_flag='source_inverted'. 2024-11-20 전후로 구간 폭이 달라져 비교하지 말 것.","mid_price":"구간 중앙값이 아니라 도매·중품 단위당 가격.","retail_price":"소매·상품 단위당 가격. 품목에 따라 단위(g·개)가 price_norm 과 다를 수 있다."},"disclaimer":"단가는 KAMIS 도매·상품 거래단위 정규화가(원/단위, 통화 KRW). A등급만 검증된 3스케일 방향 예측 제공, B·C등급은 시세만. 반입량 미포함.","auction":{"price":4849.0,"date":"2026-10-01","unit":"원/kg","basis":"전국 도매시장 경락 낙찰가","garak_pum_nm":"방울토마토","comparable":true,"note":null},"volume":{"garak_pum_nm":"방울토마토","buryu":"과일과채류","unit":"톤","settle_lag_days":3,"latest":{"obs_date":"2026-09-30","qty_ton":62.94,"hhi":0.3536,"n_firms":5,"concentration":"집중(과점)"},"series":[{"date":"2024-05-06","qty_ton":105.17,"hhi":0.3793,"n_firms":5},{"date":"2024-05-07","qty_ton":95.8,"hhi":0.349,"n_firms":5}],"note":"가락시장 반입량(공급). 법인 집중도 HHI=Σ(법인점유율²). 거래량·수요 아님.","data_through":"2026-09-30","age_days":1,"stale":false},"no_forecast_note":"팜템포는 시세가 올라오는 모든 품목을 보여드립니다. 다만 예측은 검증을 통과한 품목에만 제공합니다. 30년 데이터로 학습·검증하고, 마지막 3년은 한 번도 열어보지 않은 구간으로 남겨 성능을 확인했습니다. 그 검증을 통과하지 못한 품목에 예측을 붙이는 것은 근거 없는 숫자를 드리는 일이라 하지 않습니다."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"days":"7"},"x-example-path":"/api/market/items/방울토마토|KA"}},"/api/market/items/{item_key}/series":{"get":{"tags":["시세"],"summary":"Market Item Series","description":"시계열 원본. freq=sun 이면 10일(순) 중앙값으로 집계.","operationId":"market_item_series","parameters":[{"name":"item_key","in":"path","required":true,"schema":{"type":"string","title":"Item Key"}},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"From"}},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"To"}},{"name":"freq","in":"query","required":false,"schema":{"type":"string","description":"day|sun(순·10일)","default":"day","title":"Freq"},"description":"day|sun(순·10일)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"item_key":{"type":"string"},"freq":{"type":"string"},"count":{"type":"integer"},"series":{"type":"array","items":{"type":"object"}},"currency":{"type":"string"}}},"example":{"item_key":"방울토마토|KA","freq":"day","count":5,"series":[{"date":"2026-09-22","price":9053.3},{"date":"2026-09-23","price":9700.0}],"currency":"KRW"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"from":"2026-09-22","to":"2026-09-30"},"x-example-path":"/api/market/items/방울토마토|KA/series"}},"/api/market/ticker":{"get":{"tags":["시세"],"summary":"Market Ticker","description":"[B2AI] 시세 티커 — 품목·가격(원/kg)·전일 대비 %.\n\n⛔ **표시 시각과 기준일을 반드시 함께 준다.** 어제 값을 실시간처럼 보이게 하지 않는다.\n박거래 품목(거래 50건·1,000kg 미만)은 등락률이 노이즈라 제외한다 — 제외 수는 응답에 명시.","operationId":"market_ticker","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":40,"minimum":1,"default":12,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"as_of":{"type":"string"},"basis_date":{"type":"string"},"compare_date":{"type":"string"},"unit":{"type":"string"},"currency":{"type":"string"},"provisional":{"type":"boolean"},"collected_at":{"type":"string"},"floor":{"type":"object","properties":{"min_trades":{"type":"integer"},"min_qty_kg":{"type":"number"},"excluded_thin":{"type":"integer"}}},"items":{"type":"array","items":{"type":"object"}},"note":{"type":"string"}}},"example":{"as_of":"2026-10-01T00:24:16+00:00","basis_date":"2026-10-01","compare_date":"2026-09-30","unit":"원/kg","currency":"KRW","provisional":true,"collected_at":"2026-10-01T07:35:29","floor":{"min_trades":50,"min_qty_kg":1000.0,"excluded_thin":2},"items":[{"item":"열무","price_krw_kg":791.2,"change_pct":54.4},{"item":"참외","price_krw_kg":2536.6,"change_pct":42.1}],"note":"2026-10-01 경매 진행 중 잠정 집계입니다 — 오후 경매 미포함, 값이 바뀔 수 있습니다."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"limit":"3"},"x-example-path":"/api/market/ticker"}},"/api/market/calendar":{"get":{"tags":["시세"],"summary":"Market Calendar","description":"[B2AI] 도매시장 개장/휴장과 다음 개장일.\n\n⛔ Phase 12a 의 판정 함수(`receipt_price.market_status`)를 **그대로** 쓴다.\n영수증 시세 대조와 이 캘린더가 다른 답을 내면 안 된다.\n\n`OPEN`=거래 있음 · `MARKET_CLOSED`=휴장(수집됐으나 거래 0건) · `NO_DATA`=미수집.\n휴장과 미수집을 뭉뚱그리지 않는다.","operationId":"market_calendar","parameters":[{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"YYYY-MM-DD (생략 시 오늘)","title":"Date"},"description":"YYYY-MM-DD (생략 시 오늘)"},{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":31,"minimum":1,"default":7,"title":"Days"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"date":{"type":"string"},"status":{"type":"string"},"expected":{"type":"null"},"is_open":{"type":"boolean"},"label":{"type":"string"},"is_fact":{"type":"boolean"},"items_today":{"type":"array","items":{"type":"string"}},"next_open":{"type":"null"},"next_open_is_fact":{"type":"boolean"},"last_open":{"type":"string"},"calendar":{"type":"array","items":{"type":"object"}},"weekday_profile":{"type":"object","properties":{"0":{"type":"object"},"1":{"type":"object"},"2":{"type":"object"},"3":{"type":"object"},"4":{"type":"object"},"5":{"type":"object"},"6":{"type":"object"}}},"collected_range":{"type":"object","properties":{"from":{"type":"string"},"to":{"type":"string"}}},"source":{"type":"string"},"note":{"type":"string"}}},"example":{"date":"2026-10-01","status":"OPEN","expected":null,"is_open":true,"label":"오늘 개장","is_fact":true,"items_today":["감귤","감자"],"next_open":null,"next_open_is_fact":false,"last_open":"2026-09-30","calendar":[{"date":"2026-09-28","status":"OPEN","n_items":34},{"date":"2026-09-29","status":"OPEN","n_items":34}],"weekday_profile":{"0":{"open":16,"closed":0},"1":{"open":16,"closed":0},"2":{"open":16,"closed":0},"3":{"open":16,"closed":1},"4":{"open":15,"closed":1},"5":{"open":15,"closed":1},"6":{"open":2,"closed":14}},"collected_range":{"from":"2026-06-11","to":"2026-10-01"},"source":"전국 도매시장 경락 낙찰가 수집분","note":"MARKET_CLOSED 는 휴장, NO_DATA 는 미수집입니다. 서로 다른 뜻입니다. `expected` 는 관측된 요일 패턴에 따른 예상이며 확정된 사실이 아닙니다 (`is_fact` 로 구분하십시오)."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"days":"3"},"x-example-path":"/api/market/calendar"}},"/api/market/egg":{"get":{"tags":["시세"],"summary":"Egg Latest","operationId":"market_egg_latest","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":60,"minimum":3,"description":"시계열 일수","default":14,"title":"Days"},"description":"시계열 일수"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"item":{"type":"string"},"date":{"type":"string"},"producer":{"type":"object","properties":{"unit":{"type":"string"},"kind":{"type":"string"},"source":{"type":"string"},"grades":{"type":"array","items":{"type":"object"}}}},"retail":{"type":"object","properties":{"unit":{"type":"string"},"kind":{"type":"string"},"source":{"type":"string"},"XL_30":{"type":"integer"},"XL_10":{"type":"integer"}}},"spread_xl_30":{"type":"object","properties":{"krw":{"type":"integer"},"pct":{"type":"number"}}},"change_pct_xl_30_vs_prev":{"type":"number"},"series":{"type":"array","items":{"type":"object"}},"regions":{"type":"object","properties":{"unit":{"type":"string"},"grade":{"type":"string"},"old_name":{"type":"string"},"date":{"type":"string"},"kind":{"type":"string"},"pilot_region":{"type":"string"},"source":{"type":"string"},"items":{"type":"array","items":{"type":"object"}},"series":{"type":"object"}}},"assumptions":{"type":"array","items":{"type":"string"}},"display_rule":{"type":"string"}}},"example":{"ok":true,"item":"계란","date":"2026-09-30","producer":{"unit":"원/30개 · 10개","kind":"조사가(실거래)","source":"축산물품질평가원 축산유통정보 · 전국 산지가격","grades":[{"grade":"2XL","old_name":"왕란","p30":6358,"p10":2119},{"grade":"XL","old_name":"특란","p30":6097,"p10":2032}]},"retail":{"unit":"원","kind":"조사가","source":"KAMIS 축산물(계란) 소매가 · 특란만 수록","XL_30":6882,"XL_10":4208},"spread_xl_30":{"krw":785,"pct":11.4},"change_pct_xl_30_vs_prev":-1.0,"series":[{"date":"2026-09-28","producer_xl_30":6137,"retail_xl_30":6885,"spread_pct":10.9},{"date":"2026-09-29","producer_xl_30":6161,"retail_xl_30":6885,"spread_pct":10.5}],"regions":{"unit":"원/30개","grade":"XL","old_name":"특란","date":"2026-09-30","kind":"조사가(실거래)","pilot_region":"충청권","source":"축산물품질평가원 권역별 산지가격(XL 30개 · 7권역 시범 발표)","items":[{"region":"전국","p30":6097,"chg_pct":-1.0,"vs_nation_krw":null,"vs_nation_pct":null},{"region":"수도권","p30":6017,"chg_pct":-1.8,"vs_nation_krw":-80,"vs_nation_pct":-1.3}],"series":{"경남":[{"date":"2026-09-28","p30":6179},{"date":"2026-09-29","p30":6239}],"경북":[{"date":"2026-09-28","p30":6073},{"date":"2026-09-29","p30":6145}],"수도권":[{"date":"2026-09-28","p30":6177},{"date":"2026-09-29","p30":6130}],"전국":[{"date":"2026-09-28","p30":6137},{"date":"2026-09-29","p30":6161}],"전남":[{"date":"2026-09-28","p30":5900},{"date":"2026-09-29","p30":6079}],"전북":[{"date":"2026-09-28","p30":6391},{"date":"2026-09-29","p30":6286}],"제주":[{"date":"2026-09-28","p30":6072},{"date":"2026-09-29","p30":6084}],"충청권":[{"date":"2026-09-28","p30":6285},{"date":"2026-09-29","p30":6105}]}},"assumptions":["산지가는 축산물품질평가원이 매일 조사·발표하는 전국 산지 실거래 가격입니다(후장기 거래 제외) — 협회 고시가가 아니며, 농장 출하 단계 가격이라 마트 판매가보다 낮습니다.","규격 2XL·XL·L·M·S 는 축산법 시행규칙 별표23 신명칭이며 왕란·특란·대란·중란·소란과 1:1 입니다(2026-05-21 시행, 11월까지 병기)."],"display_rule":"산지(축평원 조사가)와 소매(KAMIS 조사가)는 조사기관·유통단계가 다르므로 한 줄에 섞지 않고 출처를 각각 표기합니다."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"days":"3"},"x-example-path":"/api/market/egg"}},"/api/auction/markets":{"get":{"tags":["경락"],"summary":"공영도매시장 코드·명 목록","description":"경락 조회에 사용할 수 있는 전국 공영도매시장 코드(예: 110001=서울가락)와 한글명 목록. /api/auction/price 의 market 파라미터에 코드·한글명 모두 사용 가능.","operationId":"get_auction_markets_api_auction_markets_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"count":{"type":"integer"},"markets":{"type":"array","items":{"type":"object"}}},"title":"Response Get Auction Markets Api Auction Markets Get"},"example":{"count":31,"markets":[{"code":"110001","name":"서울가락"},{"code":"110008","name":"서울강서"}]}}}}},"parameters":[],"x-example-path":"/api/auction/markets"}},"/api/auction/price":{"get":{"tags":["경락"],"summary":"품목×시장 경락 요약 + KAMIS 도매가 비교","description":"특정 품목의 경락(낙찰) 요약을 반환한다. 단위는 원/kg(거래중량 가중평균).\n\n- market 지정: 해당 시장 1곳의 평균 낙찰가·총물량·거래건수·가격범위 + KAMIS 정산 도매가 비교(기준 상이: 경락=낙찰가, KAMIS=정산 도매가).\n- market 생략: 전 시장을 평균가 오름차순(어디가 싼지)으로 반환.\n- date 생략: 최신 수집일 자동.\n- market 매칭: 코드(110001)·한글명(서울가락)·부분일치(가락) 모두 허용. 부분일치 복수 시 후보 목록 반환.\n- 미존재 품목·시장·날짜는 404 아닌 200 + {found:false, hint}.","operationId":"get_auction_price_api_auction_price_get","parameters":[{"name":"item","in":"query","required":true,"schema":{"type":"string","description":"품목 한글명. 예: 양파, 마늘, 배추, 사과, 복숭아","title":"Item"},"description":"품목 한글명. 예: 양파, 마늘, 배추, 사과, 복숭아"},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"도매시장 코드(110001)·한글명(서울가락)·부분일치(가락). 생략 시 전 시장.","title":"Market"},"description":"도매시장 코드(110001)·한글명(서울가락)·부분일치(가락). 생략 시 전 시장."},{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"거래정산일 YYYY-MM-DD. 생략 시 최신 수집일.","title":"Date"},"description":"거래정산일 YYYY-MM-DD. 생략 시 최신 수집일."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean"},"item":{"type":"string"},"date":{"type":"string"},"currency":{"type":"string"},"unit":{"type":"string"},"price_basis":{"type":"string"},"all_market":{"type":"object","properties":{"avg_price_krw_kg":{"type":"number"},"total_qty_kg":{"type":"number"},"trade_count":{"type":"integer"},"price_range":{"type":"object"}}},"markets":{"type":"array","items":{"type":"object"}},"market_count":{"type":"integer"},"kamis_ref":{"type":"object","properties":{"wholesale_price_krw_kg":{"type":"integer"},"price_basis":{"type":"string"},"as_of":{"type":"string"},"note":{"type":"string"}}},"description":{"type":"string"}},"title":"Response Get Auction Price Api Auction Price Get"},"example":{"found":true,"item":"토마토","date":"2026-10-01","currency":"KRW","unit":"원/kg","price_basis":"경락 낙찰가 (KAT katRealTime2)","all_market":{"avg_price_krw_kg":3041.6,"total_qty_kg":270738.0,"trade_count":2793,"price_range":{"min":200.0,"max":18500.0}},"markets":[{"market_code":"240001","market_name":"광주각화","avg_price_krw_kg":2228.0,"total_qty_kg":4605.0,"trade_count":77,"price_range":{"min":200.0,"max":18500.0}},{"market_code":"110008","market_name":"서울강서","avg_price_krw_kg":2410.5,"total_qty_kg":9920.0,"trade_count":100,"price_range":{"min":600.0,"max":4300.0}}],"market_count":24,"kamis_ref":{"wholesale_price_krw_kg":4400,"price_basis":"wholesale","as_of":"2026-09-30","note":"경락=낙찰가·KAMIS=정산 도매가, 기준 상이"},"description":"2026-10-01 토마토 경락은 24개 시장 평균 kg당 약 3,042원(총 270,738kg). 최저가 시장은 광주각화(2,228원/kg). KAMIS 정산 도매가 4,400원/kg(기준 상이)."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"item":"토마토"},"x-example-path":"/api/auction/price"}},"/api/auction/summary":{"get":{"tags":["경락"],"summary":"일별 품목×시장 경락 전체 요약 (사전집계)","description":"지정일(또는 최신 수집일)의 전 품목×시장 경락 요약을 사전집계 그대로 반환한다. 단위 원/kg(거래중량 가중평균), 경락 낙찰가 기준. 미수집·휴장일은 trading_day=false + hint.","operationId":"get_auction_summary_api_auction_summary_get","parameters":[{"name":"date","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"거래정산일 YYYY-MM-DD. 생략 시 최신 수집일.","title":"Date"},"description":"거래정산일 YYYY-MM-DD. 생략 시 최신 수집일."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"found":{"type":"boolean"},"trading_day":{"type":"boolean"},"date":{"type":"string"},"schema_version":{"type":"string"},"source":{"type":"string"},"trd_clcln_ymd":{"type":"string"},"provisional":{"type":"boolean"},"collected_at":{"type":"string"},"price_basis":{"type":"string"},"currency":{"type":"string"},"unit":{"type":"string"},"krw_per_kg_formula":{"type":"string"},"n_items":{"type":"integer"},"n_markets":{"type":"integer"},"n_rows_aggregated":{"type":"integer"},"n_rows_skipped":{"type":"integer"},"markets":{"type":"array","items":{"type":"object"}},"items":{"type":"object","properties":{"양파":{"type":"object"},"마늘":{"type":"object"},"감자":{"type":"object"}}}},"title":"Response Get Auction Summary Api Auction Summary Get"},"example":{"found":true,"trading_day":true,"date":"2026-10-01","schema_version":"v1.0","source":"auction_daily_summary","trd_clcln_ymd":"2026-10-01","provisional":true,"collected_at":"2026-10-01T07:35:29","price_basis":"경락 낙찰가 (KAT katRealTime2)","currency":"KRW","unit":"원/kg","krw_per_kg_formula":"Σ(scsbd_prc·qty)/Σ(unit_qty·qty) — 거래중량 가중평균","n_items":34,"n_markets":29,"n_rows_aggregated":57721,"n_rows_skipped":5,"markets":[{"code":"320301","name":"강릉"},{"code":"240001","name":"광주각화"}],"items":{"양파":{"item":"양파","all_market":{"avg_price_krw_kg":1125.9,"total_qty_kg":1190805.0,"trade_count":795,"price_range":{"min":105.0,"max":4200.0}},"by_market":[{"market_code":"370101","market_name":"포항","avg_price_krw_kg":295.5,"total_qty_kg":1820.0,"trade_count":2,"price_range":{"min":290.0,"max":300.0}},{"market_code":"250003","market_name":"대전노은","avg_price_krw_kg":963.0,"total_qty_kg":27900.0,"trade_count":24,"price_range":{"min":600.0,"max":1200.0}}]},"마늘":{"item":"마늘","all_market":{"avg_price_krw_kg":5640.8,"total_qty_kg":54613.6,"trade_count":265,"price_range":{"min":500.0,"max":66666.7}},"by_market":[{"market_code":"320201","market_name":"원주","avg_price_krw_kg":1735.5,"total_qty_kg":150.5,"trade_count":5,"price_range":{"min":525.0,"max":7876.0}},{"market_code":"370101","market_name":"포항","avg_price_krw_kg":1791.7,"total_qty_kg":24.0,"trade_count":3,"price_range":{"min":1250.0,"max":2100.0}}]},"감자":{"item":"감자","all_market":{"avg_price_krw_kg":1144.9,"total_qty_kg":519697.0,"trade_count":1105,"price_range":{"min":100.0,"max":2275.0}},"by_market":[{"market_code":"320201","market_name":"원주","avg_price_krw_kg":708.0,"total_qty_kg":1260.0,"trade_count":7,"price_range":{"min":500.0,"max":1510.0}},{"market_code":"360301","market_name":"순천","avg_price_krw_kg":828.8,"total_qty_kg":2570.0,"trade_count":11,"price_range":{"min":300.0,"max":1850.0}}]}}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-path":"/api/auction/summary"}},"/api/prices/wholesale":{"get":{"summary":"도매가 정규화 응답 (9품목 단일 스키마)","description":"**v2 신설 — 5대 원칙 #4 데이터 정규화 핵심 엔드포인트.** 9개 핵심 품목(배추·무·양파·대파·마늘·오이·감자·생고추·토마토)의 도매가를 품목당 1행 단일 스키마로 반환합니다.\n\n## 호출 메커니즘\n- KAMIS `dailyPriceByCategoryList` (도매: `p_product_cls_code=02`) 카테고리 200·100 두 번 호출 · 국가코드 비움 = 조사 도매시장(최대 5곳) 평균\n- 각 품목의 `(item_code, kind_code, rank_code)` 매칭으로 단일 행 추출\n- 도매 매칭 실패 품목은 `dailySalesList`(소매)로 자동 fallback\n\n## 핵심 필드\n- `today`, `yesterday`: 도매가 (KRW, KAMIS 단위 기준)\n- `unit`: KAMIS 도매시장 표준 단위 (예: '10kg', '100개')\n- `kg_per_unit`: 단위→kg 환산 계수 (품목 간 비교용)\n- `krw_per_kg`: **kg당 단가 (KRW/kg)** — 품목 간 직접 비교 가능한 정규화 가격\n- `kg_conversion_note`: 환산 근거 자연어 설명 (LLM 컨텍스트용)\n- `price_basis`: `\"wholesale\"` (도매 성공) / `\"retail_fallback\"` (소매 대체)\n- `as_of`: 실제 가격 기준일 (도매시장 마감 전이면 전일)\n- `kamis_item_code`, `kamis_kind_code`, `kamis_kind_name`, `kamis_rank`: 출처 추적용 메타필드\n- `coverage`: 9품목 중 도매/소매 fallback/누락 분포\n\n## /api/prices와의 차이\n- `/api/prices`: 소매가, 다중 단위 중복 가능 (대시보드 호환용)\n- `/api/prices/wholesale`: **도매가, 9품목, 정규화된 단일 스키마 (LLM/AI용)**\n\nReturns normalized wholesale prices (1 row per item) for 9 core items. Falls back to retail when wholesale unavailable (price_basis indicates source).","operationId":"get_wholesale_prices_api_prices_wholesale_get","parameters":[{"name":"regday","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"조회 기준일 (YYYY-MM-DD). 미지정 시 오늘. 도매시장 마감 전이면 dpr2(전일) 자동 fallback.","examples":["2026-04-30"],"title":"Regday"},"description":"조회 기준일 (YYYY-MM-DD). 미지정 시 오늘. 도매시장 마감 전이면 dpr2(전일) 자동 fallback."}],"responses":{"200":{"description":"정규화된 도매가 응답","content":{"application/json":{"schema":{"type":"object","properties":{"source":{"type":"string"},"generated_at":{"type":"string"},"regday":{"type":"string"},"requested_date":{"type":"string"},"regday_fallback_reason":{"type":"string"},"country_code":{"type":"string"},"country_name":{"type":"string"},"currency":{"type":"string"},"price_basis_default":{"type":"string"},"basis_summary":{"type":"object","properties":{"wholesale":{"type":"integer"},"retail_fallback":{"type":"integer"},"note":{"type":"string"}}},"as_of_range":{"type":"object","properties":{"oldest":{"type":"string"},"newest":{"type":"string"}}},"items":{"type":"array","items":{"type":"object"}},"coverage":{"type":"object","properties":{"requested":{"type":"integer"},"wholesale_matched":{"type":"integer"},"retail_fallback_used":{"type":"array","items":{"type":"string"}},"missing":{"type":"array","items":{"type":"string"}}}}}},"example":{"source":"kamis_wholesale","generated_at":"2026-04-30T17:00:00+09:00","regday":"2026-04-30","country_code":"","country_name":"KAMIS 조사 도매시장 평균","currency":"KRW","price_basis_default":"wholesale","items":[{"name":"배추","today":12200,"yesterday":12200,"change":0.0,"unit":"10kg(그물망 3포기)","kg_per_unit":10.0,"krw_per_kg":1220,"kg_conversion_note":"박스/그물망 표시지만 실 중량 10kg","currency":"KRW","price_basis":"wholesale","kamis_item_code":"211","kamis_kind_code":"06","kamis_kind_name":"월동(10kg(그물망 3포기))","kamis_rank":"상품","as_of":"2026-04-29","source":"kamis_wholesale"},{"name":"오이","today":40500,"yesterday":38000,"change":6.6,"unit":"100개","kg_per_unit":50.0,"krw_per_kg":810,"kg_conversion_note":"다다기 오이 1개≈500g, 100개≈50kg (도매 관행)","currency":"KRW","price_basis":"wholesale","kamis_item_code":"223","kamis_kind_code":"02","kamis_kind_name":"다다기계통(100개)","kamis_rank":"상품","as_of":"2026-04-29","source":"kamis_wholesale"},{"name":"마늘","today":57000,"yesterday":56500,"change":0.9,"unit":"10kg","kg_per_unit":10.0,"krw_per_kg":5700,"kg_conversion_note":"피마늘 난지(대서) 10kg","currency":"KRW","price_basis":"wholesale","kamis_item_code":"244","kamis_kind_code":"22","kamis_kind_name":"피마늘 난지(대서)(10kg)","kamis_rank":"상품","as_of":"2026-04-29","source":"kamis_wholesale"}],"coverage":{"requested":9,"wholesale_matched":8,"retail_fallback_used":["감자"],"missing":[],"note":"감자는 노지 시즌 외 시 dpr=\"-\" 정상 동작, retail_fallback 발동"}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["도매가"],"x-example-path":"/api/prices/wholesale"}},"/api/prices/seasonal":{"get":{"summary":"월별 평년 흐름 (KAMIS 평년)","description":"품목별 12개월 평년 가격 흐름입니다. 월값 = 올해 그 달 평일마다 구한 KAMIS 평년(지난 5년 같은 시기 ±3일 평일 평균 중 최고·최저를 뺀 3년 평균)의 평균. 단위는 계열 unit(원/kg 또는 원/개). 평년이 잡힌 평일이 10일 미만인 달은 null. 품목 매핑은 승인된 별칭만 쓰고, C등급 계열은 내지 않습니다(available=false, reason). 매입 시점 권고가 아니라 지난 5년의 계절 흐름입니다.\n\n12-month KAMIS 5-year normal (trimmed mean of 3 of 5 years) per item; low/high month of the normal.","operationId":"get_seasonal_prices_api_prices_seasonal_get","responses":{"200":{"description":"품목별 KAMIS 평년 월별 흐름","content":{"application/json":{"schema":{"type":"object","properties":{"months":{"type":"array","items":{"type":"string"}},"year":{"type":"integer"},"basis":{"type":"string"},"normal_def":{"type":"string"},"monthly_def":{"type":"string"},"items":{"type":"array","items":{"type":"object"}}},"title":"Response Get Seasonal Prices Api Prices Seasonal Get"},"example":{"months":["1월","2월","3월","4월","5월","6월","7월","8월","9월","10월","11월","12월"],"year":2026,"basis":"kamis_normal","normal_def":"KAMIS 평년: 지난 5년 같은 시기(±3일, 평일) 평균 중 최고·최저를 뺀 3년 평균","monthly_def":"2026년 그 달 평일마다 구한 KAMIS 평년의 평균. 평년이 잡힌 평일 10일 미만인 달은 null.","items":[{"name":"배추","monthly":[775,921,1143,1243,922,883,1245,1864,2237,1307,989,941],"available":true,"item_key":"배추|KA","series":"배추","grade":"A","unit":"원/kg","low_month":"1월","high_month":"9월","note":"평년 기준 1월 가장 낮음 · 9월 가장 높음"}]}}}}},"tags":["도매가"],"parameters":[],"x-example-path":"/api/prices/seasonal"}},"/api/v1/items":{"get":{"tags":["표준 품목"],"summary":"표준 품목 목록 — 소스별 매핑 신뢰도 요약(가격 없음)","operationId":"items_list","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object"}},"confidence_order":{"type":"array","items":{"type":"string"}},"note":{"type":"string"}}},"example":{"items":[{"canonical_item_id":"apple","category":"fruit","use_class":null,"name_ko":"사과","name_en":"Apple","name_ja":null,"name_zh":null,"aliases":["후지","홍로"],"description":"Dessert apple (Malus domestica); cultivar mix differs by country (Korea: Fuji, Hongro, Tsugaru; US: Gala, Fuji, Honeycrisp, Red Delicious).","mapping":{"overall":"provisional","by_source":{"garak_kat":"provisional","kamis_bulk":"provisional","kamis_sales":"provisional","kamis_wholesale":"provisional","usda_mars":"provisional"},"n_sources_confirmed":0}},{"canonical_item_id":"napa_cabbage","category":"vegetable","use_class":null,"name_ko":"배추","name_en":"Napa Cabbage","name_ja":null,"name_zh":null,"aliases":["김장배추","봄배추"],"description":"Napa (Chinese) cabbage (Brassica rapa subsp. pekinensis); Korean series split by season of cultivation, US series listed as 'Chinese Cabbage'.","mapping":{"overall":"provisional","by_source":{"garak_kat":"provisional","kamis_bulk":"provisional","kamis_sales":"provisional","kamis_wholesale":"provisional","usda_mars":"provisional"},"n_sources_confirmed":0}}],"confidence_order":["confirmed","provisional"],"note":"confirmed 는 사람이 검수해 확정한 매핑, provisional 은 초안. 가격은 이 API 에 없다."}}}}},"parameters":[],"x-example-path":"/api/v1/items"}},"/api/v1/items/resolve":{"get":{"tags":["표준 품목"],"summary":"자유 텍스트(한/영/일/중 표준명·별칭·소스 원문명) → 표준 품목. 부분 일치 안 함 · 두 축 표기와 근거 포함 · 로트 연결 없음","operationId":"items_resolve","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"title":"Q"}},{"name":"locale","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}],"title":"Locale"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"matched":{"type":"boolean"},"canonical_item_id":{"type":"string"},"confidence":{"type":"string"},"mapping_by_source":{"type":"object","properties":{"fda_ftl":{"type":"string"},"garak_kat":{"type":"string"},"garak_kat_corp":{"type":"string"},"garak_kat_std":{"type":"string"},"kamis_bulk":{"type":"string"},"kamis_sales":{"type":"string"},"kamis_wholesale":{"type":"string"},"usda_mars":{"type":"string"}}},"matched_by":{"type":"string"},"name_ko":{"type":"string"},"name_en":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"query":{"type":"string"},"locale":{"type":"null"},"value_state":{"type":"object","properties":{"value_origin":{"type":"string"},"value_origin_ko":{"type":"string"},"verification":{"type":"string"},"verification_ko":{"type":"string"},"usable_scope":{"type":"string"},"usable_scope_ko":{"type":"string"},"basis":{"type":"string"}}},"match_evidence":{"type":"string"},"mapping_by_source_axes":{"type":"object","properties":{"fda_ftl":{"type":"object"},"garak_kat":{"type":"object"},"garak_kat_corp":{"type":"object"},"garak_kat_std":{"type":"object"},"kamis_bulk":{"type":"object"},"kamis_sales":{"type":"object"},"kamis_wholesale":{"type":"object"},"usda_mars":{"type":"object"}}},"scope":{"type":"string"}}},"example":{"matched":true,"canonical_item_id":"tomato","confidence":"confirmed","mapping_by_source":{"fda_ftl":"provisional","garak_kat":"provisional","garak_kat_corp":"confirmed","garak_kat_std":"confirmed","kamis_bulk":"provisional","kamis_sales":"provisional","kamis_wholesale":"provisional","usda_mars":"provisional"},"matched_by":"name_ko","name_ko":"토마토","name_en":"Tomato","category":"vegetable","description":"Round (slicing) tomato; cherry, grape and plum types are separate items in both countries.","query":"토마토","locale":null,"value_state":{"value_origin":"rule_computed","value_origin_ko":"규칙 계산","verification":"provisional","verification_ko":"잠정","usable_scope":"with_provisional_label","usable_scope_ko":"잠정 표기와 함께만 사용","basis":"표준 품목 이름·별칭 정확 일치(규칙) · 표준 품목 이름·별칭 등록에는 사람 확인 기록이 없어 잠정"},"match_evidence":"'토마토' = tomato 의 한국어 표준명 정확 일치 → tomato [규칙 계산·잠정: 이름·별칭 등록은 사람 확인 기록 없음]","mapping_by_source_axes":{"fda_ftl":{"value_origin":"model_estimated","verification":"provisional","rows":1},"garak_kat":{"value_origin":"model_estimated","verification":"provisional","rows":1},"garak_kat_corp":{"value_origin":"person_provided","verification":"confirmed","rows":115},"garak_kat_std":{"value_origin":"person_provided","verification":"confirmed","rows":4},"kamis_bulk":{"value_origin":"model_estimated","verification":"provisional","rows":1},"kamis_sales":{"value_origin":"model_estimated","verification":"provisional","rows":1},"kamis_wholesale":{"value_origin":"model_estimated","verification":"provisional","rows":1},"usda_mars":{"value_origin":"model_estimated","verification":"provisional","rows":1}},"scope":"품목 수준 해석만 — 로트·거래 대응은 이 응답에 없다(로트 식별은 POST /api/v1/lots/reconcile 에 식별자로)"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"q":"토마토"},"x-example-path":"/api/v1/items/resolve"}},"/api/v1/items/{item_id}":{"get":{"tags":["표준 품목"],"summary":"표준 품목 하나 — 소스별 식별자·확정 여부·포장 kg 근거(가격 없음)","operationId":"items_get","parameters":[{"name":"item_id","in":"path","required":true,"schema":{"type":"string","title":"Item Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"canonical_item_id":{"type":"string"},"category":{"type":"string"},"use_class":{"type":"string"},"name_ko":{"type":"string"},"name_en":{"type":"string"},"name_ja":{"type":"null"},"name_zh":{"type":"null"},"aliases":{"type":"array","items":{"type":"string"}},"description":{"type":"string"},"mapping":{"type":"object","properties":{"overall":{"type":"string"},"by_source":{"type":"object"},"n_sources_confirmed":{"type":"integer"}}},"sources":{"type":"array","items":{"type":"object"}},"sources_by_jurisdiction":{"type":"object","properties":{"US":{"type":"integer"},"KR":{"type":"integer"}}},"units":{"type":"array","items":{"type":"object"}}}},"example":{"canonical_item_id":"tomato","category":"vegetable","use_class":"fresh","name_ko":"토마토","name_en":"Tomato","name_ja":null,"name_zh":null,"aliases":["완숙토마토","tomatoes"],"description":"Round (slicing) tomato; cherry, grape and plum types are separate items in both countries.","mapping":{"overall":"confirmed","by_source":{"fda_ftl":"provisional","garak_kat":"provisional","garak_kat_corp":"confirmed","garak_kat_std":"confirmed","kamis_bulk":"provisional","kamis_sales":"provisional","kamis_wholesale":"provisional","usda_mars":"provisional"},"n_sources_confirmed":2},"sources":[{"source":"fda_ftl","source_label":"FDA 식품 추적 대상 목록(FSMA 204) 범주","jurisdiction":"US","code":"tomatoes_fresh","name":"Tomatoes (fresh)","variety_raw":null,"package_raw":null,"mapping_confidence":"provisional","human_confirmed":false,"decided_by_human":false,"notes":"FDA 범주 'Tomatoes (fresh)' 는 모든 신선 토마토 품종 — 우리 tomato(원형)는 그 부분집합. 방울·그레이프·플럼 토마토도 FDA 대상이지만 아직 대응 표준 품목이 없다(1:다)."},{"source":"garak_kat","source_label":"경락 원천 대/중분류","jurisdiction":"KR","code":"08/03","name":"토마토","variety_raw":null,"package_raw":null,"mapping_confidence":"provisional","human_confirmed":false,"decided_by_human":false,"notes":null}],"sources_by_jurisdiction":{"US":2,"KR":125},"units":[{"source":"kamis_bulk","package_raw":"kg","kg_per_package":1.0,"conversion_basis":"source_spec","reason":null},{"source":"kamis_sales","package_raw":"5kg","kg_per_package":5.0,"conversion_basis":"source_spec","reason":null}]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-path":"/api/v1/items/tomato"}},"/api/v1/lots/reconcile":{"post":{"tags":["표준 품목"],"summary":"식별자 정합 — 여러 체계·주체의 품목 코드/로트 코드가 같은 품목·같은 로트를 가리키는지(추론 없음·가격 없음)","operationId":"lots_reconcile","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ReconcileRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"summary":{"type":"object","properties":{"requested":{"type":"integer"},"matched":{"type":"integer"},"unmatched":{"type":"integer"}}},"results":{"type":"array","items":{"type":"object"}},"groups":{"type":"object","properties":{"same_lot":{"type":"array","items":{}},"same_item":{"type":"array","items":{"type":"object"}}}},"rules":{"type":"array","items":{"type":"string"}}}},"example":{"summary":{"requested":2,"matched":2,"unmatched":0},"results":[{"ref":null,"kind":"item","jurisdiction":"KR","matched":true,"level":"item","canonical_item_id":"tomato","identifier":{"source":"garak_kat_std","source_label":"경락 공공 표준 품목분류 대/중/소","jurisdiction":"KR","code":"08/03/01","name":"토마토/토마토(일반)","variety_raw":"토마토(일반)","package_raw":null,"mapping_confidence":"confirmed","human_confirmed":true,"decided_by_human":true,"notes":"대표 검수 2026-09-16: 경락 표준 소분류 01 토마토(일반) → tomato 확정"},"equivalent_item_identifiers":{"same_jurisdiction":[{"source":"garak_kat_corp","source_label":"도매법인 자체 품목코드(법인코드:법인품목코드)","jurisdiction":"KR","code":"11000101:20301","name":"서울청과㈜ · 토마토/토마토","variety_raw":"토마토","package_raw":null,"mapping_confidence":"confirmed","human_confirmed":true,"decided_by_human":true,"notes":"대표 확정 2026-09-17(검수 목록 권고대로 383건 일괄) — tomato | 근거: 법인 코드가 적재된 로트 전체에서 표준 소분류 ['08/03/01'] 로 쓰였고 모두 같은 표준 품목(재계산)"},{"source":"garak_kat_corp","source_label":"도매법인 자체 품목코드(법인코드:법인품목코드)","jurisdiction":"KR","code":"11000101:20314","name":"서울청과㈜ · 토마토/찰토마토","variety_raw":"찰토마토","package_raw":null,"mapping_confidence":"confirmed","human_confirmed":true,"decided_by_human":true,"notes":"대표 확정 2026-09-17(검수 목록 권고대로 383건 일괄) — tomato | 근거: 법인 코드가 적재된 로트 전체에서 표준 소분류 ['08/03/04'] 로 쓰였고 모두 같은 표준 품목(재계산)"}],"other_jurisdictions":[{"source":"fda_ftl","source_label":"FDA 식품 추적 대상 목록(FSMA 204) 범주","jurisdiction":"US","code":"tomatoes_fresh","name":"Tomatoes (fresh)","variety_raw":null,"package_raw":null,"mapping_confidence":"provisional","human_confirmed":false,"decided_by_human":false,"notes":"FDA 범주 'Tomatoes (fresh)' 는 모든 신선 토마토 품종 — 우리 tomato(원형)는 그 부분집합. 방울·그레이프·플럼 토마토도 FDA 대상이지만 아직 대응 표준 품목이 없다(1:다)."},{"source":"usda_mars","source_label":"USDA AMS MARS 뉴욕 터미널 품목","jurisdiction":"US","code":"Tomatoes","name":"Tomatoes","variety_raw":null,"package_raw":null,"mapping_confidence":"provisional","human_confirmed":false,"decided_by_human":false,"notes":"뉴욕 터미널 NX_FV020. round 계열만. Cherry·Grape Type·Plum Type 은 별도 commodity 라 매핑하지 않음"}]},"note":"국가 간 동일성은 표준 품목 수준까지만이다 — 로트 수준으로 잇지 않는다."},{"ref":null,"kind":"item","jurisdiction":"US","matched":true,"level":"item","canonical_item_id":"tomato","identifier":{"source":"fda_ftl","source_label":"FDA 식품 추적 대상 목록(FSMA 204) 범주","jurisdiction":"US","code":"tomatoes_fresh","name":"Tomatoes (fresh)","variety_raw":null,"package_raw":null,"mapping_confidence":"provisional","human_confirmed":false,"decided_by_human":false,"notes":"FDA 범주 'Tomatoes (fresh)' 는 모든 신선 토마토 품종 — 우리 tomato(원형)는 그 부분집합. 방울·그레이프·플럼 토마토도 FDA 대상이지만 아직 대응 표준 품목이 없다(1:다)."},"equivalent_item_identifiers":{"same_jurisdiction":[{"source":"usda_mars","source_label":"USDA AMS MARS 뉴욕 터미널 품목","jurisdiction":"US","code":"Tomatoes","name":"Tomatoes","variety_raw":null,"package_raw":null,"mapping_confidence":"provisional","human_confirmed":false,"decided_by_human":false,"notes":"뉴욕 터미널 NX_FV020. round 계열만. Cherry·Grape Type·Plum Type 은 별도 commodity 라 매핑하지 않음"}],"other_jurisdictions":[{"source":"garak_kat_corp","source_label":"도매법인 자체 품목코드(법인코드:법인품목코드)","jurisdiction":"KR","code":"11000101:20301","name":"서울청과㈜ · 토마토/토마토","variety_raw":"토마토","package_raw":null,"mapping_confidence":"confirmed","human_confirmed":true,"decided_by_human":true,"notes":"대표 확정 2026-09-17(검수 목록 권고대로 383건 일괄) — tomato | 근거: 법인 코드가 적재된 로트 전체에서 표준 소분류 ['08/03/01'] 로 쓰였고 모두 같은 표준 품목(재계산)"},{"source":"garak_kat_corp","source_label":"도매법인 자체 품목코드(법인코드:법인품목코드)","jurisdiction":"KR","code":"11000101:20314","name":"서울청과㈜ · 토마토/찰토마토","variety_raw":"찰토마토","package_raw":null,"mapping_confidence":"confirmed","human_confirmed":true,"decided_by_human":true,"notes":"대표 확정 2026-09-17(검수 목록 권고대로 383건 일괄) — tomato | 근거: 법인 코드가 적재된 로트 전체에서 표준 소분류 ['08/03/04'] 로 쓰였고 모두 같은 표준 품목(재계산)"}]},"note":"국가 간 동일성은 표준 품목 수준까지만이다 — 로트 수준으로 잇지 않는다."}],"groups":{"same_lot":[],"same_item":[{"canonical_item_id":"tomato","indexes":[0,1],"jurisdictions":["KR","US"]}]},"rules":["추론으로 짝짓지 않는다 — 없으면 matched:false","로트 동일성은 같은 관할국 안에서만"]}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"parameters":[],"x-example-body":{"identifiers":[{"kind":"item","jurisdiction":"KR","source":"garak_kat_std","code":"08/03/01"},{"kind":"item","jurisdiction":"US","source":"fda_ftl","code":"tomatoes_fresh"}]}}},"/api/events/tracker":{"get":{"tags":["이벤트"],"summary":"Events Tracker","operationId":"events_tracker","parameters":[{"name":"days","in":"query","required":false,"schema":{"type":"integer","maximum":120,"minimum":7,"description":"앞으로 며칠","default":45,"title":"Days"},"description":"앞으로 며칠"},{"name":"past","in":"query","required":false,"schema":{"type":"integer","maximum":30,"minimum":0,"description":"지난 며칠(기상 관측·끝난 이벤트)","default":7,"title":"Past"},"description":"지난 며칠(기상 관측·끝난 이벤트)"},{"name":"macro","in":"query","required":false,"schema":{"type":"boolean","description":"거시 지표 큰 변동 사건(macro_events)도 함께","default":false,"title":"Macro"},"description":"거시 지표 큰 변동 사건(macro_events)도 함께"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"today":{"type":"string"},"window":{"type":"object","properties":{"days":{"type":"integer"},"past":{"type":"integer"}}},"event_count":{"type":"integer"},"counts_by_type":{"type":"object","properties":{"weather_warning":{"type":"integer"},"season":{"type":"integer"},"biosecurity":{"type":"integer"},"weather_season":{"type":"integer"},"festival":{"type":"integer"},"policy":{"type":"integer"}}},"type_labels":{"type":"object","properties":{"festival":{"type":"string"},"school":{"type":"string"},"demand":{"type":"string"},"season":{"type":"string"},"weather_season":{"type":"string"},"biosecurity":{"type":"string"},"policy":{"type":"string"},"trade":{"type":"string"},"disaster":{"type":"string"},"logistics":{"type":"string"},"weather":{"type":"string"},"other":{"type":"string"},"weather_warning":{"type":"string"}}},"headline":{"type":"object","properties":{"id":{"type":"string"},"layer":{"type":"string"},"type":{"type":"string"},"type_label":{"type":"string"},"title":{"type":"string"},"date":{"type":"string"},"date_end":{"type":"string"},"approx":{"type":"boolean"},"d_day":{"type":"integer"},"status":{"type":"string"},"items":{"type":"array","items":{"type":"string"}},"note":{"type":"string"},"basis":{"type":"string"},"source":{"type":"null"},"signals":{"type":"array","items":{"type":"object"}}}},"events":{"type":"array","items":{"type":"object"}},"disclaimer":{"type":"string"}}},"example":{"ok":true,"today":"2026-10-01","window":{"days":45,"past":7},"event_count":14,"counts_by_type":{"weather_warning":1,"season":7,"biosecurity":1,"weather_season":2,"festival":2,"policy":1},"type_labels":{"festival":"명절","school":"급식","demand":"수요","season":"출하기","weather_season":"기상철","biosecurity":"방역","policy":"정책","trade":"수입·수출","disaster":"재해","logistics":"물류","weather":"기상관측","other":"기타","weather_warning":"기상특보"},"headline":{"id":"festival:kimjang:2026-11-01","layer":"festival","type":"festival","type_label":"명절","title":"김장철","date":"2026-11-01","date_end":"2026-12-15","approx":false,"d_day":31,"status":"upcoming","items":["배추","무"],"note":"김장 수요가 집중되는 기간입니다(11/1~12/15). 배추·무는 수요가 늘어도 가을 출하가 겹쳐 값이 내린 해가 많았습니다.","basis":"고정 기간 · 27년 실측","source":null,"signals":[{"item":"생고추","signal":null,"consistency":89,"strength":"강"},{"item":"배추","signal":null,"consistency":100,"strength":"강"}]},"events":[{"id":"warning:강풍주의보:202610010700","layer":"warning","type":"weather_warning","type_label":"기상특보","title":"강풍주의보 발효 중","date":"2026-10-01","date_end":null,"approx":false,"d_day":0,"status":"ongoing","items":["포도","사과"],"regions":["경북"],"note":"울릉도.독도. 기상청 특보 현황(10월 1일 07:00 발표) 그대로입니다. 이 지역에서 최근 2주 출하된 품목: 포도·사과·양파·배.","basis":"기상청 특보","source":{"name":"기상청 날씨누리 특보 현황","url":"https://www.weather.go.kr/w/special-report/overall.do"}},{"id":"calendar:sweetpotato_new:2026-08-15","layer":"calendar","type":"season","type_label":"출하기","title":"햇고구마 출하기","date":"2026-08-15","date_end":"2026-10-15","approx":false,"d_day":0,"status":"ongoing","items":["고구마"],"note":"햇고구마가 나오는 기간입니다.","basis":"관례(매년 이 무렵)","source":null}],"disclaimer":"일정·관례·공표·관측 사실을 시간순으로 모아 보여드립니다. 가격이 오르거나 내린다고 예측한 것이 아닙니다 — 품목 옆 방향은 과거 관례이며, 판단은 시세와 함께 봐주세요."}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"days":"45","past":"7"},"x-example-path":"/api/events/tracker"}},"/api/events/types":{"get":{"tags":["이벤트"],"summary":"Events Types","operationId":"events_types","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"types":{"type":"object","properties":{"festival":{"type":"string"},"school":{"type":"string"},"demand":{"type":"string"},"season":{"type":"string"},"weather_season":{"type":"string"},"biosecurity":{"type":"string"},"policy":{"type":"string"},"trade":{"type":"string"},"disaster":{"type":"string"},"logistics":{"type":"string"},"weather":{"type":"string"},"other":{"type":"string"},"weather_warning":{"type":"string"}}},"manual_types":{"type":"array","items":{"type":"string"}}}},"example":{"types":{"festival":"명절","school":"급식","demand":"수요","season":"출하기","weather_season":"기상철","biosecurity":"방역","policy":"정책","trade":"수입·수출","disaster":"재해","logistics":"물류","weather":"기상관측","other":"기타","weather_warning":"기상특보"},"manual_types":["policy","biosecurity"]}}}}},"parameters":[],"x-example-path":"/api/events/types"}},"/api/external/events/upcoming":{"get":{"tags":["이벤트"],"summary":"다가오는 명절·김장 이벤트 (D-14 경보) + 영향 품목","description":"오늘 기준 향후 horizon_days(기본 14일=D-14 경보) 내 도래하는 명절(설날·추석)과 김장철(11/1~12/15) 이벤트, 그리고 27년 실측 기반 영향 품목 신호를 반환한다.\n\n각 품목 신호는 두 가지로 분리된다:\n- price: 명절/김장 가격급등 → 선매입(발주 권고 제안) 대상\n- demand: 수요폭증인데 가격하락(공급폭증) → '매수 적기' 플래그\n\n강도(강/중/약)와 일관성(consistency %)을 함께 노출한다.","operationId":"get_events_upcoming_api_external_events_upcoming_get","parameters":[{"name":"horizon_days","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"description":"조회 범위 일수 (기본 14=D-14 경보 윈도우, 최대 200=장기 카운트다운)","default":14,"title":"Horizon Days"},"description":"조회 범위 일수 (기본 14=D-14 경보 윈도우, 최대 200=장기 카운트다운)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"today":{"type":"string"},"horizon_days":{"type":"integer"},"event_count":{"type":"integer"},"events":{"type":"array","items":{"type":"object"}},"warnings":{"type":"null"}},"title":"Response Get Events Upcoming Api External Events Upcoming Get"},"example":{"today":"2026-10-01","horizon_days":200,"event_count":1,"events":[{"event_name":"설날","date":"2027-02-06","d_day":128,"alert":"예정","items":[{"item":"오이","signal_type":"price","strength":"강","chg_pct":25.0,"consistency":90,"recommend":"선매입 검토 (가격 급등 예상, 강도 강)"},{"item":"호박","signal_type":"price","strength":"강","chg_pct":25.0,"consistency":90,"recommend":"선매입 검토 (가격 급등 예상, 강도 강)"}]}],"warnings":null}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"horizon_days":"200"},"x-example-path":"/api/external/events/upcoming"}},"/api/external/events/item-signal":{"get":{"tags":["이벤트"],"summary":"품목별 명절·김장 신호 + 강도·일관성 + 발주 권고 제안","description":"특정 품목의 명절·김장 이벤트 신호를 반환한다. signal_type=price(가격급등 선매입) 또는 demand(가격하락 매수적기).\n\norder_plan_suggestion 은 방식 A '제안형' — 기존 suggest_order_plan (POST /api/predictive-orders/suggest-trigger) 호출용 payload 를 생성만 하며, AI 는 발주를 실행하지 않는다(사람 승인 게이트, 특허 정합).","operationId":"get_events_item_signal_api_external_events_item_signal_get","parameters":[{"name":"item","in":"query","required":true,"schema":{"type":"string","description":"품목 한글명. 예: 사과, 대파, 배추, 생고추","title":"Item"},"description":"품목 한글명. 예: 사과, 대파, 배추, 생고추"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"item":{"type":"string"},"has_signal":{"type":"boolean"},"signal_type":{"type":"string"},"signal_type_description":{"type":"string"},"events":{"type":"object","properties":{"김장":{"type":"object"}}},"order_plan_suggestion":{"type":"object","properties":{"type":{"type":"string"},"requires_human_approval":{"type":"boolean"},"ai_permission_gate":{"type":"string"},"action":{"type":"string"},"method":{"type":"string"},"endpoint":{"type":"string"},"request_body":{"type":"object"},"request_body_note":{"type":"string"},"rationale_korean":{"type":"string"}}}},"title":"Response Get Events Item Signal Api External Events Item Signal Get"},"example":{"item":"배추","has_signal":true,"signal_type":"demand","signal_type_description":"demand = 수요폭증인데 가격하락(공급폭증) — 매수 적기 플래그","events":{"김장":{"chg_pct":-40.7,"consistency":100,"strength":"강","recommend":"매수 적기 (수요폭증·가격하락, 강도 강)","note":"수요폭증+가격하락=매수적기"}},"order_plan_suggestion":{"type":"proposal","requires_human_approval":true,"ai_permission_gate":"제안형(방식 A) — AI는 발주 실행 권한 없음, 사람 승인 필수","action":"suggest_order_plan","method":"POST","endpoint":"/api/predictive-orders/suggest-trigger","request_body":{"item_code":"배추","current_stock":null,"stock_unit":null,"target_margin_pct":25.0},"request_body_note":"current_stock 은 운영자가 자기 재고를 입력해야 함 (필수, 미입력 시 실행 불가).","rationale_korean":"김장 수요폭증·가격하락(실측 -40.7%) → 매수 적기. 재고 입력 후 발주 권고 산출 검토."}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"item":"배추"},"x-example-path":"/api/external/events/item-signal"}},"/api/usda/catalog":{"get":{"tags":["미국 시세(USDA)"],"summary":"USDA 뉴욕 터미널 리포트 목록과 수록 구간","description":"팜템포가 재배포 승인을 받아 보유한 USDA AMS Market News 리포트 3종과, 품목별 수록 구간.","operationId":"usda_catalog","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"type":"object","properties":{"text":{"type":"string"},"source":{"type":"string"},"program":{"type":"string"},"site":{"type":"string"},"reuse_confirmed_on":{"type":"string"},"notice":{"type":"string"}}},"as_of":{"type":"string"},"stale_days":{"type":"integer"},"reports":{"type":"array","items":{"type":"object"}},"coverage":{"type":"object","properties":{"first_report_date":{"type":"string"},"last_report_date":{"type":"string"},"rows":{"type":"integer"},"stale_days":{"type":"integer"}}}}},"example":{"attribution":{"text":"Source: USDA AMS Market News","source":"USDA AMS Market News","program":"Specialty Crops Market News Division, USDA Agricultural Marketing Service","site":"https://mymarketnews.ams.usda.gov/","reuse_confirmed_on":"2026-09-29","notice":"Quoted price ranges are reproduced exactly as published by USDA AMS Market News. FarmTempo does not modify, average or convert the reported values. USDA does not endorse FarmTempo."},"as_of":"2026-09-30","stale_days":1,"reports":[{"slug":"AJ_FV010","slug_id":2277,"title":"Atlanta Terminal Market Fruit Prices","city":"Atlanta","market":"AJ","market_type":"Terminal","commodities":[{"commodity":"Apples","rows":4494,"first_report_date":"2026-07-01","last_report_date":"2026-09-30"},{"commodity":"Apple Pears","rows":643,"first_report_date":"2025-11-06","last_report_date":"2026-09-30"}]},{"slug":"AJ_FV020","slug_id":2278,"title":"Atlanta Terminal Market Vegetables Prices","city":"Atlanta","market":"AJ","market_type":"Terminal","commodities":[{"commodity":"Tomatoes","rows":3255,"first_report_date":"2026-07-01","last_report_date":"2026-09-30"},{"commodity":"Chinese Cabbage","rows":302,"first_report_date":"2026-07-01","last_report_date":"2026-09-30"}]}],"coverage":{"first_report_date":"1998-01-23","last_report_date":"2026-09-30","rows":265176,"stale_days":1}}}}}},"parameters":[],"x-example-path":"/api/usda/catalog"}},"/api/usda/prices":{"get":{"tags":["미국 시세(USDA)"],"summary":"USDA 터미널시장 가격 구간(11개 도시·원값)","description":"보고된 대로의 터미널시장 가격 구간 — 그날 아침 도매시장 첫 수취인(도매업자)의 판매가(USDA 조사). 값은 변형하지 않으며, 행마다 리포트 번호와 리포트 날짜가 붙는다.","operationId":"usda_prices","parameters":[{"name":"commodity","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"승인 범위: Apple Pears, Apples, Chinese Cabbage, Onions, Dry, Potatoes, Tomatoes","title":"Commodity"},"description":"승인 범위: Apple Pears, Apples, Chinese Cabbage, Onions, Dry, Potatoes, Tomatoes"},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"터미널 시장 접두어: AJ, AS, BH, BP, CA, DU, HC, HX, MH, NA, NX","title":"Market"},"description":"터미널 시장 접두어: AJ, AS, BH, BP, CA, DU, HC, HX, MH, NA, NX"},{"name":"origin","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"description":"원산 — 발표된 표기 그대로 정확히 일치 (예: South Korea). 최신 날짜도 이 원산 안에서 잡는다","title":"Origin"},"description":"원산 — 발표된 표기 그대로 정확히 일치 (예: South Korea). 최신 날짜도 이 원산 안에서 잡는다"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"From"}},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"To"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":200,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"type":"object","properties":{"text":{"type":"string"},"source":{"type":"string"},"program":{"type":"string"},"site":{"type":"string"},"reuse_confirmed_on":{"type":"string"},"notice":{"type":"string"}}},"as_of":{"type":"string"},"stale_days":{"type":"integer"},"count":{"type":"integer"},"rows":{"type":"array","items":{"type":"object"}},"query":{"type":"object","properties":{"commodity":{"type":"string"},"market":{"type":"null"},"origin":{"type":"null"},"from":{"type":"string"},"to":{"type":"null"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}},"example":{"attribution":{"text":"Source: USDA AMS Market News","source":"USDA AMS Market News","program":"Specialty Crops Market News Division, USDA Agricultural Marketing Service","site":"https://mymarketnews.ams.usda.gov/","reuse_confirmed_on":"2026-09-29","notice":"Quoted price ranges are reproduced exactly as published by USDA AMS Market News. FarmTempo does not modify, average or convert the reported values. USDA does not endorse FarmTempo."},"as_of":"2026-09-30","stale_days":1,"count":2,"rows":[{"report":{"slug":"AJ_FV020","slug_id":2278,"title":"Atlanta Terminal Market Vegetables Prices","city":"Atlanta","market":"AJ","market_type":"Terminal"},"report_date":"2026-09-30","commodity":"Tomatoes","market":"Atlanta Terminal Market","origin":"North Carolina","variety":"MATURE GREENS","grade":"85% U.S. One or Better","package":"25 lb cartons loose","unit":"USD per package","currency":"USD","price_basis":"quoted_range","price_low":25.0,"price_high":28.0,"price_point":null,"attributes":{"item_size":"5x6 size","market_type":"Terminal","organic":"N","properties":"Light Red-red"},"attribution":"Source: USDA AMS Market News"},{"report":{"slug":"AJ_FV020","slug_id":2278,"title":"Atlanta Terminal Market Vegetables Prices","city":"Atlanta","market":"AJ","market_type":"Terminal"},"report_date":"2026-09-30","commodity":"Tomatoes","market":"Atlanta Terminal Market","origin":null,"variety":"MATURE GREENS","grade":"U.S. Combination","package":"25 lb cartons loose","unit":"USD per package","currency":"USD","price_basis":"quoted_range","price_low":24.0,"price_high":25.0,"price_point":null,"attributes":{"item_size":"6x6 size","market_type":"Terminal","organic":"N","properties":"Light Red","repack":"Local"},"attribution":"Source: USDA AMS Market News"}],"query":{"commodity":"Tomatoes","market":null,"origin":null,"from":"2026-08-31","to":null,"limit":2,"offset":0}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"commodity":"Tomatoes","limit":"2"},"x-example-path":"/api/usda/prices"}},"/api/usda/latest":{"get":{"tags":["미국 시세(USDA)"],"summary":"USDA 터미널 — 시장·품목별 최신 리포트","description":"**시장·품목마다** 가장 최근 리포트 날짜의 행만.\n\n⛔ 최신 날짜는 시장마다·품목마다 다르다. 한 날짜로 뭉뚱그리지 말고 행마다 report_date 를 읽을 것.\n⛔ 도시끼리 합치거나 평균 내지 않는다 — 각자의 시장이다.","operationId":"usda_latest","parameters":[{"name":"commodity","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"승인 범위: Apple Pears, Apples, Chinese Cabbage, Onions, Dry, Potatoes, Tomatoes","title":"Commodity"},"description":"승인 범위: Apple Pears, Apples, Chinese Cabbage, Onions, Dry, Potatoes, Tomatoes"},{"name":"market","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"터미널 시장 접두어: AJ, AS, BH, BP, CA, DU, HC, HX, MH, NA, NX","title":"Market"},"description":"터미널 시장 접두어: AJ, AS, BH, BP, CA, DU, HC, HX, MH, NA, NX"},{"name":"origin","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}],"description":"원산 — 발표된 표기 그대로 정확히 일치 (예: South Korea). 최신 날짜도 이 원산 안에서 잡는다","title":"Origin"},"description":"원산 — 발표된 표기 그대로 정확히 일치 (예: South Korea). 최신 날짜도 이 원산 안에서 잡는다"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"시장×품목 한 조합당 행 수","default":4,"title":"Limit"},"description":"시장×품목 한 조합당 행 수"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"type":"object","properties":{"text":{"type":"string"},"source":{"type":"string"},"program":{"type":"string"},"site":{"type":"string"},"reuse_confirmed_on":{"type":"string"},"notice":{"type":"string"}}},"as_of":{"type":"string"},"stale_days":{"type":"integer"},"count":{"type":"integer"},"rows":{"type":"array","items":{"type":"object"}},"query":{"type":"object","properties":{"commodity":{"type":"string"},"market":{"type":"null"},"origin":{"type":"null"},"limit":{"type":"integer"}}}}},"example":{"attribution":{"text":"Source: USDA AMS Market News","source":"USDA AMS Market News","program":"Specialty Crops Market News Division, USDA Agricultural Marketing Service","site":"https://mymarketnews.ams.usda.gov/","reuse_confirmed_on":"2026-09-29","notice":"Quoted price ranges are reproduced exactly as published by USDA AMS Market News. FarmTempo does not modify, average or convert the reported values. USDA does not endorse FarmTempo."},"as_of":"2026-09-30","stale_days":1,"count":17,"rows":[{"report":{"slug":"AJ_FV010","slug_id":2277,"title":"Atlanta Terminal Market Fruit Prices","city":"Atlanta","market":"AJ","market_type":"Terminal"},"report_date":"2026-09-30","commodity":"Apple Pears","market":"Atlanta Terminal Market","origin":"Chile","variety":"HOSUI","grade":null,"package":"cartons 2 layer","unit":"USD per package","currency":"USD","price_basis":"quoted_range","price_low":23.0,"price_high":23.0,"price_point":null,"attributes":{"item_size":"66s","market_type":"Terminal","organic":"N","reporter_comment":"occasional higher/lower"},"attribution":"Source: USDA AMS Market News"},{"report":{"slug":"AJ_FV010","slug_id":2277,"title":"Atlanta Terminal Market Fruit Prices","city":"Atlanta","market":"AJ","market_type":"Terminal"},"report_date":"2026-09-30","commodity":"Apple Pears","market":"Atlanta Terminal Market","origin":"Chile","variety":"VARIETY NOT MARKED","grade":null,"package":"cartons 1 layer","unit":"USD per package","currency":"USD","price_basis":"quoted_range","price_low":33.0,"price_high":34.0,"price_point":null,"attributes":{"item_size":"16s","market_type":"Terminal","organic":"N","reporter_comment":"occasional higher/lower"},"attribution":"Source: USDA AMS Market News"}],"query":{"commodity":"Apple Pears","market":null,"origin":null,"limit":2}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"commodity":"Apple Pears","limit":"2"},"x-example-path":"/api/usda/latest"}},"/api/usda/movement":{"get":{"tags":["미국 반입 물량(USDA)"],"summary":"USDA 반입 물량 — 보고된 행 그대로","description":"보고된 대로의 반입 행. 값은 변형하지 않으며, 행마다 리포트 번호와 리포트 날짜가 붙는다.","operationId":"usda_movement","parameters":[{"name":"commodity","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Commodity"}},{"name":"origin","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"원산 — 국가(수입) 또는 미국 주","title":"Origin"},"description":"원산 — 국가(수입) 또는 미국 주"},{"name":"entry_point","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"입항지·통과지 원문","title":"Entry Point"},"description":"입항지·통과지 원문"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"From"}},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"To"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":200,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"type":"object","properties":{"text":{"type":"string"},"source":{"type":"string"},"program":{"type":"string"},"site":{"type":"string"},"reuse_confirmed_on":{"type":"string"},"notice":{"type":"string"}}},"basis":{"type":"object","properties":{"what":{"type":"string"},"not":{"type":"string"},"unit":{"type":"string"}}},"as_of":{"type":"string"},"stale_days":{"type":"integer"},"count":{"type":"integer"},"rows":{"type":"array","items":{"type":"object"}},"query":{"type":"object","properties":{"commodity":{"type":"null"},"origin":{"type":"string"},"entry_point":{"type":"null"},"from":{"type":"string"},"to":{"type":"null"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}},"example":{"attribution":{"text":"Source: USDA AMS Market News","source":"USDA AMS Market News","program":"Specialty Crops Market News Division, USDA Agricultural Marketing Service","site":"https://mymarketnews.ams.usda.gov/","reuse_confirmed_on":"2026-09-29","notice":"Arrival volumes are reproduced exactly as published by USDA AMS Market News. FarmTempo does not modify or convert the reported values. USDA does not endorse FarmTempo."},"basis":{"what":"Arrivals reported at US terminal markets and ports of entry.","not":"Not sales, not shipments, and not a transaction-level record.","unit":"Volumes are reported in pounds (lb) and are shown unchanged."},"as_of":"2026-09-30","stale_days":1,"count":2,"rows":[{"report":{"slug":"WA_FV170","slug_id":3283,"title":"WASHINGTON, DC TRUCK, AIR AND BOAT Daily Movement Report","covers":"national imports (titled Washington, DC)"},"report_date":"2026-09-30","period":{"start":"2026-09-29","end":"2026-09-29"},"commodity":"Grapes","variety":null,"origin":"South Korea","entry_point":"IMPORTS THROUGH LOS ANGELES-LONG BEACH CALIFORNIA","transport_mode":"Boat","trade_flow":"I (import)","package":null,"package_count":null,"volume":{"lb":108240.0,"season_to_date_10klb":30.0},"organic":"No","attribution":"Source: USDA AMS Market News"},{"report":{"slug":"WA_FV170","slug_id":3283,"title":"WASHINGTON, DC TRUCK, AIR AND BOAT Daily Movement Report","covers":"national imports (titled Washington, DC)"},"report_date":"2026-09-30","period":{"start":"2026-09-29","end":"2026-09-29"},"commodity":"Chestnuts","variety":null,"origin":"South Korea","entry_point":"IMPORTS THROUGH LOS ANGELES AIRPORT CALIFORNIA","transport_mode":"Air","trade_flow":"I (import)","package":null,"package_count":null,"volume":{"lb":6930.0,"season_to_date_10klb":2.0},"organic":"No","attribution":"Source: USDA AMS Market News"}],"query":{"commodity":null,"origin":"South Korea","entry_point":null,"from":"2026-09-16","to":null,"limit":2,"offset":0}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"origin":"South Korea","limit":"2"},"x-example-path":"/api/usda/movement"}},"/api/usda/movement/catalog":{"get":{"tags":["미국 반입 물량(USDA)"],"summary":"USDA 반입 물량 리포트 목록과 수록 구간","description":"팜템포가 재배포 승인을 받아 보유한 USDA 반입 물량 리포트와, 리포트별 수록 구간.","operationId":"usda_movement_catalog","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"type":"object","properties":{"text":{"type":"string"},"source":{"type":"string"},"program":{"type":"string"},"site":{"type":"string"},"reuse_confirmed_on":{"type":"string"},"notice":{"type":"string"}}},"basis":{"type":"object","properties":{"what":{"type":"string"},"not":{"type":"string"},"unit":{"type":"string"}}},"as_of":{"type":"string"},"stale_days":{"type":"integer"},"reports":{"type":"array","items":{"type":"object"}},"coverage":{"type":"object","properties":{"first_report_date":{"type":"string"},"last_report_date":{"type":"string"},"rows":{"type":"integer"},"stale_days":{"type":"integer"}}}}},"example":{"attribution":{"text":"Source: USDA AMS Market News","source":"USDA AMS Market News","program":"Specialty Crops Market News Division, USDA Agricultural Marketing Service","site":"https://mymarketnews.ams.usda.gov/","reuse_confirmed_on":"2026-09-29","notice":"Arrival volumes are reproduced exactly as published by USDA AMS Market News. FarmTempo does not modify or convert the reported values. USDA does not endorse FarmTempo."},"basis":{"what":"Arrivals reported at US terminal markets and ports of entry.","not":"Not sales, not shipments, and not a transaction-level record.","unit":"Volumes are reported in pounds (lb) and are shown unchanged."},"as_of":"2026-09-30","stale_days":1,"reports":[{"slug":"BR_FV170","slug_id":2768,"title":"BENTON HARBOR, MI TRUCK AIR, AND BOAT Daily Movement Report","covers":"Benton Harbor, MI","rows":1023,"first_report_date":"2026-07-02","last_report_date":"2026-09-30"},{"slug":"CA_FV170","slug_id":2793,"title":"COLUMBIA, SC TRUCK AIR, AND BOAT Daily Movement Report","covers":"Columbia, SC","rows":47,"first_report_date":"2026-07-14","last_report_date":"2026-09-22"}],"coverage":{"first_report_date":"2026-07-02","last_report_date":"2026-09-30","rows":91337,"stale_days":1}}}}}},"parameters":[],"x-example-path":"/api/usda/movement/catalog"}},"/api/usda/movement/summary":{"get":{"tags":["미국 반입 물량(USDA)"],"summary":"USDA 반입 물량 합계 — 팜템포가 더한 값","description":"선택한 행들의 파운드 합계.\n\n🔴 이 합계는 **USDA 가 발표한 수치가 아니라 팜템포가 더한 값**이다. 응답의 `computed` 가 그렇게 밝힌다.\n   단위는 파운드 그대로 — kg·톤으로 바꾸지 않는다.","operationId":"usda_movement_summary","parameters":[{"name":"group_by","in":"query","required":false,"schema":{"type":"string","description":"하나: origin, commodity, entry_point, transport_mode","default":"origin","title":"Group By"},"description":"하나: origin, commodity, entry_point, transport_mode"},{"name":"commodity","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Commodity"}},{"name":"origin","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Origin"}},{"name":"entry_point","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Entry Point"}},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"From"}},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"To"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":200,"minimum":1,"default":50,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"type":"object","properties":{"text":{"type":"string"},"source":{"type":"string"},"program":{"type":"string"},"site":{"type":"string"},"reuse_confirmed_on":{"type":"string"},"notice":{"type":"string"}}},"basis":{"type":"object","properties":{"what":{"type":"string"},"not":{"type":"string"},"unit":{"type":"string"}}},"as_of":{"type":"string"},"stale_days":{"type":"integer"},"group_by":{"type":"string"},"count":{"type":"integer"},"groups":{"type":"array","items":{"type":"object"}},"computed":{"type":"object","properties":{"by":{"type":"string"},"operation":{"type":"string"},"unit":{"type":"string"},"note":{"type":"string"}}},"query":{"type":"object","properties":{"commodity":{"type":"null"},"origin":{"type":"string"},"entry_point":{"type":"null"},"from":{"type":"string"},"to":{"type":"null"},"limit":{"type":"integer"}}}}},"example":{"attribution":{"text":"Source: USDA AMS Market News","source":"USDA AMS Market News","program":"Specialty Crops Market News Division, USDA Agricultural Marketing Service","site":"https://mymarketnews.ams.usda.gov/","reuse_confirmed_on":"2026-09-29","notice":"Arrival volumes are reproduced exactly as published by USDA AMS Market News. FarmTempo does not modify or convert the reported values. USDA does not endorse FarmTempo."},"basis":{"what":"Arrivals reported at US terminal markets and ports of entry.","not":"Not sales, not shipments, and not a transaction-level record.","unit":"Volumes are reported in pounds (lb) and are shown unchanged."},"as_of":"2026-09-30","stale_days":1,"group_by":"origin","count":1,"groups":[{"key":"South Korea","rows":38,"lb_total":1852627.0}],"computed":{"by":"FarmTempo","operation":"sum of the reported pound volumes over the matching rows","unit":"lb","note":"This total is calculated by FarmTempo from the rows published in the reports below. USDA does not publish this figure, and the values are not converted to other units."},"query":{"commodity":null,"origin":"South Korea","entry_point":null,"from":"2026-09-16","to":null,"limit":2}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"origin":"South Korea","limit":"2"},"x-example-path":"/api/usda/movement/summary"}},"/api/usda/shipping-point/catalog":{"get":{"tags":["미국 산지 가격(USDA)"],"summary":"USDA 산지 FOB 가격 리포트 목록과 수록 구간","description":"팜템포가 재배포 승인을 받아 보유한 USDA 산지(shipping point) 리포트와, 품목별 수록 구간.","operationId":"usda_sp_catalog","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"type":"object","properties":{"text":{"type":"string"},"source":{"type":"string"},"program":{"type":"string"},"site":{"type":"string"},"reuse_confirmed_on":{"type":"string"},"notice":{"type":"string"}}},"level":{"type":"object","properties":{"level":{"type":"string"},"what":{"type":"string"},"not":{"type":"string"}}},"as_of":{"type":"string"},"stale_days":{"type":"integer"},"reports":{"type":"array","items":{"type":"object"}},"coverage":{"type":"object","properties":{"first_report_date":{"type":"string"},"last_report_date":{"type":"string"},"rows":{"type":"integer"},"stale_days":{"type":"integer"}}}}},"example":{"attribution":{"text":"Source: USDA AMS Market News","source":"USDA AMS Market News","program":"Specialty Crops Market News Division, USDA Agricultural Marketing Service","site":"https://mymarketnews.ams.usda.gov/","reuse_confirmed_on":"2026-09-29","notice":"Quoted price ranges are reproduced exactly as published by USDA AMS Market News. FarmTempo does not modify, average or convert the reported values. USDA does not endorse FarmTempo."},"level":{"level":"shipping_point","what":"FOB prices at the shipping point: the price as produce leaves the growing area.","not":"Not terminal market prices. Shipping point and terminal prices are different levels of the trade; FarmTempo does not merge them or subtract one from the other."},"as_of":"2026-09-30","stale_days":1,"reports":[{"slug":"BR_FV110","slug_id":2386,"title":"Benton Harbor Shipping Point Fruit Prices","covers":"Benton Harbor, MI","commodities":[{"commodity":"Apples","rows":2306,"first_report_date":"2025-09-29","last_report_date":"2026-07-17"}]},{"slug":"IF_FV110","slug_id":2392,"title":"Idaho Falls Shipping Point Fruit Prices","covers":"Idaho Falls, ID","commodities":[{"commodity":"Apples","rows":2365,"first_report_date":"2025-09-29","last_report_date":"2026-09-30"}]}],"coverage":{"first_report_date":"2025-09-29","last_report_date":"2026-09-30","rows":59156,"stale_days":1}}}}}},"parameters":[],"x-example-path":"/api/usda/shipping-point/catalog"}},"/api/usda/shipping-point/latest":{"get":{"tags":["미국 산지 가격(USDA)"],"summary":"USDA 산지 FOB 가격 — 리포트·품목별 최신 리포트","description":"리포트·품목마다 가장 최근 리포트 날짜의 행만.\n\n⛔ 산지는 계절 따라 돈다 — 제철이 아닌 산지는 최신 날짜가 몇 달 전일 수 있다. 행마다 report_date 를 읽을 것.","operationId":"usda_sp_latest","parameters":[{"name":"commodity","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"승인 범위: Apples, Chinese Cabbage, Onions, Dry, Potatoes, Tomatoes","title":"Commodity"},"description":"승인 범위: Apples, Chinese Cabbage, Onions, Dry, Potatoes, Tomatoes"},{"name":"report","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"리포트: BR_FV110, IF_FV110, IF_FV130, IX_FV120, MB_FV110, OR_FV120, YA_FV110","title":"Report"},"description":"리포트: BR_FV110, IF_FV110, IF_FV130, IX_FV120, MB_FV110, OR_FV120, YA_FV110"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":50,"minimum":1,"description":"리포트×품목 한 조합당 행 수","default":4,"title":"Limit"},"description":"리포트×품목 한 조합당 행 수"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"type":"object","properties":{"text":{"type":"string"},"source":{"type":"string"},"program":{"type":"string"},"site":{"type":"string"},"reuse_confirmed_on":{"type":"string"},"notice":{"type":"string"}}},"level":{"type":"object","properties":{"level":{"type":"string"},"what":{"type":"string"},"not":{"type":"string"}}},"as_of":{"type":"string"},"stale_days":{"type":"integer"},"count":{"type":"integer"},"rows":{"type":"array","items":{"type":"object"}},"query":{"type":"object","properties":{"commodity":{"type":"null"},"report":{"type":"null"},"limit":{"type":"integer"}}}}},"example":{"attribution":{"text":"Source: USDA AMS Market News","source":"USDA AMS Market News","program":"Specialty Crops Market News Division, USDA Agricultural Marketing Service","site":"https://mymarketnews.ams.usda.gov/","reuse_confirmed_on":"2026-09-29","notice":"Quoted price ranges are reproduced exactly as published by USDA AMS Market News. FarmTempo does not modify, average or convert the reported values. USDA does not endorse FarmTempo."},"level":{"level":"shipping_point","what":"FOB prices at the shipping point: the price as produce leaves the growing area.","not":"Not terminal market prices. Shipping point and terminal prices are different levels of the trade; FarmTempo does not merge them or subtract one from the other."},"as_of":"2026-09-30","stale_days":1,"count":17,"rows":[{"level":"shipping_point","report":{"slug":"BR_FV110","slug_id":2386,"title":"Benton Harbor Shipping Point Fruit Prices","covers":"Benton Harbor, MI"},"report_date":"2026-07-17","commodity":"Apples","shipping_point":"Benton Harbor FOB SC","district":"MICHIGAN","variety":"FUJI","grade":"U.S. Extra Fancy","package":"cartons 12 3-lb film bags","unit":"USD per package (FOB shipping point)","currency":"USD","price_basis":"quoted_range","price_low":20.0,"price_high":25.95,"price_point":null,"attributes":{"basis_of_sale":"Sales F.O.B. Shipping Point and/or Delivered Sales, Shipping Point Basis","import_export_flag":"D (domestic)","item_size":"2 1/2\" minimum","organic":"N","season":"2025"},"attribution":"Source: USDA AMS Market News"},{"level":"shipping_point","report":{"slug":"BR_FV110","slug_id":2386,"title":"Benton Harbor Shipping Point Fruit Prices","covers":"Benton Harbor, MI"},"report_date":"2026-07-17","commodity":"Apples","shipping_point":"Benton Harbor FOB SC","district":"MICHIGAN","variety":"FUJI","grade":"U.S. Extra Fancy","package":"cartons tray pack","unit":"USD per package (FOB shipping point)","currency":"USD","price_basis":"quoted_range","price_low":22.0,"price_high":30.95,"price_point":null,"attributes":{"basis_of_sale":"Sales F.O.B. Shipping Point and/or Delivered Sales, Shipping Point Basis","import_export_flag":"D (domestic)","item_size":"88s","organic":"N","season":"2025"},"attribution":"Source: USDA AMS Market News"}],"query":{"commodity":null,"report":null,"limit":2}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"limit":"2"},"x-example-path":"/api/usda/shipping-point/latest"}},"/api/usda/shipping-point/prices":{"get":{"tags":["미국 산지 가격(USDA)"],"summary":"USDA 산지 FOB 가격 구간(원값)","description":"보고된 대로의 산지 FOB 가격 구간. 값은 변형하지 않으며, 행마다 리포트 번호와 리포트 날짜가 붙는다.","operationId":"usda_sp_prices","parameters":[{"name":"commodity","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"승인 범위: Apples, Chinese Cabbage, Onions, Dry, Potatoes, Tomatoes","title":"Commodity"},"description":"승인 범위: Apples, Chinese Cabbage, Onions, Dry, Potatoes, Tomatoes"},{"name":"report","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"리포트: BR_FV110, IF_FV110, IF_FV130, IX_FV120, MB_FV110, OR_FV120, YA_FV110","title":"Report"},"description":"리포트: BR_FV110, IF_FV110, IF_FV130, IX_FV120, MB_FV110, OR_FV120, YA_FV110"},{"name":"from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"From"}},{"name":"to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},{"type":"null"}],"title":"To"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"default":200,"title":"Limit"}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0,"title":"Offset"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"attribution":{"type":"object","properties":{"text":{"type":"string"},"source":{"type":"string"},"program":{"type":"string"},"site":{"type":"string"},"reuse_confirmed_on":{"type":"string"},"notice":{"type":"string"}}},"level":{"type":"object","properties":{"level":{"type":"string"},"what":{"type":"string"},"not":{"type":"string"}}},"as_of":{"type":"string"},"stale_days":{"type":"integer"},"count":{"type":"integer"},"rows":{"type":"array","items":{"type":"object"}},"query":{"type":"object","properties":{"commodity":{"type":"null"},"report":{"type":"null"},"from":{"type":"string"},"to":{"type":"null"},"limit":{"type":"integer"},"offset":{"type":"integer"}}}}},"example":{"attribution":{"text":"Source: USDA AMS Market News","source":"USDA AMS Market News","program":"Specialty Crops Market News Division, USDA Agricultural Marketing Service","site":"https://mymarketnews.ams.usda.gov/","reuse_confirmed_on":"2026-09-29","notice":"Quoted price ranges are reproduced exactly as published by USDA AMS Market News. FarmTempo does not modify, average or convert the reported values. USDA does not endorse FarmTempo."},"level":{"level":"shipping_point","what":"FOB prices at the shipping point: the price as produce leaves the growing area.","not":"Not terminal market prices. Shipping point and terminal prices are different levels of the trade; FarmTempo does not merge them or subtract one from the other."},"as_of":"2026-09-30","stale_days":1,"count":2,"rows":[{"level":"shipping_point","report":{"slug":"IF_FV110","slug_id":2392,"title":"Idaho Falls Shipping Point Fruit Prices","covers":"Idaho Falls, ID"},"report_date":"2026-09-30","commodity":"Apples","shipping_point":"Idaho Falls FOB SC","district":"NEW YORK","variety":"HONEYCRISP","grade":"U.S. Extra Fancy","package":"cartons 12 3-lb film bags","unit":"USD per package (FOB shipping point)","currency":"USD","price_basis":"quoted_range","price_low":39.0,"price_high":45.5,"price_point":null,"attributes":{"basis_of_sale":"Sales F.O.B. Shipping Point and/or Delivered Sales, Shipping Point Basis","import_export_flag":"D (domestic)","item_size":"2 1/2\" minimum","organic":"N","season":"2026"},"attribution":"Source: USDA AMS Market News"},{"level":"shipping_point","report":{"slug":"IF_FV110","slug_id":2392,"title":"Idaho Falls Shipping Point Fruit Prices","covers":"Idaho Falls, ID"},"report_date":"2026-09-30","commodity":"Apples","shipping_point":"Idaho Falls FOB SC","district":"NEW YORK","variety":"HONEYCRISP","grade":"U.S. Extra Fancy","package":"cartons tray pack","unit":"USD per package (FOB shipping point)","currency":"USD","price_basis":"quoted_range","price_low":45.0,"price_high":56.5,"price_point":null,"attributes":{"basis_of_sale":"Sales F.O.B. Shipping Point and/or Delivered Sales, Shipping Point Basis","import_export_flag":"D (domestic)","item_size":"80s","organic":"N","season":"2026"},"attribution":"Source: USDA AMS Market News"}],"query":{"commodity":null,"report":null,"from":"2026-08-31","to":null,"limit":2,"offset":0}}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"x-example-query":{"limit":"2"},"x-example-path":"/api/usda/shipping-point/prices"}},"/api/keys/me":{"get":{"summary":"내 파트너 키 상태·남은 일 한도","description":"X-API-Key(또는 Authorization: Bearer) 로 자기 키의 상태·스코프·오늘 남은 호출 수를 본다. 이 호출은 사용량에 세지 않는다.","operationId":"my_key_api_keys_me_get","parameters":[],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["파트너 키"],"security":[{"ApiKeyAuth":[]}]}},"/api/assets/recommend":{"post":{"tags":["영농 자산 추천(파트너)"],"summary":"Recommend","operationId":"recommend_api_assets_recommend_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Raw"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/assets/search":{"get":{"tags":["영농 자산 추천(파트너)"],"summary":"Search","operationId":"search_api_assets_search_get","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":100,"title":"Q"}},{"name":"type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^(variety|technology|machinery)$"},{"type":"null"}],"title":"Type"}},{"name":"crop","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}],"title":"Crop"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":30,"minimum":1,"default":10,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/assets/{asset_id}":{"get":{"tags":["영농 자산 추천(파트너)"],"summary":"Detail","operationId":"detail_api_assets__asset_id__get","parameters":[{"name":"asset_id","in":"path","required":true,"schema":{"type":"string","title":"Asset Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}},"/api/assets/feedback":{"post":{"tags":["영농 자산 추천(파트너)"],"summary":"Feedback","operationId":"feedback_api_assets_feedback_post","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Raw"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"ApiKeyAuth":[]}]}}},"components":{"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Identifier":{"properties":{"kind":{"type":"string","enum":["item","lot"],"title":"Kind","description":"item: 품목 코드 하나 · lot: 거래 로트 하나"},"jurisdiction":{"type":"string","pattern":"^[A-Z]{2}$","title":"Jurisdiction","description":"관할국 ISO 3166-1 alpha-2 (KR/US)"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source","description":"kind=item 일 때 식별 체계(예: garak_kat_std, usda_mars, fda_ftl)"},"code":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Code","description":"kind=item 일 때 그 체계의 품목 코드"},"scheme":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Scheme","description":"kind=lot 일 때 로트 식별 체계(예: garak_corp_lot)"},"party_id":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Party Id","description":"kind=lot 일 때 식별자를 부여·사용하는 주체(법인 코드는 주체 범위에서만 유일)"},"item_code":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Item Code"},"lot_code":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"title":"Lot Code"},"ref":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}],"title":"Ref","description":"호출자 쪽 참조값 — 응답에 그대로 돌려준다"}},"type":"object","required":["kind","jurisdiction"],"title":"Identifier"},"ReconcileRequest":{"properties":{"identifiers":{"items":{"$ref":"#/components/schemas/Identifier"},"type":"array","maxItems":50,"minItems":1,"title":"Identifiers"}},"type":"object","required":["identifiers"],"title":"ReconcileRequest"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"파트너 키 ft_live_… (Authorization: Bearer 도 됨). 발급: 앱 문의하기 → 'API'"}}},"tags":[{"name":"시세"},{"name":"경락"},{"name":"도매가"},{"name":"표준 품목"},{"name":"이벤트"},{"name":"미국 시세(USDA)"},{"name":"미국 반입 물량(USDA)"},{"name":"미국 산지 가격(USDA)"},{"name":"파트너 키"},{"name":"영농 자산 추천(파트너)"}],"x-farmtempo":{"rate_limit":{"public":"IP 당 10회/초, 순간 30건까지 허용, 초과 시 429","partner":"키마다 일 호출 한도(기본 1,000회) — REST 는 요청 1건, MCP 는 tools/call 1건(initialize·tools/list 는 안 셈), 초과 시 429"},"mcp":{"public":"https://api.farmtempo.com/mcp/public (무인증, 39개 도구)","private":"https://api.farmtempo.com/mcp/private (파트너 키, 6개 도구)","info":"https://api.farmtempo.com/mcp/info"},"missing_in_build":[]}}