@coldsurf/tickets

@coldsurf/tickets

KOPIS(공연예술통합전산망) OpenAPI를 활용한 공연 정보 CLI 및 TypeScript SDK입니다.

터미널에서 공연 목록 조회, 상세 정보 확인을 간편하게 할 수 있고, TypeScript 프로젝트에서 SDK로 import하여 사용할 수도 있습니다.

설치

# CLI로 사용
npm install -g @coldsurf/tickets

# SDK로 사용 (프로젝트 의존성)
pnpm add @coldsurf/tickets

또는 npx로 바로 실행:

npx @coldsurf/tickets find --startDate 20250101

KOPIS API Key 발급

이 CLI를 사용하려면 KOPIS OpenAPI 인증키가 필요합니다.

• 공연예술통합전산망 OpenAPI 페이지에서 회원가입
• OpenAPI 사용 신청 후 인증키 발급
• 환경변수 또는 --apiKey 옵션으로 전달

export KOPIS_KEY="발급받은_API_KEY"

사용법

# 공연 목록 조회
tickets find --startDate 20250101
tickets find --startDate 20250101 --category GGGA --area 11

# 공연 상세 조회
tickets detail PF123456

# 공연시설 목록 조회
tickets venue --name 예술의전당

# 공연시설 상세 조회
tickets venue-detail FC001247

# 기획/제작사 목록 조회
tickets promoter --name 국악단

# 수상작 목록 조회
tickets award --startDate 20160101 --endDate 20161231

# 축제 목록 조회
tickets festival --startDate 20250101 --endDate 20251231

# 원·창작자 목록 조회
tickets creator --startDate 20250101 --endDate 20251231

# JSON 출력 (모든 커맨드 공통)
tickets find --startDate 20250101 --format json

전체 옵션, 코드표 등 상세 문서는 GitHub README를 참고하세요.

SDK 사용법

TypeScript/JavaScript 프로젝트에서 직접 import하여 사용할 수 있습니다.

import {
  createKopisClient,
  KOPIS_CATEGORIES,
  KOPIS_AREAS,
} from '@coldsurf/tickets'

const client = createKopisClient(process.env.KOPIS_KEY!)

// 서울 대중음악 공연 조회
const performances = await client.getPerformanceList({
  startDate: '20260101',
  endDate: '20261231',
  category: KOPIS_CATEGORIES.대중음악,
  area: KOPIS_AREAS.서울,
  rows: 20,
})

// 공연 상세 조회
const detail = await client.getPerformanceDetail(performances[0].id)

// 공연장 검색
const venues = await client.getVenueList({
  name: '예술의전당',
})

주요 API

메서드	설명
getPerformanceList(params)	공연 목록 조회
getPerformanceDetail(id)	공연 상세 조회
getVenueList(params)	공연시설 목록 조회
getVenueDetail(id)	공연시설 상세 조회
getPromoterList(params)	기획/제작사 목록 조회
getAwardList(params)	수상작 목록 조회
getFestivalList(params)	축제 목록 조회
getCreatorList(params)	원·창작자 목록 조회

Export 목록

분류	Export
클라이언트	createKopisClient, KopisApiError
클라이언트 타입	KopisClient
응답 타입	KopisPerformance, KopisPerformanceDetail, KopisTicketInfo, KopisVenue, KopisVenueDetail, KopisHall, KopisPromoter, KopisAwardPerformance, KopisFestivalPerformance, KopisCreatorPerformance
파라미터 타입	ListParams, VenueListParams, PromoterListParams
코드 타입	KopisCategoryCode, KopisAreaCode, KopisPerformStateCode, KopisVenueTypeCode
상수	KOPIS_CATEGORIES, KOPIS_AREAS, KOPIS_PERFORM_STATES, KOPIS_VENUE_TYPES, KOPIS_SUB_AREAS

데이터 출처

이 도구는 KOPIS 공연예술통합전산망 (예술경영지원센터)에서 제공하는 OpenAPI 데이터를 사용합니다.

라이선스

MIT