Learn-skills.dev korea-tourapi

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

install

source · Clone the upstream repo

git clone https://github.com/NeverSight/learn-skills.dev

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/NeverSight/learn-skills.dev "$T" && mkdir -p ~/.claude/skills && cp -r "$T/data/skills-md/2sem/korea-tourapi-skill/korea-tourapi" ~/.claude/skills/neversight-learn-skills-dev-korea-tourapi && rm -rf "$T"

manifest: data/skills-md/2sem/korea-tourapi-skill/korea-tourapi/SKILL.md

source content

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:

```
serviceKey
```
```
MobileOS
```
(
```
IOS
```
,
```
AND
```
,
```
WEB
```
,
```
ETC
```
)
```
MobileApp
```
(service name)
```
_type=json
```
(unless XML is explicitly required)

Then add endpoint-specific required params.

Operating Procedure

Identify user intent: list, detail, codes, sync, pet travel.
Select endpoint by intent (see
```
references/quick-reference.md
```
).
Build request with required params and only compatible optional filters.

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
```

For location queries, clamp
```
radius
```
to
```
<= 20000
```
.
Parse
```
response.header
```
first:
- success expected:
```
resultCode == "0000"
```
- else map to actionable error
Parse
```
response.body.items.item
```
robustly (single object or array).
Return normalized fields and pagination (
```
pageNo
```
,
```
numOfRows
```
,
```
totalCount
```
).

If detail flow is needed, chain:

detailCommon2

detailIntro2

detailInfo2

detailImage2

Respect licensing metadata (
```
cpyrhtDivCd
```
) in downstream usage.

Request/Response Validation Feature (Mandatory)

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

Request validation
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

detailImage2

Output Contract for Agent

When this skill is used, always output:

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

Local References

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