Startseite Erkunden Hilfe
Anmelden
admin
/
crawler
1
0
Fork 0
Dateien Issues 0 Pull-Requests 0 Wiki
Branch: main
Branches Tags
crawler
/
docs
/
KOBIS-영화API.md

KOBIS-영화API.md 16 KB
Permalink Verlauf Originalformat

KOBIS 영화진흥위원회 OpenAPI 정리

영화진흥위원회(KOBIS) 통합전산망 오픈API 요약 문서입니다. crawler 프로젝트에서 사용하는 영화 관련 API 9종을 한 곳에 정리했습니다.

원본: docs/*.txt (KOBIS 공식 API 명세)

공통 사항

  • 호출 방식: REST / SOAP 선택 가능 (본 문서는 REST 기준)
  • 응답 형식: URI 확장자로 구분 — .xml 또는 .json
  • HTTP 메서드: GET
  • REST 베이스 URL: http://www.kobis.or.kr/kobisopenapi/webservice/rest
  • SOAP 베이스 URL: http://www.kobis.or.kr/kobisopenapi/webservice/soap
  • 인증: 모든 요청에 발급키 key 파라미터 필수
  • 예시 URL의 key=82ca741a2844c5c180a208137bb92bd7 는 KOBIS 공식 문서의 샘플 키입니다. 실제 호출 시 발급받은 키로 교체하세요.

엔드포인트 한눈에 보기

구분 API Operation REST 경로 (.json / .xml)
박스오피스 일별 박스오피스 searchDailyBoxOfficeList /boxoffice/searchDailyBoxOfficeList
박스오피스 주간/주말 박스오피스 searchWeeklyBoxOfficeList /boxoffice/searchWeeklyBoxOfficeList
영화 영화 목록 searchMovieList /movie/searchMovieList
영화 영화 상세 searchMovieInfo /movie/searchMovieInfo
영화사 영화사 목록 searchCompanyList /company/searchCompanyList
영화사 영화사 상세 searchCompanyInfo /company/searchCompanyInfo
영화인 영화인 목록 searchPeopleList /people/searchPeopleList
영화인 영화인 상세 searchPeopleInfo /people/searchPeopleInfo
공통 공통코드 조회 searchCodeList /code/searchCodeList

자주 쓰는 상위코드 (comCode, 공통코드 조회 API로 조회)

comCode 용도 사용하는 API
2201 영화유형코드 영화 목록 (movieTypeCd)
2204 국적코드 영화 목록 (repNationCd)
2601 영화사 분류코드 영화사 목록 (companyPartCd)
0105000000 상영지역코드 박스오피스 (wideAreaCd)

1. 일별 박스오피스 — searchDailyBoxOfficeList

특정 일자 상영작들의 박스오피스 정보를 영화구분(다양성/상업), 한국/외국, 상영지역 등으로 조회.

  • REST: GET /boxoffice/searchDailyBoxOfficeList.json (또는 .xml)
  • SOAP: .../soap/boxoffice · Operation searchDailyBoxOfficeList

요청 파라미터

변수 필수 설명
key ✅ 발급받은 키 값
targetDt ✅ 조회 날짜 yyyymmdd
itemPerPage 결과 ROW 개수 (default 10, 최대 10)
multiMovieYn Y: 다양성 영화 / N: 상업영화 (default 전체)
repNationCd K: 한국영화 / F: 외국영화 (default 전체)
wideAreaCd 상영지역코드(공통코드 0105000000) (default 전체)

응답 필드

필드 설명
boxofficeType 박스오피스 종류
showRange 박스오피스 조회 일자
rnum 순번
rank 해당일자 박스오피스 순위
rankInten 전일 대비 순위 증감분
rankOldAndNew 신규 진입 여부 (OLD 기존 / NEW 신규)
movieCd 영화 대표코드
movieNm 영화명(국문)
openDt 개봉일
salesAmt 해당일 매출액
salesShare 해당일 상영작 매출총액 대비 매출 비율
salesInten 전일 대비 매출액 증감분
salesChange 전일 대비 매출액 증감 비율
salesAcc 누적 매출액
audiCnt 해당일 관객수
audiInten 전일 대비 관객수 증감분
audiChange 전일 대비 관객수 증감 비율
audiAcc 누적 관객수
scrnCnt 해당일자 상영 스크린수
showCnt 해당일자 상영 횟수

예시

http://kobis.or.kr/kobisopenapi/webservice/rest/boxoffice/searchDailyBoxOfficeList.json?key={KEY}&targetDt=20120101

2. 주간/주말 박스오피스 — searchWeeklyBoxOfficeList

특정 일자가 속한 주차의 주간/주말/주중 상영작 박스오피스 정보를 조회.

  • REST: GET /boxoffice/searchWeeklyBoxOfficeList.json (또는 .xml)
  • SOAP: .../soap/boxoffice · Operation searchWeeklyBoxOfficeList

요청 파라미터

변수 필수 설명
key ✅ 발급받은 키 값
targetDt ✅ 조회 날짜 yyyymmdd
weekGb 0: 주간(월~일) / 1: 주말(금~일, default) / 2: 주중(월~목)
itemPerPage 결과 ROW 개수 (default 10, 최대 10)
multiMovieYn Y: 다양성 영화 / N: 상업영화 (default 전체)
repNationCd K: 한국영화 / F: 외국영화 (default 전체)
wideAreaCd 상영지역코드(공통코드 0105000000) (default 전체)

응답 필드

일별 박스오피스와 동일하며, 아래 필드가 추가됩니다.

필드 설명
boxofficeType 박스오피스 종류
showRange 대상 상영기간
yearWeekTime 조회일자에 해당하는 연도·주차 (YYYYIW)
rnum 순번
rank 박스오피스 순위
rankInten 전일 대비 순위 증감분
rankOldAndNew 신규 진입 여부 (OLD / NEW)
movieCd 영화 대표코드
movieNm 영화명(국문)
openDt 개봉일
salesAmt / salesShare / salesInten / salesChange / salesAcc 매출액 / 점유율 / 증감분 / 증감율 / 누적
audiCnt / audiInten / audiChange / audiAcc 관객수 / 증감분 / 증감율 / 누적
scrnCnt / showCnt 상영 스크린수 / 상영 횟수

예시

http://kobis.or.kr/kobisopenapi/webservice/rest/boxoffice/searchWeeklyBoxOfficeList.json?key={KEY}&targetDt=20120101

3. 영화 목록 — searchMovieList

영화명, 감독명 등의 조건으로 영화 목록을 조회.

  • REST: GET /movie/searchMovieList.json (또는 .xml)
  • SOAP: .../soap/movie · Operation searchMovieList

요청 파라미터

변수 필수 설명
key ✅ 발급받은 키 값
curPage 현재 페이지 (default 1)
itemPerPage 결과 ROW 개수 (default 10)
movieNm 영화명으로 조회 (UTF-8)
directorNm 감독명으로 조회 (UTF-8)
openStartDt 조회 시작 개봉연도 YYYY
openEndDt 조회 종료 개봉연도 YYYY
prdtStartYear 조회 시작 제작연도 YYYY
prdtEndYear 조회 종료 제작연도 YYYY
repNationCd 국적코드(공통코드 2204), N개 가능 (default 전체)
movieTypeCd 영화유형코드(공통코드 2201), N개 가능 (default 전체)

응답 필드

필드 설명
movieCd 영화코드
movieNm 영화명(국문)
movieNmEn 영화명(영문)
prdtYear 제작연도
openDt 개봉일
typeNm 영화유형
prdtStatNm 제작상태
nationAlt 제작국가(전체)
genreAlt 영화장르(전체)
repNationNm 대표 제작국가명
repGenreNm 대표 장르명
directors › peopleNm 영화감독(배열) › 감독명
companys › companyCd, companyNm 제작사(배열) › 제작사 코드, 제작사명

예시

http://kobis.or.kr/kobisopenapi/webservice/rest/movie/searchMovieList.json?key={KEY}

4. 영화 상세 — searchMovieInfo

영화코드로 영화 상세정보를 조회.

  • REST: GET /movie/searchMovieInfo.json (또는 .xml)
  • SOAP: .../soap/movie · Operation searchMovieInfo

요청 파라미터

변수 필수 설명
key ✅ 발급받은 키 값
movieCd ✅ 영화코드

응답 필드

기본 정보

필드 설명
movieCd 영화코드
movieNm / movieNmEn / movieNmOg 영화명 국문 / 영문 / 원문
prdtYear 제작연도
showTm 상영시간
openDt 개봉연도
prdtStatNm 제작상태명
typeNm 영화유형명

중첩 구조 (배열)

그룹 하위 필드 설명
nations nationNm 제작국가명
(genre) genreNm 장르명
directors peopleNm, peopleNmEn 감독명 / 감독명(영문)
actors peopleNm, peopleNmEn, cast, castEn 배우명 / 배우명(영문) / 배역명 / 배역명(영문)
showTypes showTypeGroupNm, showTypeNm 상영형태 구분 / 상영형태명
audits auditNo, watchGradeNm 심의번호 / 관람등급 명칭
companys companyCd, companyNm, companyNmEn, companyPartNm 영화사 코드 / 명 / 명(영문) / 참여 분야명
staffs peopleNm, peopleNmEn, staffRoleNm 스텝명 / 스텝명(영문) / 스텝역할명

예시

http://www.kobis.or.kr/kobisopenapi/webservice/rest/movie/searchMovieInfo.json?key={KEY}&movieCd=20124079

5. 영화사 목록 — searchCompanyList

영화사명, 대표자명 등의 조건으로 영화사 목록을 조회.

  • REST: GET /company/searchCompanyList.json (또는 .xml)
  • SOAP: .../soap/company · Operation searchCompanyList

요청 파라미터

변수 필수 설명
key ✅ 발급받은 키 값
curPage 현재 페이지 (default 1)
itemPerPage 결과 ROW 개수 (default 10)
companyNm 영화사명으로 조회
ceoNm 대표자명으로 조회
companyPartCd 분류코드(공통코드 2601), N개 가능 (default 전체)

응답 필드

필드 설명
companyCd 영화사 코드
companyNm / companyNmEn 영화사명 / 영화사명(영문)
companyPartNames 영화사 분류
ceoNm 대표자명
filmoNames 필모리스트

예시

http://kobis.or.kr/kobisopenapi/webservice/rest/company/searchCompanyList.json?key={KEY}

6. 영화사 상세 — searchCompanyInfo

영화사코드로 영화사 상세정보를 조회.

  • REST: GET /company/searchCompanyInfo.json (또는 .xml)
  • SOAP: .../soap/company · Operation searchCompanyInfo

요청 파라미터

변수 필수 설명
key ✅ 발급받은 키 값
companyCd 영화사코드

응답 필드

그룹 필드 설명
기본 companyCd 영화사 코드
기본 companyNm / companyNmEn 영화사명 / 영화사명(영문)
기본 ceoNm 대표자명
parts companyPartNm 영화사 분류명
filmos movieCd, movieNm, companyPartNm 참여 영화코드 / 참여 영화명 / 참여 분류명

예시

http://www.kobis.or.kr/kobisopenapi/webservice/rest/company/searchCompanyInfo.json?key={KEY}&companyCd=20122497

7. 영화인 목록 — searchPeopleList

영화인명, 필모그래피 조건으로 영화인 목록을 조회.

  • REST: GET /people/searchPeopleList.json (또는 .xml)
  • SOAP: .../soap/people · Operation searchPeopleList

요청 파라미터

변수 필수 설명
key ✅ 발급받은 키 값
curPage 현재 페이지 (default 1)
itemPerPage 결과 ROW 개수 (default 10)
peopleNm 영화인명으로 조회
filmoNames 필모리스트로 조회

응답 필드

필드 설명
peopleCd 영화인 코드
peopleNm / peopleNmEn 영화인명 / 영화인명(영문)
repRoleNm 분야
filmoNames 필모리스트

예시

http://kobis.or.kr/kobisopenapi/webservice/rest/people/searchPeopleList.json?key={KEY}

8. 영화인 상세 — searchPeopleInfo

영화인코드로 영화인 상세정보를 조회.

  • REST: GET /people/searchPeopleInfo.json (또는 .xml)
  • SOAP: .../soap/people · Operation searchPeopleInfo > ⚠️ SOAP Operation 표기가 원문에서 searchpeopleInfo(소문자 p)로 되어 있음 — SOAP 사용 시 주의.

요청 파라미터

변수 필수 설명
key ✅ 발급받은 키 값
peopleCd 영화인코드

응답 필드

그룹 필드 설명
기본 peopleCd 영화인 코드
기본 peopleNm / peopleNmEn 영화인명 / 영화인명(영문)
기본 sex 성별
기본 repRoleNm 영화인 분류명
filmos movieCd, movieNm, moviePartNm 참여 영화코드 / 참여 영화명 / 참여분야
기본 homepages 관련 URL

예시

http://kobis.or.kr/kobisopenapi/webservice/rest/people/searchPeopleInfo.json?key={KEY}&peopleCd=20164556

9. 공통코드 조회 — searchCodeList

특정 상위 코드값을 조건으로 하위 코드정보를 조회. (국적/유형/분류/지역 코드 등)

  • REST: GET /code/searchCodeList.json (또는 .xml)
  • SOAP: .../soap/code · Operation searchCodeList

요청 파라미터

변수 필수 설명
key ✅ 발급받은 키 값
comCode ✅ 조회하고자 하는 상위 코드 (예: 2204, 2201, 2601, 0105000000)

응답 필드

필드 설명
fullCd 상위코드
korNm 코드 국문명
engNm 코드 영문명

예시

http://kobis.or.kr/kobisopenapi/webservice/rest/code/searchCodeList.json?key={KEY}&comCode=0105000000

구현 현황 (crawler ↔ movie 사이트) — 2026-07-22 기준

KOBIS API crawler 구현 crawler 엔드포인트 movie 사이트 사용처
일별 박스오피스 ✅ GET /movie/searchDailyBoxOfficeList /movie/rank (평일)
주간/주말 박스오피스 ✅ GET /movie/searchWeeklyBoxOfficeList /movie/rank (주말)
영화 목록 ✅ GET /movie/searchMovieList + /cron/list (수집 전용 — 검색 페이지는 tb_movie 직조회)
영화 상세 ✅ GET /movie/searchMovieInfo + /cron/info /movie/rank/{id}, /movie/search/{id}
영화사 목록 ✅ GET /company/searchCompanyList /movie/company
영화사 상세 ✅ GET /company/searchCompanyInfo /movie/company/{cd}
영화인 목록/상세 ❌ 미구현 - -
공통코드 조회 ❌ 미구현 - -
  • 영화사 API는 DB 캐싱 없이 KOBIS 프록시로 동작한다 (tb_company 테이블 없음).
  • KOBIS는 오류도 HTTP 200 + faultInfo로 반환하므로 crawler model/kobis.go의 checkFault()가 error로 승격한다 (→ HTTP 400).

키 운영 정책

  • 키는 crawler config/movie.json(cron 수집용)과 movie config/constants.php KOBIS_API_1~3(사이트 → crawler 전달용) 양쪽에 동일하게 유지해야 한다.
  • apiKey_3 자리의 82ca741a...는 KOBIS 공식 문서 샘플 키로 무효(320010) — 실제 사용 시 KOBIS 계정에서 발급한 키로 교체할 것. 사이트는 KOBIS_API_1만 실제 사용한다.
  • 키당 일 호출 한도가 있으므로 cron 수집 시 ?key=1|2 파라미터로 분산한다.

운영 절차 (수집)

  1. 박스오피스(일별/주간): 사이트 조회 시 on-demand 수집 — 별도 스케줄 불필요. 키만 유효하면 날짜별 첫 조회 때 tb_movie_daily/weekly에 적재된다.
  2. 영화 목록/기본정보/상세: GET /cron/list?key=1 → GET /cron/info?key=2 → GET /cron/detail 순서로 주기 실행 (마지막 수집 페이지는 log/kobis/page.txt에 저장, 목록은 최신순 정렬이라 전량 스윕은 page.txt를 1로 리셋 후 실행).
    • /cron/info는 단건 실패 시 해당 영화만 건너뛰고(failedCodes로 리포트) 연속 오류 10회면 중단한다(무효 키·쿼터 초과 보호). 실패 원인은 log/kobis/error.txt에서 확인.
    • 2026-07-22 기준 백로그: tb_movie 101,810 vs KOBIS 120,000(목록 ~18k편 부족), 기본정보 미수집 ~31k건 — info 수집은 키당 일 3,000회 제한으로 수일 분산 필요.
  3. 누적 매출/관객(tb_movie_detail.sale_acc/audi_acc) 수집기(c2)는 주석 처리 상태 — 재활성화 시 searchMovieDtl.do sType=stat 셀렉터 재검증 필요.