KOPIS OpenAPI를 활용해 26년 1~6월 기준 공연 회차 top10 제작사를 추출한 작업의 단계별 프롬프트 가이드

한 번에 붙여넣어서 되는 프롬프트는 아니지만.. 이 흐름대로 따라가거나, 클로드에게 이 내용을 미리 알려주고 작업을 진행한다면 더 수월하게 데이터를 추출할 수 있을 것!


STEP 1. 목표 설정 + 환경 제약 확인

프롬프트 의도: 데이터 소스·기간·지표·결과물을 한 번에 정의하고, API 호출 환경 제약을 바로 전달한다.

⌨️ kopis 데이터 기반으로 ‘상반기 가장 열심히 일한 제작사’ top 10을 뽑으려고 해. 26년 1~6월 기준, 공연 회차가 가장 많았던 제작사를 1위부터 10위까지 선정할거야.
kopis는 웹사이트에서 직접 호출을 허용하지 않아. 내가 cmd로 직접 입력해야해.

결과: Claude가 KOPIS API 구조 탐색 스크립트(step1_explore.py)를 생성. 공연목록·공연상세·공연시설별통계 API 응답 필드를 확인하고, 회차 데이터 접근 경로를 파악했다. 이후 모든 스크립트는 로컬 CMD 실행 기준으로 작성됨.

⚠️ KOPIS API는 외부(Claude 샌드박스 포함)에서 직접 호출 불가. 스크립트를 로컬 CMD에서 실행하고, 결과 파일을 Claude와 공유하는 방식으로 진행해야 한다.

STEP 2. 추출 로직 구체화

프롬프트 의도: 집계 기간·회차 카운트 기준·공연장 기반 조회 방식을 번호로 명시. KOPIS API 가이드 파일(guide.md)을 첨부해 Claude가 정확한 엔드포인트와 매칭 조건을 파악하게 한다.

⌨️ 데이터 추출을 위한 py를 생성해줘.

  1. 26년 1월 1일 ~ 6월 30일까지 진행된(진행예정인) 공연을 모두 리스트업

  2. 공연 기간이 26년 1월 1일 ~ 6월 30일 이내인 경우 - 공연의 전체 회차를 카운트

  3. 공연 기간이 해당 기간을 벗어나는 경우 - 기간 내의 회차만 카운트

  4. 공연 회차는 해당 공연의 공연장을 기반으로 카운트해야 함.

  5. 공연 기간(일자)이 긴 공연 상위 100개를 먼저 필터링 한 후, 상위 100개 공연에 대해서만 공연 회차를 추출하는 것으로 하자.

  6. 공연 상연횟수(회차) 확인하는 방법에 대해서는 guide.md 파일을 참고해줘.

결과: collect.py 초안 생성. 3단계 API 체인이 구현됨:

  • /pblprfr → 공연 목록 수집
  • 공연 상세에서 fcltynm 파싱 → 공연시설명 + 공연장명 분리
  • /prfstsPrfByFct → 날짜 호출 + 상연횟수(prfdtcnt) 추출

단, 이 시점에는 공연 기간이 긴 상위 100개만 필터링해서 회차를 조회하는 방식이었음 → STEP 3에서 문제 발견 후 제거.

💡 클로드가 모를만한 조건들, 판단할 수 없는 것들은 내가 충분히 정보를 줘야 한다.
예를 들어 진행예정인 공연을 함께 카운트할 것인지, 공연 기간이 6월 30일 이후까지 되어있는 공연들은 포함을 할 것인지, 오픈런이나 아동공연을 포함할 것인지 등의 내용은 클로드가 판단하지 않고 나의 목적과 의도에 맞게 내가 판단하고 프롬프트에 입력해줘야 한다.

처음부터 모든 조건을 구체화할 필요는 없다. 클로드와 대화하면서 구체화해 나가도 충분하다.

STEP 3. 1차 추출 결과 확인 후 수정사항 도출

