KAMIS CLI — 한국 농수산물 가격 OpenAPI

Wraps KAMIS (Korea Agro-Fisheries & Food Trade Corporation, kamis.or.kr) — the canonical source for Korean agricultural, livestock, and aquatic product prices. Daily wholesale/retail prices for ~180 items across 10 부류, with built-in 1-day/1-week/2-week/1-month/1-year/평년 comparisons.

Endpoint: https://www.kamis.or.kr/service/price/xml.do?action={ACTION}&p_cert_key={KEY}&p_cert_id={ID}&p_returntype=json&...

Setup (once)

1. Apply for an API key at https://www.kamis.or.kr/customer/reference/openapi_list.do (1-business-day approval, free).
2. Export credentials in your shell:

export KAMIS_CERT_KEY="your-key"
export KAMIS_CERT_ID="your-email-id"

The CLI also accepts --key / --id flags. If unset, it falls back to TEST/TEST which works for dailyPriceByCategoryList (the most common call) but is rate-limited and may return error_code:001 for paid endpoints.

Subcommands

All subcommands return JSON to stdout. Pipe through jq for shaping.

1. daily.sh — 일일 부류별 도/소매가격 (dailyPriceByCategoryList)

The flagship endpoint. One call returns every item in a 부류 (category) with today / 1 day ago / 1 week ago / 2 weeks ago / 1 month ago / 1 year ago / 평년 prices side-by-side. Perfect for AI agents asking "what's happening with onion prices this week?"

scripts/daily.sh --cls 01 --category 200 --date 2026-04-30
# 01 = 소매(retail), 02 = 도매(wholesale)
# category: 100=식량작물, 200=채소류, 300=특용작물, 400=과일류, 500=축산물, 600=수산물
# Optional: --country 1101 (서울), --kg-convert Y

2. period.sh — 기간별 도매가격 (periodProductList)

Daily prices for a specific item across a date range (≤ 1 year). Returns one row per market per day.

scripts/period.sh \
  --start 2026-01-01 --end 2026-04-30 \
  --category 200 --item 211 --kind 01 --rank 04 --country 1101
# 211 = 양파, 01 = 일반양파, 04 = 상품, 1101 = 서울

3. period-retail.sh — 기간별 소매가격 (periodRetailProductList)

Same shape as period.sh but soft-retail (대형마트/전통시장) instead of 도매. Use when comparing 소매 마진.

scripts/period-retail.sh --start 2026-04-01 --end 2026-04-30 --category 200 --item 211 --kind 01 --rank 04 --country 1101

4. monthly.sh — 월별 평균 가격 (monthlySalesList)

Long-term monthly averages — use for seasonality charts, YoY comparison.

scripts/monthly.sh --year 2026 --period 2024,2025 --category 200 --item 211 --kind 01

5. yearly.sh — 연도별 평균 가격 (yearlySalesList)

Annual averages.

scripts/yearly.sh --year 2026 --category 200 --item 211 --kind 01

6. recent.sh — 최근 가격 동향 간이조회 (recentlyPriceTrendList)

Lightweight time-series for a single product number — last 40 days, 30 days, 20 days, 10 days, 0 days, plus min/max. Useful for fast charts without fetching the full period dataset.

scripts/recent.sh --product 111
# 111 = 쌀

7. codes.sh — 코드 표 (helper, no API call)

Local lookup of category / item / kind / rank / country codes. Wraps reference/codes.json — the canonical KAMIS code table cached at skill install.

scripts/codes.sh categories
scripts/codes.sh items --category 200
scripts/codes.sh countries          # 17 시·군 codes
scripts/codes.sh ranks

Quick recipes

"How much have onion prices moved this week?"

scripts/daily.sh --cls 01 --category 200 | jq '.data.item[] | select(.item_name=="양파")'

"Plot 1-year retail price for rice"

scripts/period.sh --start 2025-05-01 --end 2026-04-30 --category 100 --item 111 --kind 01 --rank 04 --country 1101 | jq '.data.item[] | {date: .yyyy + "-" + .regday, price: .price}'

"Daily morning brief: top 5 climbers in 채소류"

scripts/daily.sh --cls 02 --category 200 \
  | jq '[.data.item[] | {name: .item_name, kind: .kind_name, today: (.dpr1|gsub(",";"")|tonumber), week_ago: (.dpr3|gsub(",";"")|tonumber)} | .pct = ((.today - .week_ago) / .week_ago * 100)] | sort_by(-.pct) | .[0:5]'

See examples/restaurant-cost-tracker.sh for a full pipeline that emits a daily Slack/Telegram-ready summary.

Pairs naturally with

• opendart-cli — overlay 식료품 corporate disclosure with raw input prices.
• bank-of-korea-ecos-cli — compare CPI-Food vs raw 농산물 도매가.
• kr-holiday-cli — exclude 명절 demand spikes from trend lines.
• naver-datalab-cli — correlate 검색량 (e.g., "양파 가격") with the price spike.
• kakao-local-cli — map 도매시장 locations.
• tistory-api-cli / velog-cli — auto-publish a daily-price digest.

Notes & gotchas

• The TEST key works for dailyPriceByCategoryList (immediate snapshot) but several "기간" endpoints return error_code:"001" until you swap in your own key.
• KAMIS only retains 1 year of recent data through the public API. For older data, contact KAMIS directly (061-930-9971).
• p_returntype=json is supported but the API still ships an xml.do path — that's the actual route, not a typo.
• Numbers come as comma-formatted strings ("62,421") — strip with jq 'gsub(","; "") | tonumber' before arithmetic.
• A few endpoints inconsistently use p_country_code vs p_countycode — the scripts normalize this for you.