jpskill.com
🛠️ 開発・MCP コミュニティ

korea-tourapi

韓国観光公社のTourAPIを使い、有効なリクエストの作成、パラメータ検証、ページネーション処理、エラー対応、そして応答をアプリモデルにマッピングするSkill。

📜 元の英語説明(参考)

Expert workflow for Korea Tourism Organization TourAPI. Builds valid requests, validates parameters, handles pagination/errors, and maps responses to app models.

🇯🇵 日本人クリエイター向け解説

一言でいうと

韓国観光公社のTourAPIを使い、有効なリクエストの作成、パラメータ検証、ページネーション処理、エラー対応、そして応答をアプリモデルにマッピングするSkill。

※ jpskill.com 編集部が日本のビジネス現場向けに補足した解説です。Skill本体の挙動とは独立した参考情報です。

⬇ このSkillをダウンロード(.skill) 元のソースを見る ↗

⚠️ ダウンロード・利用は自己責任でお願いします。当サイトは内容・動作・安全性について責任を負いません。

🎯 このSkillでできること

下記の説明文を読むと、このSkillがあなたに何をしてくれるかが分かります。Claudeにこの分野の依頼をすると、自動で発動します。

📦 インストール方法 (3ステップ)

  1. 1. 上の「ダウンロード」ボタンを押して .skill ファイルを取得
  2. 2. ファイル名の拡張子を .skill から .zip に変えて展開(macは自動展開可)
  3. 3. 展開してできたフォルダを、ホームフォルダの .claude/skills/ に置く
    • · macOS / Linux: ~/.claude/skills/
    • · Windows: %USERPROFILE%\.claude\skills\

Claude Code を再起動すれば完了。「このSkillを使って…」と話しかけなくても、関連する依頼で自動的に呼び出されます。

詳しい使い方ガイドを見る →
最終更新
2026-05-17
取得日時
2026-05-17
同梱ファイル
1

📖 Skill本文(日本語訳)

※ 原文(英語/中国語)を Gemini で日本語化したものです。Claude 自身は原文を読みます。誤訳がある場合は原文をご確認ください。

韓国観光公社 TourAPI スキル

このスキルは、韓国観光公社 TourAPI 4.0 KorService2 との連携を実装またはデバッグする際に使用します。

信頼できる情報源

  • API ファミリー: KorService2
  • ベース URL: https://apis.data.go.kr/B551011/KorService2
  • マニュアルバージョン: TourAPI 4.0 Ver 4.3 (2025-05-12)
  • 対象となる主要エンドポイント:
    • areaCode2, categoryCode2, areaBasedList2, locationBasedList2
    • searchKeyword2, searchFestival2, searchStay2
    • detailCommon2, detailIntro2, detailInfo2, detailImage2
    • areaBasedSyncList2, detailPetTour2, ldongCode2, lclsSystmCode2

使用場面

  • 新しいリスト/詳細/分類 API 呼び出しを構築する場合。
  • 古い TourAPI パラメータを最新の Ver 4.3 の動作に移行する場合。
  • リクエスト検証エラーやデータなしのケースをトラブルシューティングする場合。
  • contentid、contenttypeid、座標、画像フィールドのモデルマッピングを設計する場合。
  • areaBasedSyncList2 から同期ジョブを追加する場合。

必須リクエストベースライン

すべてのリクエストについて、まずこれらのベースラインパラメータを適用します。

  1. serviceKey
  2. MobileOS (IOS、AND、WEB、ETC)
  3. MobileApp (サービス名)
  4. _type=json (XML が明示的に必要な場合を除く)

次に、エンドポイント固有の必須パラメータを追加します。

操作手順

  1. ユーザーの意図を特定します: リスト、詳細、コード、同期、ペット旅行。
  2. 意図に基づいてエンドポイントを選択します (references/quick-reference.md を参照)。
  3. 必須パラメータと互換性のあるオプションフィルターのみを使用してリクエストを構築します。
  4. 呼び出し前に依存関係パラメータを検証します。
    • sigunguCode には areaCode が必要です。
    • cat2 には cat1 が必要です。
    • cat3 には cat1 と cat2 が必要です。
    • lDongSignguCd には lDongRegnCd が必要です。
    • lclsSystm2 には lclsSystm1 が必要です。
    • lclsSystm3 には lclsSystm1 と lclsSystm2 が必要です。
  5. 位置情報クエリの場合、radius を <= 20000 に制限します。
  6. まず response.header を解析します。
    • 成功が期待される場合: resultCode == "0000"
    • それ以外の場合は、実行可能なエラーにマッピングします。
  7. response.body.items.item を堅牢に解析します (単一オブジェクトまたは配列)。
  8. 正規化されたフィールドとページネーション (pageNo、numOfRows、totalCount) を返します。
  9. 詳細フローが必要な場合は、次のように連結します。
    • detailCommon2 -> detailIntro2 -> detailInfo2 -> detailImage2
  10. ダウンストリームでの使用において、ライセンスメタデータ (cpyrhtDivCd) を尊重します。

