KTO TourAPI CLI

Korean tourism content (관광지·문화시설·축제공연·여행코스·레포츠·숙박·쇼핑·음식점) via 한국관광공사 TourAPI 4.0 (apis.data.go.kr/B551011/KorService2). Eight subcommands wrap areaCode2, cat...

Security Scan

The skill's code and instructions match its stated purpose (wrapping the Korean TourAPI) but the published metadata omits required environment variables and required binaries, an inconsistency you should resolve before installing.

Purpose & Capability

Name/description describe a CLI wrapper for 한국관광공사 TourAPI 4.0; the scripts implement exactly that (area, nearby, search, festival, stay, detail). The included scripts only call the TourAPI endpoints and normalize JSON output, which is coherent with the stated purpose.

Instruction Scope

SKILL.md and the scripts instruct the agent / user to export TOURAPI_SERVICE_KEY (the API decoding key) and to run bash/curl/jq. The runtime instructions do not request unrelated files, system data, or external endpoints beyond the documented apis.data.go.kr domain. However the SKILL.md and script behavior require an API key and certain binaries that are not declared in the registry metadata—this mismatch is notable.

Install Mechanism

There is no install spec (instruction-only), so nothing is downloaded from arbitrary URLs. The repo includes bash scripts and examples; no package installs or remote code-fetching occur as part of an install step. Risk from install mechanism is low.

Credentials

The skill requires a TOURAPI_SERVICE_KEY (the TourAPI decoding key) and optionally TOURAPI_BASE / TOURAPI_MOBILE_OS / TOURAPI_MOBILE_APP; it also requires binaries (bash, curl, jq). The registry metadata claims 'Required env vars: none' and 'Required binaries: none', which is inconsistent and misleading. Requesting the single TourAPI key is proportionate to the stated purpose, but the metadata omission is a problem and should be corrected before use.

Persistence & Privilege

The skill does not request always:true, does not modify other skills or system-wide config, and does not request elevated or persistent platform privileges. Autonomous invocation is allowed (default) but there are no additional persistent privileges.

What to consider before installing

This CLI appears to do exactly what it says: call the Korean TourAPI and return normalized JSONL. Before installing or enabling it, verify these points: (1) the skill actually requires TOURAPI_SERVICE_KEY (the decoding key) and the registry metadata did not declare that—do not provide unrelated secrets; (2) the scripts need bash, curl and jq locally—ensure those binaries are available and trustworthy; (3) the code calls only apis.data.go.kr (the official data.go.kr host) and uses mktemp/curl/jq to process responses, so there is no obvious exfiltration, but confirm the owner/source (there is no homepage) — prefer a published repository or verified author before granting the skill access to your environment; (4) if you plan automation, consider scope: the skill will make outgoing HTTP requests using your TourAPI key, so treat that key like any API secret and rotate/revoke it if needed. If the publisher can update the registry metadata to list TOURAPI_SERVICE_KEY and the required binaries, that would resolve the main concern.

Command-line wrapper for 한국관광공사 TourAPI 4.0 (KorService2) — Korea's first-party tourism content API. Curated and maintained by 한국관광공사 (Korea Tourism Organization), it's the data behind VisitKorea, 대한민국 구석구석, and most travel apps in Korea.

Eight subcommands, each wraps one (or one composite) endpoint:

Command	Endpoint(s)	Purpose
scripts/area-code.sh	areaCode2	17개 광역시도 → 시군구 코드 트리.
scripts/category-code.sh	categoryCode2	3-level cat1/cat2/cat3 service-classification tree.
scripts/area.sh	areaBasedList2	Browse content by area / sigungu / contentType / category.
scripts/nearby.sh	locationBasedList2	Radius search (≤20 km) from a (lng, lat) point.
scripts/search.sh	searchKeyword2	Keyword search with optional area/category filters.
scripts/festival.sh	searchFestival2	Festivals/events overlapping a date window.
scripts/stay.sh	searchStay2	Lodging-only browse (hotels, motels, pensions, hanok stays).
scripts/detail.sh	detailCommon2 + detailIntro2 + detailInfo2 + detailImage2	One-shot full record for a contentId.

All output is JSONL — one row per item — so it pipes directly into jq, csvkit, pandas, or downstream skills.

When to use this skill

• Trip planning agents — "build me a 3-day Gangneung itinerary" → area --area-code 32 --sigungu-code 1 + nearby --lng <h1> --lat <h1> + festival --start 20260601.
• Festival calendars — festival --start YYYYMMDD --end YYYYMMDD → JSONL → cal.json.
• K-content blogs / videos — search --keyword 강릉 then detail --content-id <id> --include-images for hero imagery + descriptions.
• Nearby-X discovery on maps — feed Kakao map taps into nearby --lng X --lat Y --content-type-id 39 to surface restaurants.
• Government/NGO grounded answers — TourAPI is curated by KTO; use it when you need authoritative tourism facts, not crowd-sourced.

