튜토리얼
영화관입장권통합전산망 오픈API 서비스를 이용해 간단한 애플리케이션을 개발하는 튜토리얼입니다.
튜토리얼 소개
- 본 튜토리얼은 오픈API 서비스 중 ‘일별 박스오피스’ 서비스를 이용하여 웹에 HTML로서출력하는 예제를 제공합니다.
- 이를 통해 본 오픈API 서비스를 어떤 절차와 방법으로 사용할 수 있는 지를 쉽게 이해할 수 있습니다.
- 튜토리얼에 사용된 개발환경은 다음과 같습니다.
- • JDK 1.6 (http://java.sun.com/)
- • Server: Tomcat v6.0 (http://tomcat.apache.org/)
- • Tool: Eclipse Java EE IDE for Web Developers (http://www.eclipse.org/)
- • Tag Lib : JSTL(JSP Standard Tag Library)
- • JSON 처리 : Jackson Java JSON-processor (https://github.com/FasterXML/jackson)
- 본 예제를 위해서는 J2EE 웹 어플리케이션에 대한 기본적인 이해와 JSON, XML 등에 대한 기본 지식이 필요합니다.
회원가입 & 로그인
키발급 관리
- • 키발급/관리 > 키발급/관리 메뉴로 이동하여 호출 시 사용할 키를 발급합니다.
- • '키 발급' 버튼을 클릭하여 사용목적, 해당 키의 관리명(다수의 키를 관리하기 편리하도록 자유롭게 입력)을 입력하고,
약관을 숙지 및 동의한 후 '키 발급'버튼을 누르면 새롭게 발급된 키를 확인할 수 있습니다. - • 발급받은 키는 기록해 두어 개발하고자 하는 어플리케이션에서 사용할 수 있도록 합니다.
REST 안내
- • OPEN API > 제공서비스 메뉴로 이동하여 제공되는 서비스를 확인하고, 개발에 사용할 서비스를 클릭해 인터페이스 정보를 확인합니다. 본 튜토리얼에서는 일별 박스오피스를 기준으로 하여 진행합니다.
- • 이클립스를 통해 프로젝트명을 임의로 입력(K_OpenAPI)하고 Context Root를 /로 하는
신규 Web Service Project를 생성합니다. (이하 웹 프로젝트) 
- • REST 방식의 서비스 클라이언트는 개발 환경에 맞도록 OPEN API > 제공서비스를 참조하여 HTTP 호출 객체를 구현하여 이용 가능합니다. 본 예제는 OPEN API>다운로드 페이지에서 제공하는 클라이언트(kobis-opcl-rest-v1.0.jar)를 이용하여 구성합니다.
- • 다운로드 받은 kobis-opcl-rest-v1.0.jar 파일을 웹 프로젝트의 build path(WEB-INF/lib)로 복사하여 호출에 이용합니다. (JAR 파일내에 소스를 참고할 수 있습니다.)
- • 라이브러리로 추가된 오픈API 클라이언트 객체인 KobisOpenAPIRestService 클래스의 서비스별 메소드는 다음과 같습니다.
- - getDailyBoxOffice: (박스오피스)일별 박스오피스
- - getWeeklyBoxOffice: (박스오피스)주간/주말 박스오피스
- - getComCodeList: (공통코드)공통코드 조회
- • 서비스 호출 결과 출력을 위한 restService.jsp 파일을 생성합니다.
- • restService.jsp의 import클래스 및 관련 정보는 다음과 같습니다.
- - 본 튜토리얼에서는 REST웹서비스의 JSON형식으로 반환된 결과값을 핸들링하기 위하여 JSON 라이브러리 ObjectMapper, JSTL등을 이용하였습니다. 관련 정보는 OPEN API > 튜토리얼페이지의 튜토리얼 소개 항목을 참고할 수 있습니다.
- • restService.jsp 파일에 발급받은 키로 KobisOpenAPIRestService 클래스를 생성합니다.
본 예제에서는 테스트용 KEY(430156241533f1d058c603178cc3ca0e)를 이용합니다. 
- • 일별 박스오피스 호출 메소드의 파라메터는 다음과 같습니다.
- - KobisOpenAPIRestService.getDailyBoxOffice(boolean isJson, String targetDt, String itemPerPage,String multiMovieYn, String repNationCd, String wideAreaCd)
- - isJson : true일 경우 JSON타입으로 웹 서비스 조회 결과를 반환, false일 경우 XML타입으로 반환 합니다.
OPEN API > 제공서비스에서 각 각 타입별 호출 결과를 확인할 수 있습니다. - - 그 외 각 파라메터의 상세 내용은 OPEN API > 제공서비스의 일별 박스오피스 요청 인터페이스를 참고하여 호출합니다.
- • 요청 인터페이스
-
요청 변수 값 설명 key 문자열(필수) 발급받은키 값을 입력합니다. targetDt 문자열(필수) 조회하고자 하는 날짜를 yyyymmdd 형식으로 입력합니다. itemPerPage 문자열 결과 ROW의 개수를 지정합니다. (default: "10", 최대 : "10") multiMovieYn 문자열 다양성 영화/상업영화를 구분지어 조회할 수 있습니다.
"Y" : 다양성 영화 "N" 상업영화 (default: 전체)repNationCd 문자열 한국/외국 영화별로 조회할 수 있습니다.
"K" : 한국영화 "F" 외국영화 (default: 전체)WideAreaCd 문자열 상영지역별로 조회할 수 있으며, 지역코드는 공통코드 조회 서비스에서
"0105000000"로서 조회된 지역코드입니다. (default: 전체) - • 앞서 호출한 일별 박스오피스 REST 웹서비스의 JSON형식으로 반환된 결과를 이용하여 HTML 로 보여주는 예제는 아래와 같습니다. 결과 컬럼의 상세 내용은 OPEN API > 제공서비스의 일별 박스오피스 응답구조에서 확인 가능합니다.
- • 응답 구조
-
응답 필드 값 설명 boxofficeType 문자열 박스오피스의 종류를 출력합니다. showRange 문자열 박스오피스의 조회일자를 출력합니다. rnum 문자열 순번을 출력합니다. rank 문자열 해당일자의 박스오피스 순위를 출력합니다. rankInten 문자열 전일대비 순위의 증감분을 출력합니다. rankOldAndNew 문자열 랭킹에 신규 진입여부를 출력합니다. "OLD": 기존, "NEW": 신규 movieCd 문자열 영화의 대표코드를 출력합니다. movieNm 문자열 영화명(국문)을 출력합니다. openDt 문자열 영화의 개봉일을 출력합니다. salesAmt 문자열 해당일의 매출액을 출력합니다. salesShare 문자열 해당일자 상영작의 매출총액 대비 해당 영화이 매출비율을 출력합니다. salesInten 문자열 전일 대비 매출액 증감분을 출력합니다. salesChange 문자열 전일 대비 매출액 증감비율을 출력합니다. salesAcc 문자열 누적매출액을 출력합니다. audiCnt 문자열 해당일의 관객수를 출력합니다. audiInten 문자열 전일 대비 관객수 증감분을 출력합니다. audiChange 문자열 전일 대비 관객수 증감비율을 출력합니다. audiAcc 문자열 누적관객수를 출력합니다. scrnCnt 문자열 해당일자에 상영한 스크린수를 출력합니다. showCnt 문자열 해당일자에 상영된 횟수를 출력합니다. - • 신규 서버(TOMCAT)을 생성하여 해당 웹 프로젝트를 시작하고 restService.jsp 파일을 호출하여 일별 박스오피스의 호출 결과를 확인합니다. (URL: http://localhost:8080/restService.jsp?targetDt=20120101&itemPerPage=10)
SOAP 안내
- • OPEN API > 제공서비스 메뉴로 이동하여 제공되는 서비스를 확인하고 개발에 사용할 서비스를 클릭하여 인터페이스 정보를 확인합니다. 본 튜토리얼에서는 일별 박스오피스를 기준으로 하여 진행합니다.
- • 이클립스를 통해 프로젝트명을 임의로 입력(K_OpenAPI)하고 Context Root를 /로 하는
신규 Web Service Project를 생성합니다. (이하 웹 프로젝트) - • SOAP 방식의 서비스는 WSDL을 통해 개발환경에 맞는 클라이언트를 구현하여 이용 가능하며, KOBIS OPEN API 에서 제공하는 각 서비스별 WSDL URL은 다음과 같습니다.
- - 박스오피스: http://www.kobis.or.kr/kobisopenapi/webservice/soap/boxoffice?wsdl
- - 공통코드: http://www.kobis.or.kr/kobisopenapi/webservice/soap/code?wsdl
- • 본 예제에서는 OPEN API > 다운로드 페이지에서 제공하는 클라이언트(kobis-opcl-soap-v1.0.jar)를 이용하여 구성합니다.
예제를 위한 클라이언트 생성은 Apache에서 제공하는 wsdl to java(http://cxf.apache.org/)를 이용하였습니다. - • 다운로드 받은 kobis-opcl-soap-v1.0.jar 파일을 웹 프로젝트의 build path(WEB-INF/lib)로 복사하여 호출에 이용합니다.
(JAR 파일내에 소스를 참고할 수 있습니다.) 
- • 라이브러리로 추가된 오픈API 클라이언트 객체인 KobisOpenAPIRestService 클래스의 서비스별 메소드는 다음과 같습니다.
- - BoxOfficeAPIServiceImplService: 박스오피스(일별 박스오피스, 주간/주말 박스오피스)
- - CodeAPIServiceImplService: 공통코드
- • 서비스 호출 결과 출력을 위한 soapService.jsp 파일을 생성합니다.
- • soapService.jsp의 import클래스 및 관련 정보는 다음과 같습니다.
- - 본 튜토리얼에서는 SOAP웹서비스의 결과값을 핸들링하기 위하여 JSTL등을 이용하였습니다.
관련 정보는 OPEN API > 튜토리얼 메뉴의 튜토리얼 소개 항목을 참고할 수 있습니다.
- - 본 튜토리얼에서는 SOAP웹서비스의 결과값을 핸들링하기 위하여 JSTL등을 이용하였습니다.
- • soapService.jsp 파일에 발급받은 키를 이용하여 일별 박스오피스 SOAP웹서비스를 위한 클라이언트를 호출합니다.
호출 파라메터는 다음과 같습니다. 본 예제에서는 테스트용 KEY(430156241533f1d058c603178cc3ca0e)를 이용합니다.- - BoxOfficeAPIServiceImplService().getBoxOfficeAPIServiceImplPort().searchDailyBoxOfficeList
(key,targetDt,itemPerPage,multiMovieYn,repNationCd,wideAreaCd) - - key: 테스트용 KEY(430156241533f1d058c603178cc3ca0e)를 입력합니다.
- - 그 외 각 파라메터의 상세 내용은 OPEN API > 제공서비스의 일별 박스오피스 요청 인터페이스를 참고하여 호출합니다.
- - BoxOfficeAPIServiceImplService().getBoxOfficeAPIServiceImplPort().searchDailyBoxOfficeList
- • 요청 인터페이스
-
요청 변수 값 설명 key 문자열(필수) 발급받은키 값을 입력합니다. targetDt 문자열(필수) 조회하고자 하는 날짜를 yyyymmdd 형식으로 입력합니다. itemPerPage 문자열 결과 ROW의 개수를 지정합니다. (default: "10", 최대 : "10") multiMovieYn 문자열 다양성 영화/상업영화를 구분지어 조회할 수 있습니다.
"Y" : 다양성 영화 "N" 상업영화 (default: 전체)repNationCd 문자열 한국/외국 영화별로 조회할 수 있습니다.
"K" : 한국영화 "F" 외국영화 (default: 전체)WideAreaCd 문자열 상영지역별로 조회할 수 있으며, 지역코드는 공통코드 조회 서비스에서
"0105000000"로서 조회된 지역코드입니다. (default: 전체) - • KOBIS OPEN API에서 제공하는 SOAP 웹서비스의 결과 반환 구조는 해당 호출 메소드의 반환 클래스를 따르며, 일별 박스오피스의 경우 제공된 클라이언트 클래스 중 DailyBoxOfficeResult 클래스로 반환됩니다.
- - 멤버변수: String boxofficeType, List dailyBoxOfficeList(조회결과 리스트), String showRange
- - 메소드: getBoxoffType(), getDailyBoxOfficeList() 등
- • 앞서 호출한 일별 박스오피스 SOAP웹서비스의 호출 결과값을 이용하여 HTML로 출력하는 예제는 아래와 같습니다.
결과 컬럼의 상세 내용은 OPEN API > 제공서비스의 일별 박스오피스 응답구조에서 확인 가능합니다. 
- • 응답 구조
-
응답 필드 값 설명 boxofficeType 문자열 박스오피스의 종류를 출력합니다. showRange 문자열 박스오피스의 조회일자를 출력합니다. rnum 문자열 순번을 출력합니다. rank 문자열 해당일자의 박스오피스 순위를 출력합니다. rankInten 문자열 전일대비 순위의 증감분을 출력합니다. rankOldAndNew 문자열 랭킹에 신규 진입여부를 출력합니다. "OLD": 기존, "NEW": 신규 movieCd 문자열 영화의 대표코드를 출력합니다. movieNm 문자열 영화명(국문)을 출력합니다. openDt 문자열 영화의 개봉일을 출력합니다. salesAmt 문자열 해당일의 매출액을 출력합니다. salesShare 문자열 해당일자 상영작의 매출총액 대비 해당 영화이 매출비율을 출력합니다. salesInten 문자열 전일 대비 매출액 증감분을 출력합니다. salesChange 문자열 전일 대비 매출액 증감비율을 출력합니다. salesAcc 문자열 누적매출액을 출력합니다. audiCnt 문자열 해당일의 관객수를 출력합니다. audiInten 문자열 전일 대비 관객수 증감분을 출력합니다. audiChange 문자열 전일 대비 관객수 증감비율을 출력합니다. audiAcc 문자열 누적관객수를 출력합니다. scrnCnt 문자열 해당일자에 상영한 스크린수를 출력합니다. showCnt 문자열 해당일자에 상영된 횟수를 출력합니다. - • 신규 서버(TOMCAT)을 생성하여 해당 웹 프로젝트를 시작하고 soapService.jsp 파일을 호출하여 일별 박스오피스의 호출 결과를 확인합니다. (URL: http://localhost:8080/soapService.jsp?targetDt=20120101&itemPerPage=10)
문의사항
- • 이용안내 > FAQ 메뉴에서 관련 정보를 검색합니다. 찾고자 하는 내용이 없는 경우 오픈 API 홈페이지에 로그인하여
이용안내 > FAQ 메뉴의 ‘질문등록’ 버튼을 클릭하여 문의사항을 입력합니다. 
- • 관리자의 처리 후 회원가입 시 입력한 메일주소로 답변내용이 전송됩니다.
Copyright (c) 2011. Korean Film Council. All rights reserved
(48058) 부산광역시 해운대구 수영강변대로 130(우동) l 고객센터: 02-6261-6573 l 이용시간: 09:00 ~ 18:00(평일) l E-mail: openapimaster@kofic.or.kr