リクエスト/レスポンス検証機能 (必須)

実装ガイダンスの前に、2つの明示的なチェックを実行し、両方を報告します。

  1. リクエスト検証
  2. レスポンス検証

1) リクエスト検証

  • ベースラインパラメータを検証します: serviceKey、MobileOS、MobileApp、_type。
  • references/validation-matrix.md からエンドポイントの必須パラメータを検証します。
  • 依存関係パラメータ (cat2/cat3、sigunguCode、法定洞、分類システム) を検証します。
  • 削除されたパラメータの拒否リストを検証します。
    • defaultYN、firstImageYN、areacodeYN、catcodeYN、addrinfoYN、mapinfoYN、overviewYN、subImageYN
  • 無効なパラメータが存在する場合、リクエストの構築をブロックし、修正されたパラメータセットを出力します。

2) レスポンス検証

  • resultCode == "0000" の場合にのみ成功を受け入れます。
  • エンベロープの形状を検証します。
    • リスト/詳細エンドポイント: response.header、response.body、response.body.items.item
    • プロバイダーエラーの形状: resultCode/resultMsg がトップレベルに表示される場合があります。
  • 存在する場合、ページネーションフィールドを検証します: pageNo、numOfRows、totalCount。
  • references/validation-matrix.md からエンドポイント固有の最小フィールドを検証します。
  • 必須のレスポンスフィールドが欠落している場合、解析警告と安全なフォールバックマッピングを返します。

コンテンツタイプ ID (韓国語)

  • 12: 観光スポット
  • 14: 文化施設
  • 15: 祭り/公演/イベント
  • 25: 旅行コース
  • 28: レジャー/スポーツ
  • 32: 宿泊
  • 38: ショッピング
  • 39: 飲食店

レスポンス安全解析ルール

  • 数値フィールド (contentid、mapx、mapy、dist) を文字列から安全に解析します。
  • 欠落しているオプション値はエラーではなく、null/空として扱います。
  • デバッグ用に生のソースペイロードを保持します。
  • 以下の厳密な区別を保持します。
    • トランスポートエラー (HTTP/ネットワーク)
    • プラットフォームエラー (OpenAPI_ServiceResponse)
    • プロバイダーエラー (レスポンスヘッダーの resultCode)

既知の 4.3 の注意事項

  • 新しいフィルター/フィールドには、法定洞と分類システムの値が含まれます。
  • 古いエンドポイントのリビジョンから一部の古いフラグが削除されました。
  • detailCommon2 は以前のリビジョンと比較して簡素化されています。

ハードガードレール (無効なパラメータの防止)

削除されたレガシーフラグを detailCommon2 に送信しないでください。

  • defaultYN
  • firstImageYN
  • areacodeYN
  • catcodeYN
  • addrinfoYN
  • mapinfoYN
  • overviewYN

上記のいずれかが生成されたコードに現れた場合、リクエスト実行前に削除してください。

detailCommon2 リクエストは次のように扱われるべきです。

  • ベースラインパラメータ: serviceKey、MobileOS、MobileApp、_type
  • 必須パラメータ: contentId
  • オプションのページングのみ: numOfRows、pageNo

また、detailImage2 で非推奨の subImageYN を使用しないでください。

エージェントの出力契約

このスキルが使用される場合、常に以下を出力します。

  1. 選択されたエンドポイントとその理由。
  2. 最終リクエスト URL (serviceKey は編集またはマスク)。
  3. 必須/オプションパラメータの分割。
  4. 実行された検証チェック。
    • リクエスト検証結果 (合格/不合格 + 修正)
    • レスポンス検証結果 (合格/警告/不合格)
  5. ページネーション処理計画。
  6. エラー処理マッピング。
  7. アプリケーションコードのモデルマッピングに関する注意事項。

ローカルリファレンス

  • references/quick-reference.md
  • references/validation-matrix.md
  • references/wherewego-mapping.md
  • docs/FEATURE_PLAN.md
📜 原文 SKILL.md(Claudeが読む英語/中国語)を展開

Korea TourAPI Skill

Use this skill when implementing or debugging integrations with Korea Tourism Organization TourAPI 4.0 KorService2.

Source of Truth

  • API family: KorService2
  • Base URL: https://apis.data.go.kr/B551011/KorService2
  • Manual version: TourAPI 4.0 Ver 4.3 (2025-05-12)
  • Core endpoints covered:
    • areaCode2, categoryCode2, areaBasedList2, locationBasedList2
    • searchKeyword2, searchFestival2, searchStay2
    • detailCommon2, detailIntro2, detailInfo2, detailImage2
    • areaBasedSyncList2, detailPetTour2, ldongCode2, lclsSystmCode2

