일치검색 표제어 전체
검색
특수문자입력기 ㅣ 도움말
홈 > OpenAPI > OpenAPI소개
역대인물 OpenAPI

1. 역대인물 OpenAPI 소개

한국학중앙연구원은 인물정보를 자유롭게 이용할 수 있도록 OpenAPI로 제공합니다. OpenAPI 이용을 위해서는 먼저 사용신청을 해야 합니다. 신청이 완료되면 담당자 검토 후 이메일로 인증키를 발송해 드립니다.

OpenAPI 서비스 신청하기

2. OpenAPI 이용 가이드

(1) 요청 주소

인증키를 이용하여 아래와 같은 형식으로 서비스를 호출할 수 있습니다.

요청 URL : http://people.aks.ac.kr/openapi
http://people.aks.ac.kr/openapi?key={인증키}&query={검색어}&category={검색 범위}&startPage={시작 페이지}&pageSize={페이지 크기}&startHilightTag={하이라이트 시작 태그}&endHilightTag={하이라이트 종료 태그}&format={출력 형식}
요청 URL 예시
역대인물 OpenAPI의 요청 파라메터는 UTF-8 인코딩을 사용해야 합니다.
http://people.aks.ac.kr/openapi?key=857f940ccd144a87ba118e0d4499e331&query=이순신&category=total&startPage=1&pageSize=50&startHilightTag=<b>&endHilightTag=</b>&format=xml
위와 같이 역대인물 OpenAPI를 요청 예를 UTF-8 URL로 인코딩하면 아래와 같습니다.
http://people.aks.ac.kr/openapi?key=857f940ccd144a87ba118e0d4499e331&query=%ec%9d%b4%ec%88%9c%ec%8b%a0&category=total&startPage=1&pageSize=50&startHilightTag=%3cb%3e&endHilightTag=%3c%2fb%3e&format=xml

(2) 요청 파라메터

요청변수 값 설명
key string (필수) Open-API 서비스 신청시 발급받은 인증키를 입력합니다.
query string (필수) 검색할 질의어를 입력합니다. UTF-8 인코딩이 필요합니다.
category (query의 속성) string (선택) 검색할 범위를 지정합니다.
  • * total : 통합인물메타 전체 검색(default)
  • * name_eq : 이름 일치 검색(이순으로 시작하는 인물 중에 일치로 하고 싶은 경우 이순*로 검색)
  • * name : 이름 낱자 검색(검색어 이순 시 김이순, 이순, 이순신도 검색됨)
  • * ex_name_eq : 확장 인명 일치(자,호,시호,묘호등 확장일치 검색)
  • * ex_name : 확장 인명 낱자 검색
  • * uci : 인물 UCI 코드 검색(검색어가 uci코드 임)
  • * pplid : 인물 고유 ID검색
startHilightTag string (선택) 검색어에 대한 하이라이트 시작 태그로 XML형식인 경우만 지원합니다.
endHilightTag string (선택) 검색어에 대한 하이라이트 종료 태그로 XML형식인 경우만 지원합니다.
startPage Int (선택) 검색된 결과의 시작 페이지 (default : 1)
pageSize Int (선택) 검색된 결과 페이지 크기 (default : 20)
format String(선택) Xml 또는 JSON (default xml)

(3) 검색 결과

변수 타입 설명
referUrl string OpenAPI 호출자 URL
conditions query string 검색어
category string 검색 범위
startPage int 시작 페이지
pageSize int 페이지 크기
startHilightTag string 하이라이트 시작 태그
endHilightTag string 하이라이트 종료 태그
format string 출력형식(xml 또는 json)
resultInfo success string 검색 오류 여부(성공:true, 실패:false)
message string 오류 메세지
totalCount int 검색 결과 건수
resultSize int 검색 결과 목록 갯수
resultSet list total_no int 전체 검색 결과에서의 순번
      no int 결과 목록에서의 순번
