2sem/korea-tourapi

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