When to Use

  • Building new list/detail/taxonomy API calls.
  • Migrating old TourAPI params to latest Ver 4.3 behavior.
  • Troubleshooting request validation errors and no-data cases.
  • Designing model mapping for contentid, contenttypeid, coordinates, image fields.
  • Adding sync jobs from areaBasedSyncList2.

Required Request Baseline

For every request, enforce these baseline params first:

  1. serviceKey
  2. MobileOS (IOS, AND, WEB, ETC)
  3. MobileApp (service name)
  4. _type=json (unless XML is explicitly required)

Then add endpoint-specific required params.

Operating Procedure

  1. Identify user intent: list, detail, codes, sync, pet travel.
  2. Select endpoint by intent (see references/quick-reference.md).
  3. Build request with required params and only compatible optional filters.
  4. Validate dependency params before call:
    • sigunguCode requires areaCode
    • cat2 requires cat1
    • cat3 requires cat1 and cat2
    • lDongSignguCd requires lDongRegnCd
    • lclsSystm2 requires lclsSystm1
    • lclsSystm3 requires lclsSystm1 and lclsSystm2
  5. For location queries, clamp radius to <= 20000.
  6. Parse response.header first:
    • success expected: resultCode == "0000"
    • else map to actionable error
  7. Parse response.body.items.item robustly (single object or array).
  8. Return normalized fields and pagination (pageNo, numOfRows, totalCount).
  9. If detail flow is needed, chain:
    • detailCommon2 -> detailIntro2 -> detailInfo2 -> detailImage2
  10. Respect licensing metadata (cpyrhtDivCd) in downstream usage.

Request/Response Validation Feature (Mandatory)

Before implementation guidance, run two explicit checks and report both:

  1. Request validation
  2. Response validation

1) Request validation

  • Validate baseline params: serviceKey, MobileOS, MobileApp, _type.
  • Validate endpoint required params from references/validation-matrix.md.
  • Validate dependency params (cat2/cat3, sigunguCode, legal-dong, classification-system).
  • Validate removed params denylist:
    • defaultYN, firstImageYN, areacodeYN, catcodeYN, addrinfoYN, mapinfoYN, overviewYN, subImageYN
  • If any invalid param exists, block request construction and output a corrected param set.

2) Response validation

  • Accept success only when resultCode == "0000".
  • Validate envelope shape:
    • list/detail endpoints: response.header, response.body, response.body.items.item
    • provider error shape: resultCode/resultMsg top-level may appear
  • Validate pagination fields when present: pageNo, numOfRows, totalCount.
  • Validate endpoint-specific minimum fields from references/validation-matrix.md.
  • If required response fields are missing, return a parsing warning and safe fallback mapping.

Content Type IDs (Kor)

  • 12: Tour spot
  • 14: Culture facility
  • 15: Festival/performance/event
  • 25: Travel course
  • 28: Leports
  • 32: Stay
  • 38: Shopping
  • 39: Food

Response-Safe Parsing Rules

  • Parse numeric fields from strings (contentid, mapx, mapy, dist) safely.
  • Treat missing optional values as null/empty, not errors.
  • Keep raw source payload for debugging.
  • Keep a strict distinction between:
    • transport errors (HTTP/network)
    • platform errors (OpenAPI_ServiceResponse)
    • provider errors (resultCode in response header)

Known 4.3 Notes

  • New filters/fields include legal-dong and classification-system values.
  • Some older flags were removed from older endpoint revisions.
  • detailCommon2 is simplified compared with prior revisions.

Hard Guardrails (Prevent Invalid Params)

Never send removed legacy flags to detailCommon2:

  • defaultYN
  • firstImageYN
  • areacodeYN
  • catcodeYN
  • addrinfoYN
  • mapinfoYN
  • overviewYN

If any of the above appears in generated code, remove it before request execution.

detailCommon2 request should be treated as:

  • baseline params: serviceKey, MobileOS, MobileApp, _type
  • required params: contentId
  • optional paging only: numOfRows, pageNo

Also do not use deprecated subImageYN on detailImage2.

Output Contract for Agent

When this skill is used, always output:

  1. Selected endpoint and reason.
  2. Final request URL (redact or mask serviceKey).
  3. Required/optional params split.
  4. Validation checks run.
    • Request validation result (pass/fail + fixes)
    • Response validation result (pass/warn/fail)
  5. Pagination handling plan.
  6. Error handling mapping.
  7. Model mapping notes for app code.

Local References

  • references/quick-reference.md
  • references/validation-matrix.md
  • references/wherewego-mapping.md
  • docs/FEATURE_PLAN.md