pplid string 역대인물 고유 아이디
uci string 역대인물 UCI
title string 자료명(대표 인물명)
document string 역대인물 상세 메타데이터 정보 역대인물 통합인명메타 DTD 참조
출력예시 
<?xml version="1.0" encoding="UTF-8"?>
<aksPeopleAPI>
   <referUrl>http://localhost:8080/openapi/testClient1.jsp</referUrl>
   <conditions>
      <query><![CDATA[세종]]></query>
      <category>name_eq</category>
      <startPage>1</startPage>
      <pageSize>50</pageSize>
      <startHilightTag><![CDATA[]]></startHilightTag>
      <endHilightTag><![CDATA[]]></endHilightTag>
      <format>xml</format>
   </conditions>
   <resultInfo>
      <success>true</success>
      <message><![CDATA[]]></message>
      <totalCount>1</totalCount>
      <resultSize>1</resultSize>
      <resultSet>
         <list>
            <total_no>1</total_no>
            <no>1</no>
            <pplid>PPL_6JOa_A1397_1_0005792</pplid>
            <uci>G002+AKS-KHF_12C138C885FFFFB1397X0</uci>
            <title>세종</title>
            <document>
               <통합인명메타 UCI="G002+AKS-KHF_12C138C885FFFFB1397X0" id="PPL_6JOa_A1397_1_0005792">
                  <시대>조선 전기</시대>
                  <분류정보 번호="1">
                     <분류 level="1">왕실</분류>
                     <분류 level="2">왕</분류>
                     <분류 level="3">왕</분류>
                  </분류정보>
                  <성별>남</성별>
                  <나이>54</나이>
                  <인명정보>
                     <인명 식별자="" 유형="시호" 한글음="장헌">莊憲</인명>
                     <인명 NO="5792" 유형="묘호" 표시="대표" 한글음="세종">世宗</인명>
                     <인명 식별자="" 유형="성명" 한글음="이도">李祹</인명>
                     <인명 식별자="" 유형="이칭" 한글음="세종대왕">世宗大王</인명>
                  </인명정보>
                  <생몰년정보>
                     <생년>
                        <연도 시대구분="A">1397</연도>
                        <왕대>태조 6</왕대>
                        <간지/>
                        <세기/>
                     </생년>
                     <몰년>
                        <연도 시대구분="A">1450</연도>
                        <왕대>세종 32</왕대>
                        <간지/>
                        <세기/>
                     </몰년>
                  </생몰년정보>
                  <본관 id="N539" 식별자="" 한글음="전주">全州</본관>
                  <가족관계정보>
                     <인명 PPLID="" 관계="부" 식별자="" 유형="묘호" 한글음="태종">太宗</인명>
                     <인명 PPLID="" 관계="모" 식별자="" 유형="시호" 한글음="태종">太宗</인명>
                  </가족관계정보>
                  <공간정보 관계="" 유형="">
                     <지명 관계="출신지" 유형="">평안남도 평양</지명>
                  </공간정보>
                  <관련사건>
                     <사건>105인사건</사건>
                  </관련사건>
               </통합인명메타>
            </document>
         </list>
      </resultSet>
   </resultInfo>
</aksPeopleAPI>

4. 역대인물 OpenAPI 활용 예시

(1) XML 방식

예시화면

샘플소스 
var apiKey = "857f940ccd144a87ba118e0d4499e331"; // 인증키
try {
	$.post("/openapi",  // 역대인물 OpenAPI 호출 URL
	{
		key : apiKey,  // 인증키
		query:"PPL_6JOa_A1397_1_0005792", // 역대인물 등록번호를 검색어로 사용
		category:"pplid", // 검색 범위는 역대인물 ID 검색을 위한 pplid 사용
		startPage:1,  // 시작페이지 설정
		pageSize:50,  // 페이지 크기 설정
		startHilightTag:"",  // 하이라이트 시작 태그
		endHilightTag:"", // 하이라이트 종료 태그
		format:"xml" // xml 형식 프로토콜 사용
	},
	function(xml) {  // 검색 결과를 받는 함수
		xsl=loadXMLDoc("/openapi/openapi.xsl"); // test용 openapi xslt 파일 지정
		if (window.ActiveXObject) // IE인 경우
		{
			// xsl파일을 적용하여 XML을 Html로 변환한다.
			htmlString = xml.transformNode(xsl);
		}
		// code for Mozilla, Firefox, Opera, etc.
		else if (document.implementation && document.implementation.createDocument)
		{
			xsltProcessor=new XSLTProcessor();

			// xsl파일을 적용하여 XML을 Html로 변환한다
			xsltProcessor.importStylesheet(xsl);
			htmlString = xsltProcessor.transformToFragment(xml,document);
		}
		// 변환된 html을 팝업 창에 삽입한다.
		popWinBody.innerHTML = htmlString ;

	}
	,"xml"); // AJAX 통신 결과를 XML형식을 받는다.(JQuery 문법)
} catch(e) {
	window.status = e;
}
예제 XSL 보기
활용예
아래 글이 여러 분이 쓴 글일 경우, “세종대왕”에 마우스를 올리면 세종대왕에 대한 정보를 볼 수 있도록 할 수 있습니다.
예제 소스 보기
조선 세종 때 최윤덕(崔潤德) 등을 보내 여진족(女眞族)을 토벌하고 압록강 상류의 여연(閭延)ㆍ자성 (慈城)ㆍ무창(茂昌)ㆍ우예(虞芮)의 4군을 설치했는데, 뒤에 그 유지ㆍ확보가 용이하지 못하다는 이유에서 철폐론이 제기되어오다가 단종ㆍ세조 때에 걸쳐 드디어 철폐되자, 그후 이 지방은 오랫동안 폐사군이라 불리게 되었다. 세종대왕은...