추출된 데이터를 확인하니 몇 가지 문제가 있었다.

  1. 공연의 ‘제작사’가 제대로 입력이 되어있지 않은 공연들이 많았다. 몇 개 공연을 샘플로 추출해서 확인해보니, 단체 정보가 입력되는 컬럼이 여러개라 어떤 제작사는 ‘기획사’컬럼에, 어떤 제작사는 ‘주최’컬럼에 있기도 했다. 그래서 공연 제작사, 기획사, 주최, 주관을 모두 제작사로 간주해서 데이터를 합치는 과정을 거쳤다.
  2. 공연 회차를 기준으로 하다보니, 오픈런 공연이나 아동 공연들이 압도적으로 많았다. 매일 하는 공연들이니 당연하다. 그래서 오픈런/아동 공연을 포함한 순위와 제외한 순위를 각각 추출하기로 했다.
  3. 공연기간(일수)를 기준으로 데이터를 추출하니, 기간만 길고 실제로 공연이 진행된 횟수는 적은 경우가 보였다. 예를 들어 26년 1월부터 6월까지, 월 1회씩 6개월간 진행된 공연은 실제로 상연 횟수는 6회이지만 기간은 6개월로 잡혔다. 그래서 공연 기간은 ‘상반기’안에 들어오는지 거르는 조건으로 활용하고, 순위에는 참고하지 않기로 했다.

그래서 다음 단계에서 위 3개에 대한 py 수정을 요청하고 다시 데이터를 추출했다.

STEP 4. 조건을 수정하고 데이터를 재추출

프롬프트 의도: “수정 필요한 부분 + 번호” 패턴으로 변경사항을 명확히 전달. 3번에서 단순히 “필터링하지 마”가 아니라 이유(데이터 오류 발생 원인)를 같이 넣어 Claude가 연관 로직까지 함께 수정하게 함.

⌨️ 아래 내용을 반영해서 py를 수정해줘.

  1. 공연 상세에서 ‘제작사’를 기준으로 하지 않고, 제작사, 기획사, 주최, 주관을 모두 ‘제작사’로 간주한다. 한 공연에 여러 제작사가 있을 수 있음.

  2. 오픈런, 아동 공연을 제외한 경우의 제작사 TOP10을 별도로 추출한다. (오픈런과 아동 모두 N인 공연들만을 기준으로 했을 때 제작사 TOP10)

  3. 기존 로직 수정: 공연 일수 기준으로 공연을 먼저 필터링 하지 않는다. 공연 기간은 길지만, 실제로 기간 내에 상연한 횟수가 적은 공연이 있기 때문에 데이터 오류가 발생함. 모든 공연의 기간 내(26년 1월 1일 ~ 6월 30일) 회차를 확인하고, 제작사별로 합산한 것을 기준으로 top 10을 추출해야 한다.”

결과: collect.py 수정.

  • entrpsnmP (제작사), entrpsnmA (기획사), entrpsnmH (주최), entrpsnmS (주관) 4개 필드를 모두 제작사로 처리, 쉼표 구분 파싱
  • openrun, child 필드 수집 → 별도 필터링 집계 추가
  • 상위 100개 pre-filter 제거 → 전체 공연(약 10,000건+) 대상으로 변경
  • Excel에 각각의 시트를 생성: Top10_전체 / Top10_오픈런아동제외 / 공연상세_전체

💡 나는 보통 번호를 붙여서 프롬프트를 쓰는 편이다. 물론 줄글로 써도 되지만 번호를 붙여야 대화하기가 편하다. 어떤 조건이 제대로 적용되지 않았을 때에 ‘3번은 반영이 제대로 안 된 것 같아. 다시 확인해’라고 이야기하거나, ‘1,2번은 그대로 두고 3번 내용만 이렇게 수정할게’ 라고 이야기하면 훨씬 편하기 때문!

STEP 5. 오류 대응

프롬프트 의도: 원인 분석 없이 터미널 로그를 그대로 붙여넣고 상황만 한 줄 추가. Claude가 진단부터 수정까지 처리하게 한다.

⌨️ ‘[ 697/10364] 조현진 플루트 독주회 (PF292107) 공연 상세 조회 실패 → 건너뜀’
모든 공연들이 이렇게 건너뛰어졌어. 상세 조회 실패

