KOBIS 오픈API 사용법: 박스오피스·영화 정보를 직접 조회하는 방법

영화 순위 기사를 보다 보면 "이 숫자는 어디서 나올까" 궁금해질 때가 있습니다. 국내 극장 박스오피스 데이터는 영화진흥위원회가 운영하는 영화관입장권통합전산망(KOBIS)에 모이며, 이 데이터 중 상당 부분을 누구나 오픈API로 조회할 수 있습니다. 이 글에서는 비개발자도 따라 할 수 있도록 키 발급부터 주소창 호출, 주요 파라미터, 간단한 코드 예시까지 차례로 정리합니다.

KOBIS 오픈API로 무엇을 조회할 수 있나

KOBIS 오픈API는 kobis.or.kr 의 오픈API 페이지(kobisopenapi)에서 안내하고 있습니다. 호출 방식은 REST와 SOAP을 지원하며, REST 방식은 주소 끝의 확장자로 XML 또는 JSON 응답을 고를 수 있습니다. 제공 서비스는 다음과 같습니다.

이 밖에 개발자를 위해 자바용 REST·SOAP 클라이언트(jar), 예제 웹 애플리케이션(war), 자바스크립트 REST 클라이언트(KobisOpenAPIRestService.js) 같은 자료도 내려받을 수 있습니다. 박스오피스 지표의 의미가 낯설다면 박스오피스 용어 사전을 먼저 읽어 보면 이해가 빠릅니다.

1단계: 키 발급받기

모든 요청에는 key 파라미터로 본인의 키를 넣어야 합니다. KOBIS 오픈API 사이트에 회원으로 로그인한 뒤 '키 발급/관리' 메뉴에서 키를 신청하면 됩니다. 발급 조건, 이용 목적 입력, 호출 횟수 제한 등 세부 사항은 사이트 안내를 확인하세요.

키는 비밀번호처럼 다루는 것이 좋습니다. 블로그나 깃허브 같은 공개된 곳에 키를 그대로 올리지 않도록 주의해야 합니다. 이 글의 예시에서도 실제 키 대신 발급받은키 라는 자리표시자를 사용합니다.

2단계: 브라우저 주소창으로 호출해 보기

가장 쉬운 방법은 브라우저 주소창에 URL을 직접 입력하는 것입니다. 일별 박스오피스의 기본 형식은 다음과 같습니다.

http://www.kobis.or.kr/kobisopenapi/webservice/rest/boxoffice/searchDailyBoxOfficeList.json?key=발급받은키&targetDt=20261010

? 뒤에는 파라미터를 이름=값 형태로 쓰고, 여러 개는 & 로 잇습니다. targetDt 는 조회할 날짜를 yyyymmdd 형식으로 넣는 필수값입니다. 주소 끝의 .json 을 .xml 로 바꾸면 같은 결과를 XML 형식으로 받을 수 있습니다.

일별 박스오피스의 주요 파라미터는 다음과 같습니다.

• itemPerPage: 결과 개수. 기본값이자 최댓값은 10입니다.
• multiMovieYn: Y는 다양성 영화, N은 상업 영화만 조회합니다. 생략하면 전체입니다.
• repNationCd: K는 한국 영화, F는 외국 영화만 조회합니다.
• wideAreaCd: 지역별 순위를 볼 때 쓰는 지역 코드입니다. 코드값은 공통코드 조회에서 comCode 를 "0105000000" 으로 넣어 확인합니다.

응답에는 박스오피스 종류(boxofficeType), 집계 기간(showRange)과 함께 영화별로 순번(rnum), 순위(rank), 전일 대비 순위 증감(rankInten) 등의 값이 담겨 있습니다.

3단계: 주간·주말 박스오피스와 공통코드

주간/주말 박스오피스는 주소의 요청 이름만 searchWeeklyBoxOfficeList 로 바꾸고, weekGb 파라미터로 기간을 정합니다.

