kopis-performance-search

name	kopis-performance-search
description	KOPIS 공연예술통합전산망 Open API를 k-skill-proxy 경유로 조회해 공연 목록·상세와 공연시설 정보를 찾는다. 조회 전용.
license	MIT
metadata	{"category":"culture","locale":"ko-KR","phase":"v1"}

KOPIS Performance Search

What this skill does

KOPIS 공연예술통합전산망 Open API https://kopis.or.kr/openApi/restful 을 k-skill-proxy 경유로 호출한다. www.kopis.or.kr redirect는 일부 요청을 차단할 수 있어 canonical host를 직접 사용한다.

지원 endpoint:

• GET /v1/kopis/performances → pblprfr 공연 목록
• GET /v1/kopis/performances/{id} → pblprfr/{mt20id} 공연 상세
• GET /v1/kopis/facilities → prfplc 공연시설 목록
• GET /v1/kopis/facilities/{id} → prfplc/{mt10id} 공연시설 상세

예매, 좌석 선점, 결제 자동화는 범위 밖이다.

When to use

• "이번 달 서울 공연 KOPIS에서 찾아줘"
• "공연 ID PF132236 상세 보여줘"
• "세종문화회관 KOPIS 시설 정보 찾아줘"

Prerequisites

• 인터넷 연결
• hosted/self-host k-skill-proxy의 /v1/kopis/* route 접근 가능

Credential requirements

• 사용자 측 필수 시크릿 없음.
• KSKILL_PROXY_BASE_URL — self-host·별도 프록시를 쓸 때만 설정. 비우면 기본 hosted https://k-skill-proxy.nomadamas.org 를 사용한다.
• KOPIS_API_KEY 또는 KSKILL_KOPIS_API_KEY 는 프록시 운영 서버 환경에만 둔다.

키 발급: KOPIS Open API 안내 https://www.kopis.or.kr/por/cs/openapi/openApiInfo.do?menuId=MNU_00074 에서 회원가입/로그인 후 OpenAPI 이용신청으로 발급한다.

Inputs

공연 목록:

• start/stdate: 시작일 YYYYMMDD
• end/eddate: 종료일 YYYYMMDD
• genre/shcate: 장르 코드
• areaCode/signgucode: 지역 코드
• sigunguCode/signgucodesub: 시군구 코드
• prfstate, kidstate, openrun, afterdate
• page/cpage, limit/rows

시설 목록:

• q/query/name/shprfnmfct: 시설명
• areaCode/signgucode, sigunguCode/signgucodesub
• fcltychartr, afterdate
• page/cpage, limit/rows

Workflow

1. Search a small list first

BASE="${KSKILL_PROXY_BASE_URL:-https://k-skill-proxy.nomadamas.org}"
curl -fsS --get "$BASE/v1/kopis/performances" \
  --data-urlencode "start=20260701" \
  --data-urlencode "end=20260731" \
  --data-urlencode "areaCode=11" \
  --data-urlencode "limit=10"

2. Fetch details for a selected ID

curl -fsS "$BASE/v1/kopis/performances/PF132236"

시설명으로 먼저 찾은 뒤 시설 ID가 필요하면 상세를 조회한다.

curl -fsS --get "$BASE/v1/kopis/facilities" \
  --data-urlencode "q=세종문화회관" \
  --data-urlencode "limit=5"

Failure modes

• 400 bad_request: 날짜 형식, 페이지 크기, ID 형식이 잘못됨.
• 503 upstream_not_configured: 프록시 서버에 KOPIS_API_KEY/KSKILL_KOPIS_API_KEY 없음.
• KOPIS upstream XML 에러/빈 결과: 검색 기간·지역·장르를 완화하거나 ID를 다시 확인한다.
• KOPIS 공식 가이드는 오류 XML 스키마를 명확히 열거하지 않는다. live 응답의 XML 본문을 그대로 확인한다.

Done when

• 목록 검색은 날짜 범위를 좁혀 수행했다.
• 상세 답변은 KOPIS mt20id 또는 mt10id를 함께 명시했다.
• 공연명, 기간, 장소, 상태, 출처 endpoint를 원문 필드 기준으로 요약했다.
• 예매/결제/좌석 자동화로 넘어가지 않았다.

Maintainer review notes

키 없이 가능한 검증:

• ./scripts/validate-skills.sh
• node --test packages/k-skill-proxy/test/server.test.js
• curl -i --get "$KSKILL_PROXY_BASE_URL/v1/kopis/performances" --data-urlencode "start=20260701" --data-urlencode "end=20260731" (키 미설정이면 503 확인)

Live smoke는 hosted/self-host proxy에 KOPIS_API_KEY가 설정된 뒤 수행한다.

Safety notes

• 조회 전용 스킬이다.
• 예매, 좌석 선점, 결제, 로그인 자동화는 하지 않는다.
• 인증키는 프록시 서버에서만 다루며 repo/GitHub Actions/public docs에 저장하지 않는다.