결과: Claude가 진단 스크립트(debug_detail.py)를 만들어 API를 직접 테스트 → API 자체는 정상(HTTP 200, XML 파싱 성공)임을 확인.

원인: fetch_xml 함수가 실패 시 이유를 로그에 남기지 않는 구조였음. HTTP 오류든, 빈 응답이든, XML 파싱 오류든 모두 동일한 “조회 실패” 메시지로 처리되어 원인 파악 불가.

수정 내용:

  • 실패 유형별 로그 분리: HTTP 상태코드 / 빈 응답 / XML 파싱 오류(응답 미리보기 포함) / 타임아웃
  • 지수 백오프 재시도 추가: 실패 시 2^attempt초 대기 후 최대 3회 재시도
  • 공연 상세 API 호출 간격 0.3초 → 0.5초로 증가

💡 오류가 발생하면, 오류가 발생한 텍스트를 그대로 복사해서 붙여넣거나, 화면을 캡쳐해서 그대로 채팅창에 입력한다. 오류를 무서워할 필요가 전혀 없다. 다시 하면 된다!


(참고) collect.py 주요 구현 내용

💡 주요 구현 내용 요약
[STEP 1] 공연목록 수집

  • 장기공연 포함을 위해 2025.01~2026.06 범위로 조회

  • 26년 상반기와 overlap 없는 공연 제외

  • overlap 일수 기준 상위 100개 선정

[STEP 2] 공연 상세 + 회차 수집 (100개 대상)

  • /pblprfr/{mt20id} → 제작사(entrpsnmP), 공연장(fcltynm) 조회

  • fcltynm 파싱: depth tracking으로 공연시설명 / 공연장명 분리

예) ‘예스24 스테이지(구. DCF대명문화공장) (2관)’
→ 시설명: 예스24 스테이지(구. DCF대명문화공장) / 공연장: 2관

  • /prfstsPrfByFct → 31일 단위 분할 + 페이지네이션(최대 10페이지)

  • 매칭 조건: prfnmplc == 공연장명 AND 시설명 in prfnmfct

[STEP 3] 제작사별 상연횟수 합산 → Top 10
[STEP 4] Excel 저장 (result_YYYYMMDD_HHMMSS.xlsx)

데이터 수집 흐름

  1. /pblprfr API로 2025.01.01~2026.06.30 전체 공연 목록 수집 (2026 상반기와 기간이 겹치는 공연 포함)
  2. 기간 필터: 공연 종료일 ≥ 2026.01.01 AND 공연 시작일 ≤ 2026.06.30
  3. 전체 공연 대상 상세 조회 + 회차 계산 → 두 가지 집계 생성

핵심 함수

get_prfdtcnt(facility_name, hall_name, start, end) — 회차 조회

  • 분석 기간을 31일 단위로 분할 (API 최대 조회 범위 제한)
  • 각 구간마다 /prfstsPrfByFct 호출, 최대 10페이지 × 100건 페이지네이션
  • 매칭 조건: prfnmplc == hall_name AND facility_name in prfnmfct
  • prfcnt > 1이면 여러 공연 합산 데이터 → 경고 출력
  • 다음 구간 시작일 = 이전 구간 종료일 + 1일 (이중합산 방지)

extract_companies(db) — 제작사 추출

  • entrpsnmP / entrpsnmA / entrpsnmH / entrpsnmS 4개 필드 수집
  • 쉼표 구분 파싱 + 중복 제거
  • 4개 필드 모두 비어있으면 ['(제작사 미상)'] 반환

aggregate_top10(results, filtered=False) — 집계

  • filtered=True: openrun == 'N' AND child == 'N' 공연만 대상
  • 제작사별 prfdtcnt 합산 (한 공연에 여러 제작사가 있으면 각각에 동일 회차 부여)

출력

  • 파일명: result_YYYYMMDD_HHMMSS.xlsx (실행마다 새 파일)
  • 시트 1: Top10_전체 — 전체 공연 기준 제작사 top10
  • 시트 2: Top10_오픈런아동제외 — openrun=N, child=N 공연만 기준
  • 시트 3: 공연상세_전체 — 전체 공연 상세 데이터 (검증용)