(2) JSON 방식

예시화면

샘플소스 
var apiKey = "857f940ccd144a87ba118e0d4499e331"; // 인증키
try {
	$.post("/openapi",  // 역대인물 OpenAPI 호출 URL
	{
		key : apiKey,  // 인증키
		query:"이순신", // 검색어
		category:"total", // 검색 범위
		startPage:1,  // 시작페이지 설정
		pageSize:50,  // 페이지 크기 설정
		startHilightTag:"",  // 하이라이트 시작 태그
		endHilightTag:"", // 하이라이트 종료 태그
		format:"json" // xml 형식 프로토콜 사용
	},
	function(data) {  // data는 json 객체이다.
		var result = data[0].resultInfo; // resultInfo 셋 정보를 가져온다.

		if (result.success == "false") // 실패인 경우 오류 메세지를 출력한다.
		{
		alert(result.message);
		return;
		}
		var resultHtml = "";
		if (result.totalCount == 0) // totalCount가 0 이면 검색결과 건수가 없다.
		{
		resultHtml = resultHtml + "<tr><d align='center'>검색된 결과가 없습니다.</td><tr>";
		}
		else {
		var list = result.resultSet; // resultSet은 Array형식으로 list 객제를 가지고 있다.
		for (i = 0; i < result.resultSize; i++) // resultSize값 만큼 반복하여 list 구조체를
													 출력한다.
		{
			  var livedie = list[i].document.통합인명메타.생몰년정보.생년.연도["#text"];
			  livedie = "  (" +livedie + " ~ " +
								 list[i].document.통합인명메타.생몰년정보.생년.연도["#text"] + ")";
			  resultHtml = resultHtml + "<tr><td align='left'> ["+
							 list[i].document.통합인명메타.시대+ "] "+  list[i].title+ livedie +
							 "<br>";
			  var d = "";
				   // 인명 정보를 처리한다.
			  for (j =0; j < list[i].document.통합인명메타.인명정보.length; j++)
			  {
				  var s = list[i].document.통합인명메타.인명정보[j];
				  d = d + getPeopleName(s);
			  }
			  resultHtml = resultHtml + d+"</td><td valign='bottom' align='right'>[
							 <a href=\"javascript: parent.showAksPeople('"+list[i].pplid +
							 "');\">자세히보기</a> ]</td><tr>";
			  resultHtml = resultHtml + "<tr><td colspan=2 height=1
							 bgColor='#AAAAAA'></td></tr>";
		   }
		} // end else
		// 생성된 HTML을 팝업 창에 삽입한다.
		openResultPopup(resultHtml);
	 },"json");  // AJAX 통신 결과를 JSON형식을 받는다.(JQuery 문법)
} catch(e) {
	window.status = e;
}
활용예
아래 글이 여러 분이 쓴 글일 경우, “세종”을 마우스로 “긁어서 선택“하면 나오는 검색버튼을 누르면 검색 결과를 볼 수 있도록 할 수 있습니다.

예제 소스 보기
조선 세종 때 최윤덕(崔潤德) 등을 보내 여진족(女眞族)을 토벌하고 압록강 상류의 여연(閭延)ㆍ자성(慈城)ㆍ무창 (茂昌)ㆍ우예(虞芮)의 4군을 설치했는데, 뒤에 그 유지ㆍ확보가 용이하지 못하다는 이유에서 철폐론이 제기되어오다가 단종ㆍ세조 때에 걸쳐 드디어 철폐되자,