Do not use this skill for

• Real-time prices, availability, bookings — TourAPI is a content directory, not a reservation API. Pair with stay-platform APIs (야놀자, 여기어때, Booking.com) for live inventory.
• User reviews / ratings — TourAPI does not expose review counts. Use Naver Place / Kakao Map APIs.
• English / non-KR languages — this skill targets KorService2. KTO publishes parallel EngService2 / ChsService2 / JpnService2 / GerService2 / FreService2 / SpnService2 / RusService2 endpoints; not in this skill yet.
• High-throughput public-facing apps without quota — the dev-tier ceiling is 1,000 req/day. Apply for production tier on data.go.kr.

Prerequisites

1. Register at https://www.data.go.kr/ (Korean OpenData portal, free, no business required).
2. Apply for "한국관광공사_국문 관광정보 서비스_GW" (TourAPI 4.0 / KorService2). Approval is automatic for the dev tier.
3. Copy your Decoding key (the raw, not URL-encoded form) and export:

   export TOURAPI_SERVICE_KEY='your_decoded_key_here'
   

4. Optional overrides:

   export TOURAPI_BASE='https://apis.data.go.kr/B551011/KorService2'
   export TOURAPI_MOBILE_OS='ETC'             # ETC|AND|IOS|WIN|WEB
   export TOURAPI_MOBILE_APP='your-app-name'  # any short identifier
   

5. Dependencies: bash, curl, jq (default on macOS / standard Linux).

Reference codes

contentTypeId (used in --content-type-id):

ID	Type	ID	Type
12	관광지	28	레포츠
14	문화시설	32	숙박
15	축제공연행사	38	쇼핑
25	여행코스	39	음식점

Top-level areaCode (run area-code.sh for fresh sigungu codes):

Code	Region	Code	Region	Code	Region
1	서울	32	강원도	6	부산
2	인천	33	충청북도	7	대구
31	경기도	34	충청남도	8	광주
35	경상북도	36	경상남도	9	대전
37	전라북도	38	전라남도	10	울산
39	제주특별자치도			11	세종특별자치시

(Full canonical list always: bash scripts/area-code.sh.)

Top-level cat1: A01=자연 / A02=인문(문화/예술/역사) / A03=레포츠 / A04=쇼핑 / A05=음식 / B02=숙박 / C01=추천코스.

Examples

Browse 관광지 in 강릉

bash scripts/area.sh --area-code 32 --sigungu-code 1 --content-type-id 12 --num 10

Find 음식점 within 500 m of 경복궁 (lng 126.9770, lat 37.5797)

bash scripts/nearby.sh --lng 126.9770 --lat 37.5797 --radius 500 --content-type-id 39

Festival list for May 2026 in Jeju

bash scripts/festival.sh --start 20260501 --end 20260531 --area-code 39

Keyword search for "한옥" stays

bash scripts/search.sh --keyword 한옥 --content-type-id 32 --num 30

Full record (with images) for 경복궁 (contentId 264432)

bash scripts/detail.sh --content-id 264432 --content-type-id 14 --include-images

Ten-day Korea festival calendar for content automation

START=$(date -u +%Y%m%d)
END=$(date -u -v+10d +%Y%m%d 2>/dev/null || date -u -d "+10 days" +%Y%m%d)
bash scripts/festival.sh --start "$START" --end "$END" --num 100 \
  | jq -r '[.title, .eventstartdate, .eventenddate, .addr1] | @tsv'

Field naming

TourAPI returns lowercase field names without delimiters (e.g. mapx, mapy, addr1, addr2, firstimage, firstimage2, tel, eventstartdate, eventenddate, dist). The CLI passes these through verbatim so downstream pipelines keep schema parity with TourAPI's published spec.

Errors

• exit 64 — bad CLI input (missing required flag, invalid date, unknown contentTypeId).
• exit 78 — TOURAPI_SERVICE_KEY env var missing.
• exit 22 — TourAPI returned non-2xx, an XML error envelope, or resultCode != "0000". The full body is echoed to stderr.
• exit 127 — required binary (curl, jq) not on PATH.

Pairs with

• juso-address-cli — resolve raw addr1 → 우편번호 + 행정동 코드.
• kakao-local-cli — drop mapx/mapy directly onto Kakao Maps.
• kr-holiday-cli — overlay legal holidays onto the festival calendar.
• naver-papago-translate — localize titles/overviews for non-KR users.
• tistory-api-cli / velog-cli — publish the rendered itinerary.
• kosis-cli / bank-of-korea-ecos-cli — overlay tourism volume / FX context for travel-economics posts.

License

MIT-0. Data is © 한국관광공사 / 공공데이터포털 — credit per data.go.kr terms when republishing.