http://www.kobis.or.kr/kobisopenapi/webservice/rest/boxoffice/searchWeeklyBoxOfficeList.json?key=발급받은키&targetDt=20261004&weekGb=0

주간 응답에는 연도와 주차를 나타내는 yearWeekTime(YYYYIW 형식)이 추가로 들어 있습니다. 공통코드 조회(searchCodeList)는 comCode 에 상위 코드를 넣으면 하위 코드 목록(fullCd, korNm, engNm)을 돌려줍니다. 예를 들어 국적 코드는 "2204", 영화 유형 코드는 "2201", 영화사 분류 코드는 "2601" 로 조회합니다.

4단계: 영화·영화사·영화인 정보 조회

영화목록(searchMovieList)은 movieNm(영화명), directorNm(감독명), openStartDt·openEndDt(개봉연도, YYYY), prdtStartYear·prdtEndYear(제작연도, YYYY), repNationCd, movieTypeCd 등으로 검색하며 curPage(기본 1)와 itemPerPage(기본 10)로 페이지를 나눕니다. 한글 검색어는 UTF-8로 전달되며, 브라우저 주소창에서는 보통 자동으로 변환됩니다.

검색 결과에서 얻은 movieCd 를 영화 상세정보(searchMovieInfo)에 넣으면 영화명(movieNm, movieNmEn, movieNmOg), 제작연도(prdtYear), 상영시간(showTm), 개봉일(openDt), 제작상태(prdtStatNm), 영화유형(typeNm), 제작국가(nations) 등을 확인할 수 있습니다.

같은 방식으로 영화사목록은 companyNm, ceoNm, companyPartCd 로 검색해 companyCd 를 얻고, 영화사 상세정보에서 분류(parts)와 필모그래피(filmos)를 봅니다. 영화인목록은 peopleNm, filmoNames 로 검색해 peopleCd 를 얻고, 영화인 상세정보에서 성별(sex), 대표 분야(repRoleNm), 참여 작품(filmos의 movieCd, movieNm, moviePartNm)을 확인합니다. 즉 "목록에서 코드를 찾고, 코드로 상세를 조회한다"는 흐름만 기억하면 됩니다.

간단한 JavaScript 예시

아래는 Node.js(내장 fetch 를 지원하는 버전)에서 일별 박스오피스 순위와 영화명을 출력하는 예시입니다. 키는 코드에 직접 쓰지 않고 환경 변수에서 읽도록 했습니다.

// boxoffice.mjs 로 저장하고, 환경 변수 KOBIS_KEY 에 발급받은키를 넣어 두고 실행합니다.
const key = process.env.KOBIS_KEY;
const targetDt = "20261010"; // 조회할 날짜(yyyymmdd)
const url = "http://www.kobis.or.kr/kobisopenapi/webservice/rest/boxoffice/searchDailyBoxOfficeList.json"
  + `?key=${key}&targetDt=${targetDt}`;

const res = await fetch(url);
const data = await res.json();
for (const movie of data.boxOfficeResult.dailyBoxOfficeList) {
  console.log(movie.rank, movie.movieNm, movie.rankInten);
}

웹 페이지의 JavaScript에서 바로 호출하는 방식은 키가 방문자에게 그대로 노출되고, 브라우저의 보안 정책 때문에 요청이 막힐 수도 있습니다. 공개 서비스를 만든다면 서버 쪽에서 API를 호출하고 결과만 화면에 전달하는 구조가 안전합니다.

정리

KOBIS 오픈API는 키 발급 후 정해진 주소 형식에 파라미터를 붙여 호출하는 단순한 구조입니다. 일별·주간 박스오피스는 targetDt 와 weekGb, 필터 파라미터로 원하는 범위를 정하고, 영화·영화사·영화인 정보는 목록에서 코드를 찾은 뒤 상세정보로 조회하면 됩니다. 받아 온 숫자를 어떻게 해석하는지는 영화관입장권통합전산망 박스오피스 데이터 읽는 법에서 이어서 다룹니다.