Korean agricultural/livestock/aquatic wholesale & retail price data via the official KAMIS (한국농수산식품유통공사) OpenAPI. Use for daily 도매가/소매가 lookup, 7-day & month...
---
name: kamis-cli
description: Korean agricultural/livestock/aquatic wholesale & retail price data via the official KAMIS (한국농수산식품유통공사) OpenAPI. Use for daily 도매가/소매가 lookup, 7-day & monthly & yearly trends, regional price comparison, and code lookup. Free p_cert_key from kamis.or.kr. Use when the user asks about Korean food/produce prices, market prices, agri price trends, restaurant ingredient costs, KAMIS, 농산물 가격, or 도매시장.
license: MIT
---
# KAMIS CLI — 한국 농수산물 가격 OpenAPI
Wraps **KAMIS** (Korea Agro-Fisheries & Food Trade Corporation, [kamis.or.kr](https://www.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:
```bash
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?"
```bash
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.
```bash
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 소매 마진.
```bash
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.
```bash
scripts/monthly.sh --year 2026 --period 2024,2025 --category 200 --item 211 --kind 01
```
### 5. `yearly.sh` — 연도별 평균 가격 (`yearlySalesList`)
Annual averages.
```bash
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.
```bash
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.
```bash
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?"**
```bash
scripts/daily.sh --cls 01 --category 200 | jq '.data.item[] | select(.item_name=="양파")'
```
**"Plot 1-year retail price for rice"**
```bash
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 채소류"**
```bash
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.
don't have the plugin yet? install it then click "run inline in claude" again.